\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename twelf.info
@settitle Twelf User's Guide 
@setchapternewpage odd
@set VERSION 1.4
@set UPDATED December 27, 2002
@c @set VERSION 1.3
@c @set UPDATED September 13, 2000
@c @set VERSION 1.2
@c @set UPDATED August 27, 1998
@syncodeindex fn cp
@c %**end of header

@titlepage
@title Twelf User's Guide
@subtitle Version @value{VERSION}
@author Frank Pfenning and Carsten Schuermann

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998, 2000, 2002 Frank Pfenning and Carsten Schuermann
@end titlepage

@node Top, Introduction, (dir), (dir)

@ifinfo
This document describes the Twelf User's Guide, Version @value{VERSION},
Last updated @value{UPDATED}.
@end ifinfo

@menu
* Introduction::                Getting started
* Lexical Conventions::         Reserved characters and identifiers
* Syntax::                      Grammar of signatures
* Term Reconstruction::         Checking and inferring types 
* Logic Programming::           How to interpret signatures as programs
* Constraint Domains::          Using rationals and integers
* Modes::                       Input/output behavior of relations
* Termination::                 Verifying termination of programs
* Coverage::                    Checking that all cases are covered
* Theorem Prover::              Proving theorems and meta-theorems
* ML Interface::                Running Twelf from ML
* Twelf Server::                A stand-alone Twelf command interpreter
* Emacs Interface::             Editing Twelf files
* Installation::                How to install Twelf
* Examples::                    Guide to standard examples
* History::                     Differences between Elf 1.5 and Twelf
* Index::                       Index to this guide

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* New Features::                Differences from Twelf 1.2
* Quick Start::                 Sample interaction with Twelf

Lexical Conventions

* Reserved Characters::         Characters separating identifiers
* Identifiers::                 Interpretation of identifiers

Syntax

* Grammar::                     The grammar of Twelf
* Constructor Declaration::     Introducing types and object constructors
* Definitions::                 Notational definitions and abbreviations
* Operator Declaration::        Infix, prefix and postfix operators
* Name Preferences::            Assigning names to anonymous variables
* Sample Signature::            Example of First-Order Logic

Term Reconstruction

* Implicit Quantifiers::        Free variables in declarations
* Implicit Arguments::          Omitted arguments to constants
* Strict Occurrences::          A sufficient condition for principal types
* Strict Definitions::          Reconstruction on definitions
* Type Ascription::             Disambiguating terms
* Error Messages::              When things go wrong
* Tracing Reconstruction::      Seeing what happens during reconstruction

Logic Programming

* Query Declaration::           Checking expected numbers of solutions
* Solve Declaration::           Naming proof terms found by search
* Interactive Queries::         Twelf's interactive top-level
* Sample Trace::                An example how search works
* Operational Semantics::       How queries are executed in some detail
* Sample Program::              Type inference for a lambda-calculus
* Clause Definitions::          How to use definitions for search
* Deterministic Type Families::  How to prune unwanted solutions 
* Tabled Logic Programming::    Executing queries with memo tables

Constraint Domains

* Installing an Extension::     Making constraint domains available
* Equalities of Rational Numbers::  Rationals with equality
* Inequalities over Rational Numbers::  Rationals with equality and inequality
* Integer Constraints::         Integers with equality and inequality
* Equalities over Strings::     Strings and concatenation
* 32-bit Integers::             Integers representable as string of 32 bits
* Sample Constraint Programs::  Some examples of use
* Restrictions and Caveats::    Alerts!

Modes

* Short Mode Declaration::      Common form for modes
* Full Mode Declaration::       Fully explicit modes
* Mode Checking::               Checking mode correctness

Termination

* Termination Declaration::     Checking termination
* Reduction Declaration::       Checking outputs are smaller than inputs
* Subterm Ordering::            Higher-order subterms
* Lexicographic Orders::        Termination by nested induction
* Simultaneous Orders::         Termination by simultaneous induction
* Mutual Recursion::            Termination of mutually recursive predicates

Coverage

* Regular Worlds::              Characterizing parameters and hypotheses
* Input Coverage::              Checking if all cases have been covered
* Totality::                    Verifying if a family is total in its input
* Subordination::               How constants depend on each other

Theorem Prover

* Theorem Declaration::         Declaring and proving theorems
* Sample Theorems::             Two examples
* Proof Steps::                 Basic operations of the prover
* Search Strategies::           How Twelf searches
* Proof Realizations::          Using automatically constructed proofs 

ML Interface

* Configurations::              Managing groups of Twelf files
* Loading Files::               Loading individual files
* Environment Parameters::      Controlling appearance and verbosity of Twelf
* Signature Printing::          Printing of signatures
* Tracing and Breakpoints::     Debugging tools
* Timing Statistics::           Gathering statistics
* Twelf Signature::             The top-level signature

Twelf Server

* Server Types::                Server command argument types
* Server Commands::             List of Twelf server commands

Emacs Interface

* Twelf Mode::                  Major mode for editing Twelf sources
* Editing Commands::            Automatic indentation
* Type Checking Commands::      Checking declarations, files, configurations
* Printing Command::            Printing signatures
* Tracing Commands::            Debugging tools
* Error Tracking::              Jumping to error locations
* Server State::                Changing server parameters
* Info File::                   Reading this documentation
* Tags Files::                  Tagging Twelf sources
* Twelf Timers::                Obtaining runtime statistics from server
* Twelf-SML Mode::              Running Twelf under SML in Emacs
* Emacs Variables::             Customizing Twelf mode
* Syntax Highlighting::         Using multiple fonts for Twelf code
* Emacs Initialization::        For the .emacs file
* Command Summary::             Summary of Twelf mode commands

@end detailmenu
@end menu

@node Introduction, Lexical Conventions, Top, Top
@chapter Introduction

@cindex logical framework
@cindex LF
@cindex Twelf home page
@cindex typographical conventions
@cindex file names

Twelf is the current version of a succession of implementations of
the logical framework LF.  Previous systems include Elf (which
provided type reconstruction and the operational semantics reimplemented
in Twelf) and MLF (which implemented module-level constructs loosely
based on the signatures and functors of ML still missing from Twelf).

Twelf should be understood as research software. This means comments,
suggestions, and bug reports are extremely welcome, but there are no
guarantees regarding response times.  The same remark applies to these
notes which constitute the only documentation on the present Twelf
implementation.

For current information including download instructions, publications,
and mailing list, see the Twelf home page at
@t{http://www.cs.cmu.edu/~twelf/}.  This User's Guide is published as
@display
 Frank Pfenning and Carsten Schuermann
 @emph{Twelf User's Guide}
 Technical Report CMU-CS-98-173, Department of Computer Science, 
 Carnegie Mellon University, November 1998.
@end display

@ifhtml
<UL>
 <LI> <A HREF="http://www.cs.cmu.edu/~twelf/">Twelf Home Page</A> </LI>
</UL>
@end ifhtml

Below we state the typographic conventions in this manual.

@table @asis
@item @code{code}
  for Twelf or ML code
@item @samp{samp}
  for characters and small code fragments
@item @var{metavar}
  for placeholders in code
@item @kbd{keyboard}
  for input in verbatim examples
@item @key{key}
  for keystrokes
@item @math{math}
  for mathematical expressions
@item @emph{emph}
  for emphasized phrases
@end table

File names for examples given in this guide are relative to the main
directory of the Twelf installation.  For example
@file{examples/guide/nd.elf} may be found in
@*@file{/usr/local/twelf/examples/guide/nd.elf} if Twelf was installed
into the @file{/usr/local/} directory.

@menu
* New Features::                Differences from Twelf 1.2
* Quick Start::                 Sample interaction with Twelf
@end menu

@node New Features, Quick Start, Introduction, Introduction
@section New Features

The current version @value{VERSION} from @value{UPDATED} incorporates
the following major changes from Twelf 1.3 from September 13, 2000.

@table @asis
@item World Checking (@pxref{Regular Worlds}).
 World checking verifies regularity of the parameters and hypothesis
that can be introduced by terms in a signature.  The new declarations
are @code{%block} and @code{%worlds}.  This formally checks part of the
adequacy theorem that is usually left implicit in the encoding and is is
used centrally by the coverage checker.

@item Coverage and Totality Checking (@pxref{Coverage}, @pxref{Totality}).
 Proofs of meta-theorems given in relational form can now be verified if
they are of order 2 or less.  The new relevant declarations are
@code{%covers} and @code{%total}.  The former can also be used to check
that sets of patterns in the arguments of a type family are exhaustive.

@item Mode Checking (@pxref{Modes})
 Mode checking has been extended so that multiple modes can be checked
for the same predicate, even though not simultaneously.  This allows
certain relations to serve as proofs for biconditional meta-theorems.
Also, some predicates in constraint domains can have multiple modes
simultaneously in effect.

@item Tabled Search (@pxref{Tabled Logic Programming})
 An experimental logic programming engine for tabled logic programming
is available in this release.  The corresponding declarations
are @code{%tabled @var{a}} (to declare a type family to be tabled)
and @code{%querytabled} to start tabled search.

@item Deterministic Search (@pxref{Deterministic Type Families})
 Type families can be declared deterministic for search, which means
that after the first solution has been found, backtracking will
not find any further solutions.  The relevant declaration is
@code{%deterministic @var{a}}.

@item Family-Level Definitions (@pxref{Clause Definitions})
 Twelf now permits family-level definitions that are opaque to logic
programming execution.  However, not all aspects of the present release
handle them properly, so they should be considered an experimental
feature.  Furthermore, defined constants will now be used for
logic programming search when prefixed with @code{%clause}.

@item Tracing Term Reconstruction (@pxref{Tracing Reconstruction})
 Term reconstruction can print each typing judgment it establishes
in order to help diagnose subtle type errors or ambiguities.

@item Portability (@pxref{Installation})
 Twelf has been ported to be compliant with the Definition of Standard
ML in its 1997 revision.  As a result, it now supports Poly/ML
and MLton in addition to Standard ML of New Jersey (SML/NJ).
@end table

@node Quick Start,  , New Features, Introduction
@section Quick Start

Assuming you are running on a Unix system with SML of New Jersey 110.0.3
already installed (@pxref{Installation}) you can build Twelf as follows.  Here
@samp{%} is assumed to be the shell prompt.  You may need to edit the
file @file{Makefile} to give the proper location for @code{sml}.

@example
@group
% @kbd{gunzip twelf-1-4.tar.gz}
% @kbd{tar -xf twelf-1-4.tar}
% @kbd{cd twelf}
% @kbd{make}
% @kbd{bin/twelf-server}
Twelf 1.4, Dec 27 2002
%% OK %%
@end group
@end example

For SML/NJ version 110.20 or greater, use @kbd{make -f smlnj/Makefile}.
For Poly/ML use @kbd{make -f polyml/Makefile}.  For MLton use
@kbd{make -f mlton/Makefile}.

You can now load the examples used in this guide and pose an example
query as shown below.  The prompt from the Twelf top-level is @samp{?-}.
To drop from the Twelf top-level to the ML top-level, type @kbd{C-c}
(@key{CTRL} @kbd{c}).  To exit the Twelf server you may issue the
@code{quit} command or type @kbd{C-d} (@key{CTRL} @kbd{c}).

@example
@group
@kbd{make examples/guide/sources.cfg}
@kbd{top}
?- @kbd{of (lam [x] x) T.}
Solving...
T = arrow T1 T1.
More? @kbd{y}
No more solutions
?- @kbd{C-c}
interrupt
%% OK %%
@kbd{quit}
%
@end group
@end example

@node Lexical Conventions, Syntax, Introduction, Top
@chapter Lexical Conventions

Lexical analysis of Twelf has purposely been kept simple, with few
reserved characters and identifiers.  As a result one may need to use
more whitespace to separate identifiers than in other languages.  For
example, @samp{A->B} or @samp{A+B} are single identifiers, while @samp{A
-> B} and @samp{A + B} both consist of 3 identifiers.

During parsing, identifiers are resolved as reserved identifiers,
constants, bound variables, or free variables, following the usual rules
of static scoping in lambda-calculi.

@menu
* Reserved Characters::         Characters separating identifiers
* Identifiers::                 Interpretation of identifiers
@end menu

@node Reserved Characters, Identifiers, Lexical Conventions, Lexical Conventions
@section Reserved Characters

@cindex reserved characters
@cindex characters, reserved

The following table lists the reserved characters in Twelf.

@table @asis
@item @samp{:}
    colon, constant declaration or ascription

@item @samp{.}
    period, terminates declarations

@item @samp{(} @samp{)}
    parentheses, for grouping terms

@item @samp{[} @samp{]}
    brackets, for lambda abstraction

@item @samp{@{} @samp{@}}
    braces, for quantification (dependent function types)

@item @var{whitespace}
    separates identifiers; one of space, newline, tab, carriage return,
    vertical tab or formfeed

@item @samp{%}
    introduces comments or special keyword declarations

@table @asis
@item @samp{%@var{whitespace}} @samp{%%}
      comment terminated by the end of the line, may contain any characters

@item @samp{%@{} @samp{@}%}
      delimited comment, nested @samp{%@{} and @samp{@}%} must match

@item @samp{%@var{keyword}}
      various declarations

@item @samp{%.}
      end of input stream
@end table

@item @samp{"}
    doublequote, disallowed

@item other printing characters
    identifier constituents
@end table

@node Identifiers,  , Reserved Characters, Lexical Conventions
@section Identifiers

@cindex reserved identifiers
@cindex identifiers, reserved
@cindex case, upper and lower
@cindex backquote, before variables

All printing characters that are not reserved can be included in
identifiers, which are separated by whitespace or reserved characters.
In particular, @code{A->B} is an identifier, whereas @code{A -> B}
stands for the type of functions from @code{A} to @code{B}.

An uppercase identifier is one which begins with an underscore @samp{_} or
a letter in the range @samp{A} through @samp{Z}.  A lowercase identifier
begins with any other character except a reserved one.  Numbers also
count as lowercase identifiers and are not interpreted specially.  Free
variables in a declaration must be uppercase, bound variables and
constants may be either uppercase or lowercase identifiers.

There are also a small number of
reserved identifiers with a predefined meaning which
cannot be changed.  Keep in mind that these can be constituents of other
identifers which are not interpreted specially.

@table @samp
@item ->
          function type
@item <-
          reverse function type
@item _
          hole, to be filled by term reconstruction
@item =
          definition
@item type
          the kind @math{type}
@end table

Constants have static scope, which means that they can be shadowed by
subsequent declarations.  A shadowed identifier (which can no longer be
referred to in input) is printed as @code{%@var{id}%}.  The printer for
terms renames bound variables so they do not shadow constants.

Free uppercase identifiers in declarations represent schematic
variables.  In order to distinguish them from other kinds of variables
and constants they are printed as @samp{'@var{id}} (backquote, followed
by the identifer name) in error messages.

@node Syntax, Term Reconstruction, Lexical Conventions, Top
@chapter Syntax

@cindex objects
@cindex types
@cindex kinds
@cindex type families

In LF, deductive systems are represented by signatures consisting of
constant declarations.  Twelf implements declarations in a
straightforward way and generalizes signatures by also allowing
definitions, which are semantically transparent.  Twelf currently
does not have module-level constructs so that, for example, signatures
cannot be named.  Instead, multiple signatures can be manipulated in the
programming environment using configurations (@pxref{Configurations}).

The LF type theory which underlies LF is stratified into three levels:
objects @math{M} and @math{N}, types @math{A} and @math{B}, and kinds
@math{K}@.  Twelf does not syntactically distinguish these levels and
simply uses one syntactic category of term.  Similarly, object-level
constants @math{c} and type-level constants @math{a} as well as
variables share one name space of identifiers.

In explanations and examples we will use letters following the
mathematical conventions above to clarify the roles of various terms.
We also use @math{U} and @math{V} to stand for arbitrary terms.

@menu
* Grammar::                     The grammar of Twelf
* Constructor Declaration::     Introducing types and object constructors
* Definitions::                 Notational definitions and abbreviations
* Operator Declaration::        Infix, prefix and postfix operators
* Name Preferences::            Assigning names to anonymous variables
* Sample Signature::            Example of First-Order Logic
@end menu

@node Grammar, Constructor Declaration, Syntax, Syntax
@section Grammar

@cindex declarations

The grammar below defines the non-terminals @code{sig}, @code{decl},
@code{term} and uses the terminal @code{id} which stands for identifers
(@pxref{Identifiers}).  The comments show the meaning in LF@.  There are
various special declarations @code{%@var{keyword}} such as @code{%infix}
or @code{%theorem} which are omitted here and detailed in the
appropriate sections.

@cindex signature
@cindex declaration
@cindex term

@comment Because of a bug in the texinfo to dvi translation
@comment the operators below are not given as references.

@example
@group
sig  ::=                       % @r{Empty signature}
       | decl sig              % @r{Constant declaration}

decl ::= id : term.            % @r{@math{a : K}  or  @math{c : A}}
       | defn.                 % @r{definition, usually @math{d : A = M}}
       | %abbrev adecl.        % @r{abbreviation}
       | %infix ixdecl.        % @r{operator declaration}
       | %prefix pxdecl.       % @r{operator declaration}
       | %postfix pxdecl.      % @r{operator declaration}
       | %name namepref.       % @r{name preference declaration}
       | %query qdecl.         % @r{query declaration}
       | %clause defn.         % @r{clause definition}
       | sdecl.                % @r{solve declaration}
       | %tabled id.           % @r{table declaration}
       | %querytabled qtdecl   % @r{tabled query declaration}
       | %deterministic ddecl. % @r{deterministic declaration}
       | %mode mdecl.          % @r{mode declaration}
       | %terminates tdecl.    % @r{termination declaration}
       | %reduces rdecl.       % @r{reduction declaration}
       | %block id : bdecl.    % @r{block declaration}
       | %worlds wdecl.        % @r{worlds declaration}
       | %total tdecl.         % @r{totality declaration}
       | %freeze ids.          % @r{freeze declaration}
       | %theorem thdecl.      % @r{theorem declaration}
       | %prove pdecl.         % @r{prove declaration}
       | %establish pdecl.     % @r{prove declaration, do not use as lemma later}
       | %assert callpats.     % @r{assert theorem (requires @code{Twelf.unsafe})}
       | %use domain.          % @r{installs constraint domain}

defn ::= id : term = term      % @r{@math{d : A = M} or @math{d : K = A}}
       | id = term             % @r{@math{d = M} or @math{d = A}}
       | _ : term = term       % @r{anonymous definition, for type-checking}
       | _ = term              % @r{anonymous definition, for type-checking}

sdecl ::= %define binding sdecl % @r{term binding}
        | %solve id : term      % @r{solve with proof term}
        | %solve _ : term       % @r{solve without proof term}

ids   ::=                      % @r{empty sequence}
        | id ids               % @r{identifier follwed by more}
@end group

@group
term ::= type                  % @math{type}
       | id                    % @r{variable @math{x} or constant @math{a} or @math{c}}
       | term -> term          % @math{A} @t{->} @math{B}
       | term <- term          % @r{@math{A} @t{<-} @math{B}, same as @math{B} @t{->} @math{A}}
       | @{id : term@} term    % @r{@math{Pi x:A. K}  or  @math{Pi x:A. B}}
       | [id : term] term      % @r{@math{lambda x:A. B}  or  @math{lambda x:A. M}}
       | term term             % @r{@math{A M}  or  @math{M N}}
       | term : term           % @r{explicit type ascription}
       | _                     % @r{hole, to be filled by term reconstruction}
       | @{id@} term           % @r{same as @code{@{id:_@}} term}
       | [id] term             % @r{same as @code{[id:_]} term}
@end group
@end example

The constructs @code{@{x:U@} V} and @code{[x:U] V} bind the identifier
@code{x} in @code{V}, which may shadow other constants or bound
variables.  As usual in type theory, @code{U -> V} is treated as an
abbreviation for @code{@{x:U@} V} where @code{x} does not appear
in @code{V}.  However, there is a subtlety in that the latter allows
an implicit argument (@pxref{Implicit Arguments}) to depend on
@code{x} while the former does not.

In the order of precedence, we disambiguate the syntax as follows:

@enumerate
@item Juxtaposition (application) is left associative and has highest precedence.

@item User declared infix, prefix, or postfix operators (see below).

@item @samp{->} is right and @samp{<-} left associative with equal precedence.

@item @samp{:}  is left associative.

@item @samp{@{@}} and @samp{[]} are weak prefix operators.
@end enumerate

For example, the following are parsed identically:

@example
@group
   d : a <- b <- @{x@} c x -> p x.
   d : (@{x@} c x -> p x) -> b -> a.
   d : ((a <- b) <- (@{x:_@} ((c x) -> (p x)))).
@end group
@end example

@node Constructor Declaration, Definitions, Grammar, Syntax
@section Constructor Declaration

@cindex variable scope
@cindex free variables
@cindex bound variables
@cindex variables, free
@cindex variables, bound

New type families or object constructors can be introduced with

@example
condec ::= id : term.    % @r{@math{a : K} or @math{c : A}}
@end example

Here @code{a} stands for a type family and @code{K} for its kind,
whereas @code{c} is an objects constructor and @code{A} its type.
Identifiers are resolved as follows:

@enumerate
@item Any identifier @code{x} may be bound by the innermost enclosing binder
for @code{x} of the form @code{@{x:A@}} or @code{[x:A]}.

@item Any identifer which is not explicitly bound may be a declared or
defined constant.

@item Any uppercase identifier, that is, identifier
starting with @samp{_} (underscore) or an upper case letter, may be
a free variable.  Free variables are interpreted universally and their
type is inferred from their occurrences (@pxref{Term Reconstruction}).

@item Any other undeclared identifier is flagged as an error.
@end enumerate

@node Definitions, Operator Declaration, Constructor Declaration, Syntax
@section Definitions

@cindex definitions
@cindex abbreviations
@findex %abbrev

Twelf supports notational definitions and abbreviations.  Semantically,
both are completely transparent, that is, both for type checking
and the operational semantics, definitions may be expanded.

@example
@group
adecl ::= id : term = term         % @r{@math{d : A = M}}
        | id = term                % @r{@math{d = M}}

defn ::= adecl.                    % @r{definition}
       | %abbrev adecl.            % @r{abbreviation}
@end group
@end example

@noindent
where the second form of declaration is equivalent to @code{id : _ =
term}.  Definitions or abbreviations at the level of type
families are permitted, but are somewhat experimental in the
present release.

In order to avoid the expansion of defined constants as much as
possible, declarations @code{id : term = term.} must be strict
(@pxref{Strict Definitions}).  A definition of a constant @code{c} is
strict if all arguments to @code{c} (implicit or explicit) have at least
one strict occurrence (@pxref{Strict Occurrences}) in the right-hand
side of the definition, and the right-hand side contains at least one
constant.  In practice, most notational definitions are strict.  For
some examples, see @ref{Sample Signature} and @ref{Strict Definitions}.
Twelf tries to preserve strict definitions as much as possible, instead
of expanding them.

The @code{%abbrev} declaration defines an @emph{abbreviation}
which need not be strict.  However, it will be expanded immediately
upon parsing and will not be used in output.

The power of definitions in Twelf, however, is severely limited by the
lack of recursion.  It should only be thought of as notational
definition, not as a computational mechanism.  Complex operations need
to be defined as logic programs, taking advantage of the operational
semantics assigned to signatures (@pxref{Logic Programming}).

@node Operator Declaration, Name Preferences, Definitions, Syntax
@section Operator Declaration

@cindex declarations, operator
@cindex operator declarations
@cindex precedence

@findex %infix
@findex %prefix
@findex %postfix
@findex none
@findex left
@findex right

The user may declare constants to be infix, prefix, or postfix
operators.  Operator precedence properties are associated with
constants, which must therefore already have been declared with a type
or kind and a possible definition.  It is illegal to shadow an infix,
prefix, or postfix operator with a bound variable.  We use
@code{nat} for the terminal natural numbers.

@example
@group
assoc ::= none   % @r{not associative}
        | left   % @r{left associative}
        | right  % @r{right associative}

prec ::= nat     % @r{0 @t{<=} @t{prec} @t{<} 10000}
@end group

@group
ixdecl ::= assoc prec id

pxdecl ::= prec id

decl ::= @dots{}
       | %infix ixdecl.
       | %prefix pxdecl.
       | %postfix pxdecl.
@end group
@end example

During parsing, ambiguous successive operators of identical precedence
such as @code{a <- b -> c} are flagged as errors.  Note that it is not
possible to declare an operator with equal or higher precedence than
juxtaposition or equal or lower precedence than @samp{->} and @samp{<-}.

@node Name Preferences, Sample Signature, Operator Declaration, Syntax
@section Name Preferences

@cindex name preferences
@cindex declarations, name preference
@cindex variable naming
@findex %name

During printing, Twelf frequently has to assign names to anonymous
variables.  In order to improve readability, the user can declare a name
preference for anonymous variables based on their type.  Thus name
preferences are declared for type family constants.  Note that name
preferences are not used to disambiguate the types of identifiers during
parsing.

@example
@group
namepref ::= id        % @r{existential variables}
           | id id     % @r{existential variables, parameters}

decl ::= @dots{}
       | %name id namepref.
@end group
@end example

Following our same conventions, a name preference declaration has the
form @code{%name @var{a} @var{id}}, that is, the first identifier must
be a type family already declared and the second is the name preference
for variables of type @var{a}.  The second identifier must be uppercase,
that is, start with a letter from @samp{A} through @samp{Z} or an
underscore @samp{_}.  Anonymous variables will then be named
@code{@var{id}@math{1}}, @code{@var{id}@math{2}}, etc.

In the second form, we can give a separate name preference
for free (existential) variables and parameters.  The second one
will typically be lowercase, as in @code{%name exp E x}.

@node Sample Signature,  , Name Preferences, Syntax
@section Sample Signature

@cindex natural deduction

Below is a signature for intuitionistic first-order logic over an
unspecified domain of individuals and atomic propositions.  It
illustrates constant declarations and definitions and the use of
operator precedence and name preference declarations.  It may be found
in the file @file{examples/guide/nd.elf}.

@example
@group
%%% Individuals
i : type.                   %name i T

%%% Propositions
o : type.                   %name o A

imp    : o -> o -> o.       %infix right 10 imp
and    : o -> o -> o.       %infix right 11 and
true   : o.
or     : o -> o -> o.       %infix right 11 or
false  : o.
forall : (i -> o) -> o.
exists : (i -> o) -> o.

not : o -> o = [A:o] A imp false.

%%% Natural Deductions

nd : o -> type.             %name nd D

impi    : (nd A -> nd B) -> nd (A imp B).
impe    : nd (A imp B) -> nd A -> nd B.
andi    : nd A -> nd B -> nd (A and B).
ande1   : nd (A and B) -> nd A.
ande2   : nd (A and B) -> nd B.
truei   : nd (true).
% no truee
ori1    : nd A -> nd (A or B).
ori2    : nd B -> nd (A or B).
ore     : nd (A or B) -> (nd A -> nd C) -> (nd B -> nd C) -> nd C.
% no falsei
falsee  : nd false -> nd C.
foralli : (@{x:i@} nd (A x)) -> nd (forall A).
foralle : nd (forall A) -> @{T:i@} nd (A T).
existsi : @{T:i@} nd (A T) -> nd (exists A).
existse : nd (exists A) -> (@{x:i@} nd (A x) -> nd C) -> nd C.

noti : (nd A -> nd false) -> nd (not A)
     = [D:nd A -> nd false] impi D.
note : nd (not A) -> nd A -> nd false
     = [D:nd (not A)] [E:nd A] impe D E.
@end group
@end example

@node Term Reconstruction, Logic Programming, Syntax, Top
@chapter Term Reconstruction

@cindex term reconstruction
@cindex type reconstruction

Representations of deductions in LF typically contain a lot of redundant
information.  In order to make LF practical, Twelf gives the user the
opportunity to omit redundant information in declarations and
reconstructs it from context.  Unlike for functional languages, this
requires recovering objects as well as types, so we refer to this phase
as term reconstruction.

There are criteria which guarantee that the term reconstruction problem
is decidable, but unfortunately these criteria are either very
complicated or still force much redundant information to be supplied.
Therefore, the Twelf implementation employs a reconstruction algorithm
which always terminates and gives one of three answers:

@enumerate
@item yes, and here is the most general reconstruction;

@item no, and here is the problem; or

@item maybe.
@end enumerate

The last characterizes the situations where there is insufficient
information to guarantee a most general solution to the term reconstruction
problem.  Because of the decidable nature of type-checking in LF, the user
can always annotate the term further until it falls into one of the
definitive categories.

@menu
* Implicit Quantifiers::        Free variables in declarations
* Implicit Arguments::          Omitted arguments to constants
* Strict Occurrences::          A sufficient condition for principal types
* Strict Definitions::          Reconstruction on definitions
* Type Ascription::             Disambiguating terms
* Error Messages::              When things go wrong
* Tracing Reconstruction::      Seeing what happens during reconstruction
@end menu

@node Implicit Quantifiers, Implicit Arguments, Term Reconstruction, Term Reconstruction
@section Implicit Quantifiers

@cindex implicit quantifiers
@cindex quantifiers, implicit

The model of term reconstruction employed by Twelf is
straightforward, although it employs a relatively complex algorithm.
The basic principle is a duality between quantifiers omitted in a
constant declaration and implicit arguments where the constant is used.
Recall some definitions in the signature defining natural deductions
(@pxref{Sample Signature}).

@example
o : type.
and : o -> o -> o.   %infix right 10 and
nd : o -> type.
andi : nd A -> nd B -> nd (A and B).
@end example

The last declaration contains @code{A} and @code{B} as free variables.
Type reconstruction infers most general types for the free variables in
a constant declaration and adds implicit quantifiers.  In the example
above, @code{A} and @code{B} must both be of type @code{o}.  The
internal form of the constant thus has one of the following two forms.

@example
@group
andi : @{A:o@} @{B:o@} nd A -> nd B -> nd (A and B).
andi : @{B:o@} @{A:o@} nd A -> nd B -> nd (A and B).
@end group
@end example

These forms are printed during type reconstruction, so the user can
examine if the result of reconstruction matches his expectations.

@node Implicit Arguments, Strict Occurrences, Implicit Quantifiers, Term Reconstruction
@section Implicit Arguments

@cindex implicit arguments
@cindex arguments, implicit

The quantifiers on @code{A} and @code{B} in the declaration

@example
andi : nd A -> nd B -> nd (A and B).
@end example

@noindent
were implicit.  The corresponding arguments to @code{andi} are also
implicit.  In fact, since the order of the reconstructed quantifiers is
arbitrary, we cannot know in which order to supply the arguments, so
they must always be omitted.  Thus a constant with @math{n} implicit
quantifiers is supplied with @math{n} implicit arguments wherever it is
seen.  These implicit arguments are existential variables whose value
may be determined from context by unification.

For example, using also

@example
true : o.
truei: nd (true).
@end example

@noindent
we have

@example
(andi truei truei) : nd (true and true).
@end example

During parsing, the expression @code{(andi truei truei)} is interpreted
as

@example
(andi _ _ truei truei)
@end example

@noindent
where the two underscores stand for the implicit @code{A} and @code{B}
arguments to @code{andi}.  They are replaced by existential variables whose
value will be determined during type reconstruction.  We call them
@code{A1} and @code{A2} and reason as follows.

@example
@group
|- andi : @{A:o@} @{B:o@} nd A -> nd B -> nd (A and B)
|- andi A1 : @{B:o@} nd A1 -> nd B -> nd (A1 and B)
|- andi A1 A2 : nd A1 -> nd A2 -> nd (A1 and A2)
@end group
@end example

At this point, we need a to infer the type of the application
@code{(andi A1 A2) truei}.  This equates the actual type of the argument
with the expected type of the argument.

@example
@group
|- andi A1 A2 : nd A1 -> nd A2 -> nd (A1 and A2)
|- truei : nd true
------------------------------------------------
|- andi A1 A2 truei : nd A2 -> nd (A1 and A2)
   @r{where} nd true = nd A1
@end group
@end example

The equation can be solved by instantiating @code{A1} to @code{true} and
we continue:

@example
@group
|- andi true A2 truei : nd A2 -> nd (true and A2)
|- truei : nd true
------------------------------------------------
|- andi true A2 truei truei : nd (true and A2)
   @r{where} nd true = nd A2
|- andi true true truei truei : nd (true and true)
@end group
@end example

The last line is the expected result.  In this way, term reconstruction
can always be reduced to solving equations such that every solution to
the set of equations leads to a valid typing and vice versa.

@node Strict Occurrences, Strict Definitions, Implicit Arguments, Term Reconstruction
@section Strict Occurrences

@cindex strict occurrences
@cindex rigid occurrences
@cindex occurrences, strict
@cindex occurrences, rigid

Both for type reconstruction and the operational semantics, Twelf must
solve equations between objects and types.  Unfortunately, it is
undecidable if a set of equations in the LF type theory has a solution.
Worse yet, even if it has solutions, it may not have a most general
solution.  Therefore, Twelf postpones difficult equations as constraints
and solves only those within the pattern fragment (see @cite{Miller
1991, Journal of Logic and Computation} and @cite{Pfenning 1991, Logical
Frameworks}).  In this fragment, principal solutions always exist and
can be computed efficiently.  If constraints remain after term
reconstruction, the constant declaration is rejected as ambiguous which
indicates that the user must supply more type information.  We
illustrate this phenomenon and a typical solution in our natural
deduction example.

A central concept useful for understanding the finer details of type
reconstruction is the notion of a @emph{strict occurrence} of a free
variable.  We call a position in a term @emph{rigid} if it is not in the
argument of a free variable.  We then call an occurrence of a free
variable @emph{strict} if the occurrence is in a rigid position and all
its arguments (possibly none) are distinct bound variables.

If all free variable occurrences in all declarations in a signature are
strict, then term reconstruction will always either fail or succeed with
a principal solution, provided no further terms are omitted (that is,
replaced by an underscore).

If a free variable in a declaration of a constant @code{c} has no strict
occurrence at all, then its type can almost never be inferred and most uses of
@code{c} will lead to a constraint.

If a free variable has strict and non-strict occurrences then in most
cases term reconstruction will provide a definitive answer, but there is
no guarantee.  Mostly this is because most general answers simply do not
exist, but sometimes because the algorithm generates, but cannot solve
constraints with unique solutions.

We use some advanced examples from the natural deduction signature to
illustrate these concepts and ideas.  In the declarations

@example
foralli : (@{x:i@} nd (A x)) -> nd (forall A).
foralle : nd (forall A) -> @{T:i@} nd (A T).
@end example

@noindent
all free variables have a strict occurrence.  However, if we had
decided to leave @code{T} as an implicit argument,

@example
foralle : nd (forall A) -> nd (A T).
@end example

@noindent
then @code{T} has no strict occurrence.  While this declaration is
accepted as unambiguous (with @code{A:i -> o} and @code{T:i}), any
future use of @code{foralle} most likely leads to constraints on
@code{T} which cannot be solved.

@node Strict Definitions, Type Ascription, Strict Occurrences, Term Reconstruction
@section Strict Definitions

@cindex definitions, strict
@cindex strict definitions

Definitions are currently restricted so that each argument to the
defined constant, may it be implicit or explicit, must have at least one
strict occurrence in the right-hand side.  For example, the definition
of @code{not} in the signature for natural deduction (@pxref{Sample
Signature})

@example
not : o -> o = [A:o] A imp false.
@end example

@noindent
is strict since the only argument @code{A} has a strict occurrence in
@code{A imp false}.  On the other hand, the definition

@example
@group
noti : (@{p:o@} nd A -> nd p) -> nd (not A)
     = [D] impi ([u:nd A] D false u).
@end group
@end example

@noindent
which gives a possible derived introduction rule for negation is not
strict: the argument @code{D} has only one occurrence, and this occurrence
is not strict since the argument @code{false} is not a variable bound in
the body, but a constant.

However, the definitions
@example
@group
noti : (nd A -> nd false) -> nd (not A)
     = [D:nd A -> nd false] impi D.
note : nd (not A) -> nd A -> nd false
     = [D:nd (not A)] [E:nd A] impe D E.
@end group
@end example

@noindent
are both strict since arguments @code{D} and @code{E} both have strict
occurrences.  Type-checking these definitions requires that the definition
of @code{not A} is expanded to @code{A imp false}.

Note that free variables in the type and the right-hand side of a
definition are shared.  In the above example, @code{A} occurs both in
the types and the right hand side and it should be thought of as the
same @code{A}.  With the implicit quantifiers and abstractions restored,
the definitions above have the following form.

@example
@group
noti : @{A:o@} (nd A -> nd false) -> nd (not A)
   = [A:o] [D:nd A -> nd false] impi D.
note : @{A:o@} nd (not A) -> nd A -> nd false
   = [A:o] [D:nd (not A)] [E:nd A] impe D E.
@end group
@end example


@node Type Ascription, Error Messages, Strict Definitions, Term Reconstruction
@section Type Ascription

@cindex ambiguity
@cindex type ascription

In some circumstances it is useful to directly ascribe a type in order
to disambiguate declarations.  For example, the term @code{ori1 truei}
has principal type @code{nd (true or B)} for a free variable @code{B}.
If we want to constrain this to a derivation of @code{nd (true or false)}
we can write @code{ori1 truei : nd (true or false)}.

Explicit type ascription sometimes helps when the source of a type error
is particularly hard to discern: we can ascribe an expected type to a
subterm, thus verifying our intuition about constituent terms in a
declaration.

@node Error Messages, Tracing Reconstruction, Type Ascription, Term Reconstruction
@section Error Messages

@cindex error messages

When term reconstruction fails, Twelf issues an error message with the
location of the declaration in which the problem occurred and the
disagreement encountered.  A typical message is

@example
@group
examples/nd/nd.elf:37.35-37.41 Error: Type mismatch
Expected: o
Found:    (i -> o) -> o
Expression clash
@end group
@end example

@noindent
which points to an error in the file @file{examples/nd/nd.elf}, line 37,
characters 35 through 41 where an argument to a function was expected to
have type @code{o}, but was found to have type @code{(i -> o) -> o}.

If constraints remain, the error location is the whole declaration
with the message

@example
@var{filename}:@var{location} Error: Typing ambiguous -- unresolved constraints
@end example

The @var{filename} and @var{location} information can be used by Emacs
(@pxref{Emacs Interface}) to jump to the specified location in the given
file for editing of the incorrect declaration for the constant @code{c}.
The @var{location} has the form
@code{@var{line1}.@var{column1}-@var{line2}.@var{column2}} and represent
Twelf's best guess as to the source of the error.  Due to the
propagation of non-trivial constraints the source of a type
reconstruction failure can sometimes not be pinpointed very precisely.

@node Tracing Reconstruction,  , Error Messages, Term Reconstruction
@section Tracing Reconstruction

@cindex tracing reconstruction
@findex Twelf.Print.implicit
@findex Twelf.Recon.trace
@findex Twelf.Recon.traceMode
@findex Twelf.Recon.TraceMode
@findex Twelf.Recon.Progressive
@findex Twelf.Recon.Omiscient

Sometimes it is quite difficult to determine the real source of a type
error.  On such occasion there are three standard techniques that
sometimes help.  The first is to enable the printing of implicit
arguments with @code{Twelf.Print.implicit := true} and try again.  The
second is to insert explicit type annotations to limit the flexibility
of reconstruction.  The third is to trace type reconstruction.

Tracing of term reconstruction is enabled with

@example
Twelf.Recon.trace := true;
@end example

It then prints, during reconstruction, the typing and kinding judgments
it infers in the form @code{|- M : A} or @code{|- A : K}.

There are two modes for tracing reconstruction that can be set
with

@example
Twelf.Recon.traceMode := Twelf.Recon.Omniscient;
Twelf.Recon.traceMode := Twelf.Recon.Progressive;
@end example

where @code{Twelf.Recon.Omnisicient} is the default.  In omnisicent
mode, it first solves all typing constraints, and then prints the typing
judgments.  In progressive mode, it prints the typing judgments as they
are encountered.  Both have their uses, depending on the form of
the problem with reconstruction.


@node Logic Programming, Constraint Domains, Term Reconstruction, Top
@chapter Logic Programming

@cindex logic programming

Twelf gives an operational interpretation to signatures under the
computation-as-proof-search paradigm.  The fundamental idea is to fix a
simple search strategy and then search for a derivation of a query
according to this strategy.  The result may be a substitution for the
free variables in a query and a derivation, or explicit failure.  It is
also possible that the computation does not terminate.

A query can be posed in three different ways: as a @code{%query}
declaration, as a @code{%solve} declaration, or interactively, using a
top-level invoked from ML with @code{Twelf.top} which prompts with
@samp{?-} (@pxref{Interactive Queries}).

@example
@group
query ::= id : term             % @r{@math{X : A}, @math{X} a free variable}
        | term                  % @r{@math{A}}

bound ::= nat                   % @r{number of solutions}
        | *                     % @r{unbounded number}

qdecl ::= bound bound query     % @r{expected solutions, try limit, query}

qtdecl ::= bound bound query    % @r{number of stages, query}

sdecl ::= %define binding sdecl % @r{term binding}
        | %solve id : term      % @r{solve with proof term}
        | %solve _ : term       % @r{solve}

binding ::= id = id             % @r{@math{c = X}, @math{X} a free variable}
          | id = id : term      % @math{c = X : A}

decl ::= @dots{}
       | %tabled id.            % @r{@math{a}, table family @math{a}}
       | %query qdecl.          % @r{execute query}
       | %querytabled qtdecl.   % @r{execute query with tabled logic programming}
       | sdecl.                 % @r{solve}
@end group
@end example

In all of these cases, the free variables in a query are interpreted
existentially, which is in contrast to constant declarations where free
variables are interpreted universally.  In particular, free variables
might be instantiated during type reconstruction and during execution of
the query.



@menu
* Query Declaration::           Checking expected numbers of solutions
* Solve Declaration::           Naming proof terms found by search
* Interactive Queries::         Twelf's interactive top-level
* Sample Trace::                An example how search works
* Operational Semantics::       How queries are executed in some detail
* Sample Program::              Type inference for a lambda-calculus
* Clause Definitions::          How to use definitions for search
* Deterministic Type Families::  How to prune unwanted solutions 
* Tabled Logic Programming::    Executing queries with memo tables
@end menu

@node Query Declaration, Solve Declaration, Logic Programming, Logic Programming
@section Query Declaration

@cindex queries
@findex %query

The query form

@example
%query @var{expected} @var{try} A.
@end example

@noindent
will try to solve the query @code{A} and verify that it gives the
@var{expected} number of solutions, but it will never try to find more
than indicated by @var{try}.  It succeeds and prints a message, whose
precise form depends on the value of @code{Twelf.chatter} if @code{A}
has the expected number of solutions; otherwise it either fails with an
error message or does not terminate.  @samp{%query} has no other effect
on the state of Twelf.  Here are some examples.

@example
%query 1 * A.      % @r{check that @code{A} has exactly one solution}
%query 1 1 A.      % @r{check that @code{A} has at least one solution}
%query * 3 A.      % @r{@code{A} has infinitely many solutions, check 3}
%query * * A.      % @r{fails if @code{A} has finitely many solutions}
%query 1 0 A.      % @r{skip this query}
@end example

@node Solve Declaration, Interactive Queries, Query Declaration, Logic Programming
@section Solve Declaration

@cindex solving queries
@findex %solve

The query form

@example
%solve c : A.
@end example

@noindent
will search for the first solution @code{M} of @code{A} and then define

@example
c : A = M.
@end example

Optionally, it is possible to perform additional binding for the free
variables in @code{A}. Let @code{X} a variable of type family @code{B}
appearing in @code{A}, and let us assume that in the solution @code{M}
this variable has been substituted with the term @code{N}; the query
form

@example
%define d = X : B
%solve c : A.
@end example

will also define

@example
d : B = N.
@end example

If there are any free variables remaining in @code{M}, @code{N} or @code{A}
after search, they will be implicitly quantified in the new definitions.

This form of definition is particularly useful to compute and name inputs to
future queries.  An example of this feature from the file
@file{examples/nd/lam.elf} can be found in @ref{Proof Realizations}.

@node Interactive Queries, Sample Trace, Solve Declaration, Logic Programming
@section Interactive Queries

@cindex queries, interactive
@cindex top-level, query

An interactive top-level can be invoked using the SML expression
@code{Twelf.top ();}.  The top-level prompts with @samp{?- } and
awaits the input of a query, terminated by a period @samp{.} and
a @key{RET}.

After the query has been parsed, Twelf reconstructs implicit type
information, issuing a warning if constraints remain.  The result is
executed as a query.  At any point during the processing of a
query the user may interrupt with @kbd{C-c} (that is, @key{CTRL} and
@kbd{c}) to drop back into ML's interactive top-level.

When Twelf has found a solution, it prints the @emph{answer
substitution} for all free variables in the query, including the proof
term variable if one was given.  It also notes if there are remaining
equational constraints, but currently does not print them.

The top-level then waits for input, which is interpreted as
follows

@table @asis
@item @kbd{y}, @kbd{Y}, or @kbd{;}
      backtrack and search for another solution

@item @kbd{q} or @kbd{Q}
      quit Twelf's top-level and return to ML

@item @kbd{n}, @kbd{N}, or anything else
      return to prompt for another query
@end table

@node Sample Trace, Operational Semantics, Interactive Queries, Logic Programming
@section Sample Trace

As an example we consider lists of propositions and some simple
operations on them, as they might be used when programming a theorem
prover.

@example
@group
list : type.
nil  : list.
cons : o -> list -> list.
@end group
@end example

First, we want to write a program to append two lists to obtain
their concatenation.  This is expressed as a relation between
the three lists, which in turn is implemented as a type family

@example
@group
append  : list -> list -> list -> type.

appNil  : append nil K K.
appCons : append (cons X L) K (cons X M)
           <- append L K M.
@end group
@end example

Here, we use the synonym @code{A <- B} for @code{B -> A} to improve
readability.  We say @emph{@code{A} if @code{B}}.

The first sample query concatenates the singleton lists containing
@code{true} and @code{false}.  We proceed as if we had loaded the appropriate
files and started a top-level with @code{Twelf.top ();}.

@example
?- append (cons true nil) (cons false nil) L.
@end example

Here, @code{L} is a free existential variable.  We search for an object
@code{M : append (cons true nil) (cons false nil) L}, even though
this object will not be shown in this form or query.  Each
constant declaration in the signature is tried in turn, unifying
the head with the goal above.  In this manner, we obtain the
following sequence of goals and actions.  Note that the intermediate
forms and comments are not printed when this is run.  They are added
here to illustrate the behavior.

@example
@group
% @r{original goal after parsing and type reconstruction}
?- append (cons true nil) (cons false nil) L.
[try appNil:
     append nil K1 K1
   = append (cons true nil) (cons false nil) L
 unification fails with constant clash: nil <> cons
]
[try appCons:
     append (cons X1 L1) K2 (cons X1 M1)
   = append (cons true nil) (cons false nil) L
 unification succeeds with
 X1 = true, L1 = nil, K2 = cons false nil, L = cons true M1
]
@end group
@group
% @r{subgoal}
?- append nil (cons false nil) M1.
[try appNil:
     append nil K3 K3
   = append nil (cons false nil) M1
 unification and subgoal succeeds with
 K3 = cons false nil, M1 = cons false nil
]
@end group
@end example

At this point the overall goal succeeds and we read off the
answer substitution for the only free variable in the query,
namely @code{L}.  It was first determined to be @code{cons true M1}
and then @code{M1} was instantiated to @code{cons false nil},
leading to the instantiation

@example
L = cons true (cons false nil).
@end example

If instead we pose the query

@example
?- X : append (cons true nil) (cons false nil) L.
@end example

@noindent
we also obtain the proof term

@example
@group
L = cons true (cons false nil);
X = appCons appNil.
@end group
@end example

As another example we consider a query with several solutions which are
enumerated when we ask for further results.  This time we do not trace
the steps of the execution, but show the interaction verbatim.

@example
@group
?- append L K (cons true (cons false nil)).
Solving...
K = cons true (cons false nil);
L = nil.
More? @kbd{y}
K = cons false nil;
L = cons true nil.
More? @kbd{y}
K = nil;
L = cons true (cons false nil).
More? @kbd{y}
No more solutions
@end group
@end example

@node Operational Semantics, Sample Program, Sample Trace, Logic Programming
@section Operational Semantics

@cindex operational semantics
@cindex semantics, operational
@cindex clause selection
@cindex subgoal selection
@cindex unification
@cindex local assumptions
@cindex assumptions
@cindex local parameters
@cindex parameters
@findex Twelf.Compile.optimize

The operational semantics of Twelf is a form of typed constraint logic
programming.  We will use standard terminology from this area.  A type
family which is used in a program or goal is called a @emph{predicate}.
A constant declaration in a signature which is available during search
is called a @emph{clause}.  A clause typically has the form @code{c : a
M1 @dots{} Mm <- A1 <- @dots{} <- An}, where @code{a M1 @dots{} Mm} is
the @emph{head of the clause} and @code{A1} through @code{An} are the
@emph{subgoals}.  A clause is used to reduce a goal to subgoals by a
process called @emph{backchaining}.  Backchaining unifies the head of
the clause with the current goal to generate @emph{subgoals}.  Next, we
@emph{select} one of the subgoals as a current goal and continue the
search process.  Actually, instead of unification (which is undecidable
in LF), Twelf employs @emph{constraint simplification} and carries along
equational constraints in a normal form.

A hypothesis which is introduced during search is a @emph{local
assumption}; a parameter is a @emph{local parameter}.  Parameters act
like constants in unification, except that their occurrences might be
restricted due to @emph{parameter dependency}.

Without going into a formal description, here are the central ideas of
the operational semantics.

@table @asis
@item Clause selection.
 The clauses are tried in the following order: from most recent to least
recent local assumption, then from first to last clause in the global
signature.

@item Subgoal selection.
 Subgoals are solved from the inside out.  For example, when a clause
@code{c : A <- B <- C.}  is applied to solve the goal @code{?- A.} then the
first subgoal is @code{B} and the second subgoal @code{C}.  Truly
dependent variables will only be subject to unification and never
give rise to a subgoal.  For example @code{c : @{X:b@} a X <- a c} is
a clause with head @code{a X}, subgoal @code{a c}, and existential variable
@code{X}.

@item Unification.
 An atomic goal is unified with the clause head using higher-order
pattern unification.  All equations outside this fragment are postponed
and carried along as constraints.

@item Local assumptions.
 A goal of the form @code{?- A -> B.} introduces a local assumption @code{A}
and then solves @code{B} under this assumption.  To solve atomic goals,
local assumptions are tried before global clauses, using the most
recently made assumption first.  Note that this is different from
Prolog @code{assert} in that @code{A} is available only for solving
@code{B}.

@item Local parameters.
 Parameters are introduced into proof search by goals of the form
@code{?- @{x:A@} B.} which generates a @emph{new} parameter @code{a} and
then solves the result of substituting @code{a} for @code{x} in
@code{B}.  Parameters are also called @emph{universal variables} since
they are not subject to instantiation during unification.  Local
parameters will never be used as local assumptions during search.
@end table

When a signature is read, some minimal amount of syntactic translation
may be applied to it in order to speed up execution.  We refer to this
process as @emph{compilation}, in an abuse of the ordinary use of the term.
Compilation will try to eliminate expensive appeals to unification
with assignment where this optimization is sound.  This can be disabled
by setting the parameter @code{Twelf.Compile.optimize} to @code{false}.

@node Sample Program, Clause Definitions, Operational Semantics, Logic Programming
@section Sample Program

@cindex lambda calculus example
@cindex type inference example

As an example, we consider simple type inference for the pure
lambda-calculus.  An extension of this example to Mini-ML is given in
the course notes @cite{Pfenning 1992, Computation and Deduction}.  The
code below can be found in the file @file{examples/guide/lam.elf}.

@example
@group
% Simple types
tp : type.                              %name tp T.

arrow : tp -> tp -> tp.                 % T1 => T2

% Expressions
exp : type.                             %name exp E.

lam   : (exp -> exp) -> exp.            % lam x. E
app   : exp -> exp -> exp.              % (E1 E2)

% Type inference 
% |- E : T  (expression E has type T)

of : exp -> tp -> type.                 %name of P.

tp_lam : of (lam E) (arrow T1 T2)       % |- lam x. E : T1 => T2
          <- (@{x:exp@}                   % if  x:T1 |- E : T2.
                of x T1 -> of (E x) T2).

tp_app : of (app E1 E2) T1              % |- E1 E2 : T1
          <- of E1 (arrow T2 T1)        % if  |- E1 : T2 => T1
          <- of E2 T2.                  % and |- E2 : T2.
@end group
@end example

Again, we have used the notation @code{A <- B} to emphasize
the interpretation of constant declarations as clauses.  We now
trace the query which infers the most general type of the identity
function, represented as @code{lam [x:exp] x}.  We indicate the scope
of hypotheses which are introduced during search by indentation.

@example
@group
% @r{original query, @code{T} free}
?- of (lam [x:exp] x) T.
% @r{use @code{tp_lam} with @code{E = ([x:exp] x)} and @code{T = arrow T1 T2}}
% @r{subgoal}
?- @{x:exp@} of x T1 -> of x T2.
% @r{introduce parameter @code{e}}
?- of e T1 -> of e T2.
% @r{introduce hypothesis labeled @code{p}}
p:of e T1
 ?- of e T2.
 % @r{succeed by hypothesis @code{p} with @code{T1 = T2}}
@end group
@end example

At this point the query succeeds and prints the answer substitution.

@example
@group
T = arrow T1 T1.
More? @kbd{y}
No more solutions
@end group
@end example

We requested more solution by typing @kbd{y}, but there are no further
possibilities.  The free variable @code{T1} in the answer substitution
means that every instance of @code{arrow T1 T1} provides a solution to
the original query.  In other words, @code{lam [x:exp] x} has type
@code{arrow T1 T1} for all types @code{T1}.

As a second example we verify that self-application is not well-typed in
the simply-typed lambda-calculus.

@example
@group
?- of (lam [x:exp] app x x) T.
% @r{use @code{tp_lam} with @code{T = arrow T1 T2}}
% @r{subgoal}
?- @{x:exp@} of x T1 -> of (app x x) T2.
% @r{introduce parameter @code{e}}
?- of e T1 -> of (app e e) T2.
% @r{introduce hypothesis @code{p:of a T1}}
p:of e T1
 ?- of (app e e) T2.
 % @r{use @code{tp_app}}
 % @r{first subgoal}
 ?- of e (arrow T3 T2).
 % @r{succeed by hypothesis @code{p} with @code{T1 = arrow T3 T2}}
 % @r{second subgoal}
 ?- of e T3.
 % @r{fail, since @code{T3 = arrow T3 T2} has no solution}
@end group
@end example

At the point where the second subgoals fails we backtrack.  However, all
other alternatives fail immediately, since the clause head does not
unify with the goal and the overall query fails.

@node Clause Definitions, Deterministic Type Families, Sample Program, Logic Programming
@section Clause Definitions

@cindex family-level definitions
@cindex definitions, family-level
@cindex type-level definitions
@cindex definitions, type-level
@cindex definitions, in proof search
@findex %clause

Definitions interact with the logic programming interpretation
of signatures in two ways.

At present family-level definitions are transparent for type-checking, but
opaque for proof search.  This means, if @code{@var{a} : type = @var{b}},
the constants defining @var{a} and @var{b} are not mixed.

@strong{Disclaimer:} This is use type-level definitions is still under
consideration and is discouraged because it might change in future
releases.  Moreover, type-level definitions at present do not interact
correctly with coverage checking and can lead to unsoundness.

The second interaction is that defined object-level constants are
generally not used for the logic programming interpretation.  However,
they can be forced to be used with a declaration

@example
%clause @var{d} : @var{A} = @var{M}.
@end example

For search, it will be treated exactly as if it were @code{@var{d} :
@var{A}.}  except that the resulting proof term will contain a defined
constant instead of a declared constant.

@node Deterministic Type Families, Tabled Logic Programming, Clause Definitions, Logic Programming
@section Deterministic Type Families
In general, a solvable goal may admit several (and possibly countably
infinite) solutions. Through backtracking, Twelf will generate all of
them. There are circumstances, however, where only the only one of
them is correct, or interesting. Consider, for example, list membership:

@example
@group
element : type. %name element X.

a : element.
b : element.
c : element.

list : type.    %name list L.

nil : list.
cons : element -> list -> list.

member : element -> list -> type.

member1 : member X (cons X L).
member2 : member X (cons Y L) <- member X L.
@end group
@end example

the query

@example
?- member a (cons a (cons b (cons a nil)))
@end example

will succeed twice. Since all we are interested in is whether
@code{a} is contained in the list or not, it may suffice for it to
succeed once.

Discarding unwanted solutions in Twelf is accomplished through the
@code{%deterministic} directive. Declaring a type family deterministic
will cause all queries involving it to succeed at most once: if there
are several solutions, only the first one will be found. So for example
declaring

@example
%deterministic member.
@end example

will have the effect of preventing backtracking in any query involving
the type family @code{member}, once one solution has been found:

@example
@group
?- member a (cons a (cons b (cons a nil))).
Solving...
Empty Substitution.
More? y
No more solutions
@end group
@end example

In other logic programming languages like Prolog, pruning of unwanted
solutions is usually accomplished by using the extra-logical operator
cut. In general, @code{%deterministic} is less powerful than cut: in
a language with cut, a deterministic predicate can be modeled by
adding a cut at the end of all of its clauses. However, in most
practical uses the two are equivalent, and the semantics of
@code{%deterministic} families is cleaner and better understood.

@node Tabled Logic Programming,  , Deterministic Type Families, Logic Programming
@section Tabled Logic Programming

@cindex tabled logic programming
@findex %tabled
@findex %querytabled
@findex Twelf.Table.strengthen
@findex Twelf.Table.strategy
@findex Twelf.Table.Variant
@findex Twelf.Table.Subsumption
@findex Twelf.Table.top

Logic programming uses a simple depth-first search strategy to search
for a proof of a given query.  This strategy is incomplete, that is,
there are queries that are true, but the logic programming engine will
not find a proof due to non-termination.  In addition, performance may
be hampered by redundant computation.

Tabled logic programming uses memoization to alleviate these problems by
avoiding infinite and redundant paths of computation.  The central data
structure is a table in which we store encountered subgoals and
corresponding solutions.  When we solve a subgoal @code{G}, then we
check whether @code{G} is in the table.  If it is not in the table, then
it will be added.  If it is in the table and there are solutions
available, then we can re-use them.  If it is in the table and no
solutions are available, then we suspend the computation.  This basic
idea is combined with global stages.  In each stage, a depth-first
search strategy is used to derive answers from the program.  If no more
answers can be derived, computation terminates.  It is important to note
that for each answer only one proof is generated, although multiple
different proofs may exist.

Tabled and non-tabled execution can be freely mixed.  This is achieved
by requiring an explicit declaration

@example
%tabled a.
@end example

@noindent
for every type family @code{a} that is to be tabled.  In addition,
at present tabling must be explicitly enabled by invoking

@example
%querytabled @var{expected} @var{stages} A.
@end example

where @var{expected} is the expected number of answers and 
@var{stages} bounds the number of stages to use before terminating
while searching for a proof of @code{A}. If @var{expected} is @code{*},
it will find all distinct solutions. If there are finitely many solutions,
search will terminate, after enumerating all of them. If @var{stages} is @code{*},
then arbitrarily many stages may be explored, which can lead to
non-termination over infinite domains.

To illustrate, here is a small simple example that computes
reachability in a cyclic graph.  First we declare the nodes
in the graph and the edge relation.

@example
@group
node : type.

a : node.
b : node.
c : node.
d : node.

edge: node -> node -> type.

e_ab : edge a b.
e_ac : edge a c.
e_ba : edge b a.
e_bd : edge b d.
@end group
@end example

Next we declare the reachability relation and declare it tabled
in order to avoid an infinite loop.

@example
@group
reach: node -> node -> type.
%tabled reach.

r_refl: reach X X.

r_cl  : reach X Y 
         <- edge X Z
         <- reach Z Y.

%querytabled 4 * (reach a X).
@end group
@end example

Note that, at present, tables will be completely ignored for ordinary
queries, so that

@example
%query * * reach a X.
@end example

will not terminate, despite the fact that @code{reach} has been
declared as tabled.

In the example above we can also give an explicit bound on the
number of stages during tabled evaluation with

@example
%querytabled 4 3 (reach a X).
@end example

Additional examples using tabling can be found in
the directory @file{examples/tabled/} of the distribution. 

One key question in tabled search is how to detect that a subgoal is
similar to another sub-goal which is already in the table. There are
two critical parameters which influence table lookup during search. 

@code{Twelf.Table.strengthen} which defaults to @code{false}.
If @code{true} it eliminates dependencies based on subordination
during tabling.  This is more expensive, but can lead to increased
re-use of prior subgoals in some cases.


@code{Twelf.Table.strategy} which defaults to @code{Twelf.Table.Variant}.
When at its default setting, @code{Twelf.Table.Variant}, then subgoals are
compared for equality modulo renaming of existential and bound variables.
When set to @code{Twelf.Table.Subsumption}, then comparison
of subgoals with table entries allows instantiation of the table
entries.  This is slower, but may lead to increased sharing and
better termination properties.

It is also possible (in analogy with @code{Twelf.top ();}, explained
in @ref{Interactive Queries}, to start an interactive top level that
executes the tabling logic programming interpreter with the command

@example
Twelf.Table.top ();
@end example

Furthermore, it should be noted that tracing does @emph{not} work for
the tabled logic programming engine, and that other analyses such as
termination checking do not take the tabling into account.  This is
conservative, but means that many terminating tabled programs can at
present not be verified.

@node Constraint Domains, Modes, Logic Programming, Top
@chapter Constraint Domains

@cindex constraints
@cindex constraint domains
@cindex numbers

Constraints-based extensions are highly experimental and under active
development.  Use of extensions other than the ones pertaining rational
arithmetic is strongly discouraged.  We refer to extension by constraint
domains as Twelf(X), where X refers different domains.

Twelf(X) extensions allow Twelf to deal more efficiently with some
specific domains (e.g. numbers). They do so by

@enumerate
@item modifying type reconstruction to accommodate other equivalences beyond
those entailed by traditional beta-eta-conversion;

@item defining special types, on which proof search is performed using ad-hoc
decision procedures rather than traditional depth-first strategy;

@item adding countably many new symbols to the language, signifying all the
elements of the domain.
@end enumerate

@menu
* Installing an Extension::     Making constraint domains available
* Equalities of Rational Numbers::  Rationals with equality
* Inequalities over Rational Numbers::  Rationals with equality and inequality
* Integer Constraints::         Integers with equality and inequality
* Equalities over Strings::     Strings and concatenation
* 32-bit Integers::             Integers representable as string of 32 bits
* Sample Constraint Programs::  Some examples of use
* Restrictions and Caveats::    Alerts!
@end menu

@node Installing an Extension, Equalities of Rational Numbers, Constraint Domains, Constraint Domains
@section Installing an Extension

@findex %use

Extensions are installed using the declaration

@example
%use @emph{extension name}
@end example

For example,

@example
%use equality/rationals.
@end example

@noindent
loads the extension dealing with equality over the rationals. Typically,
an extension introduces new symbols in the signature. For example,
@code{equality/rationals} adds a type for rational numbers:

@example
rational : type.
@end example

In addition to these symbols, a countably infinite set of ``special''
ones may be also accepted by the system as the result of loading one
extension. In our example, after loading @code{equality/rationals} the
symbols

@example
135  5/13  ~1/4
@end example

@noindent
become valid constants of type @code{rational}.

Finally, it is possible for an extension to be built on top of others,
and therefore to depend on them. Hence, loading an extension usually
causes all the others it depends upon to be loaded as well, if they have
not been already. For example, the extension @code{inequality/rationals}
requires @code{equality/rationals}, and hence the declaration

@example
%use inequality/rationals.
@end example

@noindent
subsumes

@example
%use equality/rationals.
@end example

Extensions must be installed prior to their use. For this reason, it is
a safe practice to put all the @code{%use} declarations at the
beginning of the program.


@node Equalities of Rational Numbers, Inequalities over Rational Numbers, Installing an Extension, Constraint Domains
@section Equalities over Rational Numbers

As mentioned before, the extension presiding equality over the rational
numbers is called @code{equality/rationals}, and it is therefore installed
by the declaration

@example
%use equality/rationals.
@end example

This causes the declarations

@example
@group
rational : type.

~ : rational -> rational.              %prefix 9999 ~.
+ : rational -> rational -> rational.  %infix left 9997 +.
- : rational -> rational -> rational.  %infix left 9997 -.
* : rational -> rational -> rational.  %infix left 9998 *.
@end group
@end example

@noindent
to be included in the current global signature. 

Note that We do not add an equality predicate for rationals. This is
unnecessary, since the extension modifies standard type checking so that
arithmetic identities are taken into account. However, one can always
define an equality predicate by declaring

@example
     == : rational -> rational -> type.  %infix none 100 ==.
     id : X == X.
@end example

This extension is also responsible for defining special constants for
all the rational numbers. These follow the syntax

@example
@group
<rational> ::= ~<unsigned> | <unsigned>
<unsigned> ::= <digits> | <digits>/<digits>
<digits>   ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 
             | <digits> <digits>
@end group
@end example

It is important to notice the difference between @code{~ 10} and
@code{~10}. The former is the object obtained applying the unary minus
operator to the positive number @math{10}; the second stands for the number
@math{-10}.  The difference is, however, just syntactical, since the former
is automatically evaluated into the latter by Twelf(X). In general, one
should keep in mind that Twelf(X) extensions do not modify the behavior
of the lexer; hence, for example, multiplication of a variable @code{X}
by two still needs to be written as @code{X * 2} (note the spaces
preceding and following the multiplication symbol), while @code{X*2}
will be interpreted by the system as a single variable named
``@code{X*2}''.

Unification of arithmetic expressions is done by Gaussian
elimination. Thus, unification problems that can be reduced to linear
equations over existentially quantified variables are immediately
solved; other problems not falling in this class are likely to be
delayed as unificational constraints.

@node Inequalities over Rational Numbers, Integer Constraints, Equalities of Rational Numbers, Constraint Domains
@section Inequalities over Rational Numbers

Arithmetical inequalities are handled by the extension
@code{inequality/rationals}. This relies on @code{equality/rationals}
for the definition of rational number, so a declaration of

@example
%use inequality/rationals.
@end example

@noindent
implicitly entails one of

@example
%use equality/rationals.
@end example

This extension adds the following to the signature:

@example
@group
>  : rational -> rational -> type.  %infix none 0 >.
>= : rational -> rational -> type.  %infix none 0 >=.

+>  : @{Z:rational@} X > Y -> (X + Z) > (Y + Z).
+>= : @{Z:rational@} X >= Y -> (X + Z) >= (Y + Z).

>>=  : X > Y -> X >= Y.
0>=0 : 0 >= 0.
@end group
@end example

It also adds countably many proof objects such as

@example
45>0 : 45 > 0.
@end example

@noindent
witnessing that positive numbers are greater than zero.

Goals of the form

@example
M > N  @r{or}  M >= N
@end example

@noindent
are evaluated using a modified version of the simplex algorithm, rather
than the usual proof-search mechanism. This will incrementally collect
inequalities, assigning them incomplete (i.e. partially instantiated)
proof objects, until either an inconsistency is discovered (generating
failure) or they can be shown to be satisfied a unique solution (causing
the proof objects to be finally completed).

@node Integer Constraints, Equalities over Strings, Inequalities over Rational Numbers, Constraint Domains
@section Integer Constraints

The extensions @code{equality/integers} and @code{inequality/integers}
deal with equalities and inequalities over the ring of integer numbers,
respectively. Since these two extensions are very similar to their
rationals counterparts, we will limit ourselves to outlining the
differences.

The signature introduced by @code{equality/integers} resembles
@code{equality/rationals}.  The only difference lies in the name of
the main type:

@example
@group
integer : type.

~ : integer -> integer.             %prefix 9999 ~.
+ : integer -> integer -> integer.  %infix left 9997 +.
- : integer -> integer -> integer.  %infix left 9997 -.
* : integer -> integer -> integer.  %infix left 9998 *.
@end group
@end example

Like before, countably many special constants are added to the signature. They follow the syntax

@example
<integer> ::= ~<digits> | <digits>
@end example

The extension @code{equality/integers} takes advantage of the fact that (unlike the rationals) the integers are not a dense ordering to considerably shorten the set of symbols needed:

@example
@group
>= : integer -> integer -> type.  %infix none 0 >=.

+>= : @{Z:integer@} X >= Y -> (X + Z) >= (Y + Z).
@end group
@end example

It also declares countably many proof objects such as

@example
37>=0 : 37 >= 0.
@end example

@noindent
for all non-negative integers.

Notice that strict inequality @code{>} can be easily defined in this case:

@example
> : integer -> integer -> type.  %infix none 0 >.

>=> : X >= (Y + 1) -> X > Y.
@end example

For solving linear inequalities over the integers, we again use the
simplex method, but we add special routines that implement
branch-and-bound search. Specifically, inequalities are internally
interpreted over rationals, and a check is performed regularly (whenever
a new inequality is added) to ensure the rational solution space
contains integral points.

Note that all known methods for solving systems of integral linear
inequations are notoriously inefficient. In the branch-and-bound method
we adopted, the number of branches to consider is potentially
exponential with respect to the size of the problem. We recommend using
the @code{inequality/rationals} extension instead, whenever the situation
allows the two to be used interchangeably.

@node Equalities over Strings, 32-bit Integers, Integer Constraints, Constraint Domains
@section Equalities over Strings

A third domain currently supported by the Twelf(X) extensions are
strings of (printable) characters. The only operator provided is string
concatenation. Installing

@example
%use equality/strings.
@end example

@noindent
causes the following signature to be loaded:

@example
string : type.

++ : string -> string -> string.   %infix right ++ 9999.
@end example

String constants are sequences of printable characters enclosed by double quotes:

@example
"foobar" : string
@end example

Under these conventions, strings cannot therefore contain the double
quote character @code{"}. Escape sequences, such as @code{"\n"} have no
special meaning; moreover, we do not currently provide input/output
primitives.

Finally, it is required that string constants occupy a single line. The declaration

@example
mystring : string = "foo
                     bar".
@end example

@noindent
is not considered syntactically correct.

@node 32-bit Integers, Sample Constraint Programs, Equalities over Strings, Constraint Domains
@section 32-bit Integers
Another supported domain are 32-bit integers. This domain is used mainly in
Proof Carrying Code applications, and because of this, it has fairly different
structure and features than the extension for (unrestricted) integers
(@pxref{Integer Constraints}). First of all, the algorithms used were kept short
and simple, so that they can be easily read and verified to be correct. Secondly,
the set of arithmetic operators provided has been kept to a minimum. Also, each of
these is implemented as a type family instead of a function symbol, so that unification
of arithmetic expressions follows the same rule as that of regular terms. Finally,
for each arithmetic operator, we also provide a type family which, in addition to
carry out the computation, also provides a proof object for it.

Declaring

@example
%uses word32.
@end example

causes the following signature to be loaded into the system:

@example
@group
word32 : type.
+ : word32 -> word32 -> word32 -> type.
* : word32 -> word32 -> word32 -> type.
/ : word32 -> word32 -> word32 -> type.
prove+ : @{X:word32@} @{Y:word32@} @{Z:word32@} @{P:+ X Y Z@} type.
proof+ : @{X:word32@} @{Y:word32@} @{Z:word32@} @{P:+ X Y Z@} prove+ X Y Z P.
prove* : @{X:word32@} @{Y:word32@} @{Z:word32@} @{P:* X Y Z@} type.
proof* : @{X:word32@} @{Y:word32@} @{Z:word32@} @{P:* X Y Z@} prove* X Y Z P.
prove/ : @{X:word32@} @{Y:word32@} @{Z:word32@} @{P:+ X Y Z@} type.
proof/ : @{X:word32@} @{Y:word32@} @{Z:word32@} @{P:+ X Y Z@} prove/ X Y Z P.
@end group
@end example

Goals involving @code{+} and @code{*} are immediately solved if at least
two of the arguments are ground objects (i.e. numbers), and delayed as
constraints otherwise. In particular

@example
?- + 3 X 9.
@end example

is solved immediately and can be used to compute @math{9-3}.
Goals involving @code{/} are delayed unless both the first and the second
argument are known. The type families @code{prove+}, @code{prove*},
@code{prove/} can be used to obtain proof object for the arithmetic
operation, and use them in the remaining part of the computation:

@example
@group
?- P : + 3 X 9.
Solving...
X = 6.
P = 3+6.
More? n
?- prove+ 3 X 9 P.
Solving...
P = 3+6;
X = 6.
More? n
@end group
@end example

It is important to stress that the domain modeled here is not the ring
of integers modulo 32 but rather the restriction of the integer ring to the
interval @math{0}...@math{4294967295}, so that for example the query:

@example
?- + 1 X 0.
@end example

will not admit a solution.

@node Sample Constraint Programs, Restrictions and Caveats, 32-bit Integers, Constraint Domains
@section Sample Constraint Programs

Using Twelf(X), we can write a modified version of @code{append} that
takes into account the size of the list involved:

@example
@group
%use equality/rationals.

item : type.
list : rational -> type.

a : type.
b : type.
...

nil  : list 0.
cons : item -> list N -> list (N + 1).

append : list M -> list N -> list (M + N).

append_nil  : append nil L L.
append_cons : append (cons X L1) L2 (cons X L3)
                <- append L1 L2 L3.
@end group
@end example

Type checking the definition of @code{append} requires some algebraic manipulation. For example, validity of @code{append_nil} depends on the identity
@math{0+M=M}.

Most classic Constraint Logic Programming (CLP) examples found in the
literature can be easily translated to Twelf(X). We present here a
simple mortgage calculator:

@example
%use inequality/rationals.

%% equality
== : rational -> rational -> type.  %infix none 1000 ==.
id : X == X.

%% mortgage payments
mortgage : rational -> rational -> rational
                    -> rational -> rational -> type.

m0 : mortgage P T I MP B
       <- T > 0
       <- 1 >= T
       <- Interest == T * P * I * 1/1200
       <- B == P + Interest - (T * MP).
m1 : mortgage P T I MP B
       <- T > 1
       <- MI == P * I * 1/1200
       <- mortgage (P + MI - MP) (T - 1) I MP B.
@end example

This CLP program takes four parameters: the principal @code{P}, the life
of the mortgage in months @code{T}, the annual interest rate (%)
@code{I}, the monthly payment @code{MP}, and the outstanding balance
@code{B}.

Finally, we use the string extensions to write a simple parser. Consider
the following syntax for simple arithmetic expressions:

@example
@group
<expr> ::= <number> | <expr>+<expr>
                    | <expr>-<expr>
                    | <expr>*<expr>
                    | (<expr>)
<number>     ::= <digit> | <digit><number>
<digit>      ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
@end group
@end example

This can be translated quite directly into Twelf by constructing parsing
predicates @code{digit}, @code{number}, @code{expression} as follows:

@example
digit : string -> type.

d0 : digit "0".
d1 : digit "1".
d2 : digit "2".
d3 : digit "3".
d4 : digit "4".
d5 : digit "5".
d6 : digit "6".
d7 : digit "7".
d8 : digit "8".
d9 : digit "9".

number : string -> type.

nd  : number X
        <- digit X.
n++ : number (X ++ Y)
        <- digit X
        <- number Y.

expression : string -> type.

en : expression X
       <- number X.
e* : expression (X ++ "*" ++ Y)
       <- expression X
       <- expression Y.
e+ : expression (X ++ "+" ++ Y)
       <- expression X
       <- expression Y.
e- : expression (X ++ "-" ++ Y)
       <- expression X
       <- expression Y.
ep : expression ("(" ++ X ++ ")")
       <- expression X.
@end example

@node Restrictions and Caveats,  , Sample Constraint Programs, Constraint Domains
@section Restrictions and Caveats

To ensure the consistency of the calculus, use of types defined by
Twelf(X) extensions is restricted. Specifically, we do not allow them to
be used as dynamic assumptions. This rules out meaningless (under the
current operating semantics) goals like

@example
?- 0 > 1 -> foo. 
@end example

@noindent
as well as meaningful, but intractable ones, such as

@example
?- @{X : rational@} X * X >= 0
@end example

One important thing to keep in mind when using arithmetic is that this
currently is defined over the rationals, rather than the integers or the
set of natural numbers.  While in many applications this is of no
consequence, it might generate in some cases surprising results. While
it is certainly possible to define the characteristic function of the
integer subset (see the content of @code{clp-examples/integers/} in the
distribution) and use this to enforce all computations to take place in
the intended domains, this introduces a big performance penalty and
should in general be avoided.

@node Modes, Termination, Constraint Domains, Top
@chapter Modes

@cindex modes
@cindex input mode
@cindex output mode

In most cases, the correctness of the algorithmic interpretation of a
signature as a logic program depends on a restriction to queries of a
certain form.  Often, this is a restriction of some arguments to
@emph{inputs} which must be given as @emph{ground} objects, that is,
objects not containing any existential variables.  In return, one often
obtains @emph{outputs} which will also be ground.  In the logic
programming terminology, the information about which arguments to a
predicate should be considered input and output is
called @emph{mode information}.

Twelf supports a simple system of modes.  It checks explicit mode
declarations by the programmer against the signature and signals errors
if the prescribed information flow is violated.  Currently, queries are
not checked against the mode declaration.

Mode checking is useful to uncover certain types of errors which
elude the type-checker.  It can also be used to generate more efficient
code, although the compiler currently does not take advantage
of mode information.

There are two forms of mode declarations: a short form which is adequate
and appropriate most of the time, and a long form which is sometimes
necessary to ascribe the right modes to implicit arguments

@example
@group
mdecl ::= smdecl    % @r{short mode declaration}
        | fmdecl    % @r{full mode declaration}

decl ::= @dots{}
       | %mode mdecl.
@end group
@end example

@menu
* Short Mode Declaration::      Common form for modes
* Full Mode Declaration::       Fully explicit modes
* Mode Checking::               Checking mode correctness
@end menu

@node Short Mode Declaration, Full Mode Declaration, Modes, Modes
@section Short Mode Declaration

@cindex declarations, mode
@cindex mode declarations, short form
@findex %mode

There are two forms of mode declarations: a short and a full form.
The short form is an abbreviation which is expanded into the full
form when it is unambiguous.

@example
@group
mode ::= +       % @r{input}
       | *       % @r{unrestricted}
       | -       % @r{output}

mid ::= mode id  % @r{named mode identifier, one token}

smdecl ::= id          % @r{type family @math{a}}
         | smdecl mid  % @r{argument mode}
@end group
@end example

Mode declarations for a predicate @code{a} must come before any clauses
defining @code{a}.  Note that the mode followed with the identifier must
be one token, such as @samp{+L} and not @samp{+ L}.  The short form is
most convenient in typical situations.  For example, we can declare that
the @code{append} program (@pxref{Sample Trace}) takes the first two
arguments as input and produces the the third as output.

@example
@group
append  : list -> list -> list -> type.
%mode append +L +K -M.
@end group
@end example

If we wanted to use @code{append} to split a list into two
sublists, we would instead declare

@example
@group
append : list -> list -> list -> type.
%mode append -L -K +M.
@end group
@end example

@noindent
where the clauses @code{appNil} and @code{appCons} remain
unchanged.

In the lambda-calculus type checker (@pxref{Sample Program}), the type
must be an unrestricted argument.

@example
@group
of : exp -> tp -> type.
%mode of +E *T.
@end group
@end example

If we declare it as an input argument, @code{%mode of +E +T},
we obtain an error pointing to the first occurrence of @code{T2}
in the clause @code{tp_app} reproduced below.

@example
@group
examples/nd/lam.elf:27.20-27.22 Error: 
Occurrence of variable T2 in input (+) argument not necessarily ground

tp_app : of (app E1 E2) T1
          <- of E1 (arrow T2 T1)
          <- of E2 T2.
@end group
@end example

If we declare it as an output argument, @code{%mode of +E -T},
we obtain an error pointing to the second occurrence of @code{T1}
in the clause @code{tp_lam} reproduced below.

@example
@group
examples/nd/lam.elf:25.8-25.10 Error: 
Occurrence of variable T1 in output (-) argument not necessarily ground

tp_lam : of (lam E) (arrow T1 T2)
          <- (@{x:exp@}
                of x T1 -> of (E x) T2).
@end group
@end example

In general, for a mode declaration in short form the arguments are
specified exactly as they would look in the program.  This means one
cannot specify the modes of implicit arguments which are filled in by
term reconstruction.  These modes are reconstructed as follows: each
implicit argument which appears in the type of an input argument is
considered input @samp{+}, those among the remaining which appear in an
output argument are considered output @samp{-}, the rest are
unrestricted.  The mode declaration is echoed in full form, so the user
can verify the correctness of the modes assigned to implicit arguments.
If the inferred full mode declaration is incorrect, or if one wants to
be explicit about modes, one should use full mode declarations
(@pxref{Full Mode Declaration}).

@node Full Mode Declaration, Mode Checking, Short Mode Declaration, Modes
@section Full Mode Declaration

@cindex mode declaration, full form
@findex %mode

To specify modes for implicit arguments one must use the full form of
mode declaration.  A @code{mode} can be one of @samp{+},
@samp{*}, or @samp{-} (@pxref{Short Mode Declaration}).

@example
@group
fmdecl ::= mode @{id : term@} fmdecl
         | mode @{id@} fmdecl
         | term
@end group
@end example

The term following the mode prefix in a full mode declaration must
always have the form @code{@math{a} @math{x1} @dots{} @math{xn}} where
@math{x1} through @math{xn} are variables declared in the mode prefix.
As an example, we give an alternative specification of the @code{append}
predicate.

@example
@group
append : list -> list -> list -> type.
%mode +@{L:list@} +@{K:list@} -@{M:list@} append L K M.
@end group
@end example

@node Mode Checking,  , Full Mode Declaration, Modes
@section Mode Checking

@cindex mode checking

Mode checking for input, output, and unrestricted arguments examines
each clause as it is encountered.  The algorithm performs a kind of
abstract interpretation of the clause, keeping track of a list of the
existential variables for which it knows that they will be ground.

@enumerate
@item We assume each existential variable with a strict occurrence
(@pxref{Strict Occurrences}) in an input argument to the clause head to
be ground.

@item We traverse the subgoals in evaluation order (@pxref{Operational
Semantics}).  For each subgoal we first verify that all input arguments
will be ground, using the information about the existential variables
collected so far.  If this check succeeds we add all variables which
have a strict occurrence in an output argument of the subgoal to the
list of variables with known ground instantiations.

@item After the last subgoal has been examined, we verify that the
output arguments in the clause head are now also ground.
@end enumerate

Arguments whose mode is unrestricted are ignored: they do no need to be
checked, and they do not contribute any information about the
instantiations of existential variables.

@node Termination, Coverage, Modes, Top
@chapter Termination

@cindex termination checking

Besides checking types and modes, Twelf can also verify if a given type
family, when interpreted as a logic program, always terminates on
well-moded goals.  In many cases this means that the program implements
a decision procedure.  Of course, in general termination is undecidable,
so we only check a simple sufficient condition.

Checking termination presupposes that the program is well-typed and
guarantees termination only when the arguments involved in the
termination order are ground.  This will always be true for well-moded
goals, since mode and termination declarations must be consistent.

Termination is different from checking types and modes in that it is not
checked incrementally as the signature is read.  Instead, termination of
a predicate is a global property of the program once it has been read.
Thus termination declarations came after the predicate has been fully
defined; further extensions of the predicate are not checked and may
invalidate termination.

The termination checker is rather rudimentary in that it only allows
lexicographic and simultaneous extensions of the subterm ordering.
Moreover, it does not take into account if a result returned by a
predicate is smaller than an input argument.  Nonetheless, for the style
of programs written in Twelf, the termination of many decision
procedures can be verified.

@menu
* Termination Declaration::     Checking termination
* Reduction Declaration::       Checking outputs are smaller than inputs
* Subterm Ordering::            Higher-order subterms
* Lexicographic Orders::        Termination by nested induction
* Simultaneous Orders::         Termination by simultaneous induction
* Mutual Recursion::            Termination of mutually recursive predicates
@end menu

@node Termination Declaration, Reduction Declaration, Termination, Termination
@section Termination Declaration

@cindex termination declarations
@cindex declarations, termination
@cindex call patterns
@cindex termination order
@cindex order
@findex %terminates

The termination orders we construct are lexicographic or simultaneous
extensions of the subterm ordering explained in @ref{Subterm Ordering}.
The termination declaration associates the termination order with
argument positions of predicates via call patterns.

The case of mutually recursive predicates is particularly complex
and requires mutual call patterns and mutual arguments.
Their syntax is given below; they are explained in @ref{Mutual Recursion}.

@example
@group
args ::=
       | id args       % @r{named argument}
       | _ args        % @r{anonymous argument}

callpat ::= id args    % @r{@math{a} @math{x1} @dots{} @math{xn}}

callpats ::= 
           | (callpat) callpats
                       % @r{mutual call patterns}
@end group

@group
ids ::=
      | id ids         % @r{argument name}

marg ::= id            % @r{single argument}
       | ( ids )       % @r{mutual arguments}

orders ::=
         | order orders % @r{component order}

order ::= marg         % @r{subterm order}
        | @{ orders @}   % @r{lexicographic order}
        | [ orders ]   % @r{simultaneous order}

tdecl ::= order callpats    % @r{termination order}

decl ::= @dots{}
       | %terminates tdecl. % @r{termination declaration}
@end group
@end example

All identifiers in the order specification of a termination declaration
must be upper case, must occur in the call patterns, and no variable may
be repeated.  Furthermore, all arguments participating in the
termination order must occur in the call patterns in input positions.

The most frequent form of termination declaration is

@example
%terminates Xi (a X1 @dots{} Xn).
@end example

@noindent
which expresses that predicate @code{a} terminates because recursive
calls decrease the input argument @code{Xi} according to the subterm
ordering (@pxref{Subterm Ordering}).

As an example, we consider a proof that simple type inference
(@pxref{Sample Program}) terminates.  Recall the relevant program
fragment (see @file{examples/guide/lam.elf}).

@example
@group
of : exp -> tp -> type.                 %name of P.
%mode of +E *T.

tp_lam : of (lam E) (arrow T1 T2)       % |- lam x. E : T1 => T2
          <- (@{x:exp@}                   % if  x:T1 |- E : T2.
                of x T1 -> of (E x) T2).

tp_app : of (app E1 E2) T1              % |- E1 E2 : T1
          <- of E1 (arrow T2 T1)        % if  |- E1 : T2 => T1
          <- of E2 T2.                  % and |- E2 : T2.
@end group
@end example

The typability of an expression is always reduced to the typability of
its subexpressions.  Therefore any call to the @code{of} predicate with
a ground expression should terminate.  In general, termination can only
be checked for input arguments, and all calls must be well-moded
(@pxref{Mode Checking}).  Twelf verifies termination with the
declaration

@example
%terminates E (of E T).
@end example

Here, @code{E} specifies the decreasing argument, namely the first
argument of the typing judgment as expressed in the call pattern
@code{(of E T)}.

A corresponding attempt to show that evaluation always terminates,

@example
%terminates E (eval E V).
@end example

@noindent
fails for the clause @code{ev_app} with the message

@example
@group
examples/guide/lam.elf:1053-1068 Error:
Termination violation:
(E1' V2) < (app E1 E2)
@end group
@end example

@noindent
indicating that in a recursive call the term @code{E1' V2} could not be
shown to be smaller than @code{app E1 E2}.  In our example, of course,
evaluation need not terminate for precisely this reason.

Termination checking plays a crucial role in checking meta-programs. The
meta-program represents a proof that some relation about programs
holds. The recursive calls in the meta-program correspond to
applications of the induction hypothesis in the proof. Termination
checking of meta-programs corresponds to checking that the application
of the induction hypothesis is valid, i.e. we apply the induction
hypothesis to a smaller argument.

@node Reduction Declaration, Subterm Ordering, Termination Declaration, Termination
@section Reduction Declaration

@cindex reduction declarations
@cindex declarations, reduction
@cindex reduction predicate
@findex %reduces

A reduction predicate specifies a relation between input and output
arguments of a program.  The reduction checker is rather restrictive and
allows only relations based on subterm ordering.  For example, we cannot
reason about the length of a list or term.  Moreover, reduction checking
presupposes that the right side of the reduction predicate corresponds
to the input arguments and the left side of the predicate corresponds to
the output arguments.  The declaration @code{%reduces} checks if the
specified reduction predicate holds for a given program.  To check
whether the predicate also terminates, one needs to check termination of
the predicate separately.  The syntax for @code{order} can be found in
@ref{Termination}.

@example
@group
pdecl ::= order < order     % @r{strictly smaller than}
        | order <= order    % @r{smaller or equal than}
        | order = order     % @r{equal}

rdecl ::= pdecl callpats    % @r{reduction predicate}

decl ::= @dots{}
       | %reduces rdecl.    % @r{reduction declaration}
@end group
@end example

A @code{pdecl} requires that both orders specified are of the same
variety.  For example, if one is lexicographic, the other one must be as
well.

For example,

@example
%reduces Z <= X (minus X Y Z).
@end example

@noindent
expects @code{X} to be the input and @code{Z} to be the output of the goal
@code{(minus X Y Z)}. The declaration checks whether the output argument @code{Z} is
smaller than the input argument @code{X}, and if the program terminates in @code{X}.

As a simple example of reduction checking we consider the greatest
common divisor.  This is an excerpt from the signature for unary arithmetic
in the file @file{example/guide/arith.elf}.

@example
@group
gcd: nat -> nat -> nat -> type.          %name gcd G. 
%mode gcd +X +Y -Z. 

gcd_z1: gcd z Y Y. 
gcd_z2: gcd X z X. 

gcd_s1: gcd (s X) (s Y) Z 
  <- less (s X) (s Y) true 
  <- rminus (s Y) (s X) Y' 
  <- gcd (s X) Y' Z. 

gcd_s1: gcd (s X) (s Y) Z 
  <- less  (s X)(s Y) false 
  <- rminus (s X) (s Y) X' 
  <- gcd X' (s Y)  Z. 

rminus: nat -> nat -> nat -> type.        %name rminus M. 
%mode rminus +X +Y -Z. 
rmin : rminus (s X) (s Y) Z 
 <- sub X Y Z. 

%reduces Z < X (rminus X Y Z). 
%terminates [X Y] (gcd X Y _). 
@end group
@end example

In order to verify that the definition of gcd terminates, we need to
show that the arguments in the recursive call are decreasing, i.e. we
need to show @code{Y' < (s Y)} and @code{X' < (s X)}. To check that
these properties hold, we need the fact that the output argument
@code{Y'} of @code{rminus (s Y) (s X) Y'} is always smaller than the
input argument @code{(s Y)} (i.e.  @code{rminus (s Y) (s X) Y'} always
satisfies the reduction predicate @code{Y' < (s Y)}). We verify that
@code{rminus (s Y) (s X) Y'} always reduces its output argument by
checking the declaration @code{%reduces Z < X (rminus X Y Z)}. While
checking termination of @code{gcd} we use this information and prove
@code{Y' < (s Y)} (termination condition of @code{gcd}) under the
assumption @code{Y' < (s Y)} (reduction predicate of @code{rminus}).

@node Subterm Ordering, Lexicographic Orders, Reduction Declaration, Termination
@section Subterm Ordering

@cindex subterm order
@cindex order, subterm

On first-order terms, that is, terms not containing lambda-abstraction,
the subterm ordering is familiar: @math{M < N} if @math{M} is a strict
subterm of @math{N}, that is, @math{M} is a subterm @math{N} and
@math{M} is different from @math{N}.

On higher-order terms, the relation is slightly more complicated because
we must allow the substitution of parameters for bound variables without
destroying the subterm relation.  Consider, for example, the case of the
typing rule

@example
@group
of : exp -> tp -> type.                 %name of P.
%mode of +E *T.

tp_lam : of (lam E) (arrow T1 T2)       % |- lam x. E : T1 => T2
          <- (@{x:exp@}                   % if  x:T1 |- E : T2.
                of x T1 -> of (E x) T2).
@end group
@end example

@noindent
from the signature for type inference (@pxref{Sample Program}) in the
file @file{example/guide/lam.elf}.  We must recognize that

@example
(E x) < (lam E)
@end example

@noindent
according to the subterm ordering.  This is because @code{E} stands for
a term @code{[y:exp] E'} and so @code{E x} has the same structure as
@code{E'} except that @code{y} (a bound variable) has been replaced by
@code{x} (a parameter).  This kind of pattern arises frequently in
Twelf programs.

On the other hand, the restriction to parameter arguments of functions
is critical.  For example, the lax rule

@example
@group
tp_applam : of (app (lam E1) E2) T2
             <- of (E1 E2) T2.
@end group
@end example

@noindent
which applies @code{E1} to @code{E2} which is not a parameter, is indeed
not terminating.  This can be seen from the query

@example
?- of (app (lam [x:exp] app x x) (lam [y:exp] app y y)) T.
@end example

The restriction of the arguments to parameters can be lifted when the
type of the argument is not mutually recursive with the result type of
the function.  For example, the signature for natural deduction
(@pxref{Sample Signature}, contains no constructor which allows
propositions to occur inside individual terms.  Therefore

@example
(A T) < (forall A)
@end example

@noindent
where @code{A : i -> o} and @code{T : i} is an arbitrary term (not just
a parameter).  Intuitively, this is correct because the number of
quantifiers and logical connectives is smaller on the left, since
@code{T} cannot contain such quantifiers or connectives.

This kind of precise analysis is important, for example, in the proof
of cut elimination or the termination of polymorphic type
reconstruction.


@node Lexicographic Orders, Simultaneous Orders, Subterm Ordering, Termination
@section Lexicographic Orders

@cindex order, lexicographic

Lexicographic orders are specified as

@example
@{@var{O1} @dots{} @var{On}@}
@end example

Using @math{vi} and @math{wi} for corresponding argument structures
whose order is already defined, we compare them lexicographically as
follows:

@table @asis
@item @math{@{v1} @dots{} @math{vn@}} @math{<} @math{@{w1} @dots{} @math{wn@}}, if
@table @asis
@item @math{v1 < w1}, or
@item @math{v1 = w1} and @math{v2 < w2}, or
@item @dots{}
@item @math{v1 = w1}, @math{v2 = w2}, @dots{}, and @math{vn < wn}.
@end table
@end table

A lexicographic order is needed, for example, to show termination of
Ackermann's function, defined in @file{examples/arith/arith.elf} with
the termination declaration in @*@file{examples/arith/arith.thm}.

@node Simultaneous Orders, Mutual Recursion, Lexicographic Orders, Termination
@section Simultaneous Orders

@cindex order, simultaneous

Simultaneous orders require that one of its elements decreases while all
others remain the same.  This is strictly weaker than a lexicographic
ordering built from the same components.  Technically speaking it is
therefore is redundant for termination checking, since the corresponding
lexicographic ordering could be used instead.  However, for inductive
theorem proving it is quite useful, since the search space for
simultaneous induction is much smaller than for lexicographic induction.

Simultaneous orders are specified as

@example
[@var{O1} @dots{} @var{On}]
@end example

Using @math{vi} and @math{wi} for corresponding argument structures
whose order is already defined, we compare them simultaneously as
follows:

@table @asis
@item @math{[v1} @dots{} @math{vn]} @math{<} @math{[w1} @dots{} @math{wn]}, if
@table @asis
@item @math{v1 < w1}, @math{v2 <= w2}, @dots{}, and @math{vn <= wn}, or
@item @math{v1 <= w1}, @math{v2 < w2}, @dots{}, and @math{vn <= wn}, or
@item @dots{}
@item @math{v1 <= w1}, @math{v2 <= w2}, @dots{}, and @math{vn < wn}.
@end table
@end table

A combination of simultaneous and lexicographic order is used, for
example, in the admissibility of cut found in
@file{examples/cut-elim/int.thm}, where either the cut formula @math{A}
gets smaller, or if @math{A} stays the same, either the derivation of
the left or right premise get smaller while the other stays the same.

@node Mutual Recursion,  , Simultaneous Orders, Termination
@section Mutual Recursion

@cindex mutual recursion
@cindex mutual arguments
@cindex arguments, mutual

Mutually recursive predicates present a challenge to termination
checking, since decreasing arguments might appear in different
positions.  Moreover, mutually recursive predicates @code{a} and
@code{a'} might be prioritized so that when @code{a} calls @code{a'} all
termination arguments remain the same, but when @code{a'} calls @code{a}
the arguments are smaller according to the termination order.

To handle the association of related argument in mutually recursive
predicates, so-called @emph{mutual arguments} can be specified
in a termination order.  They are given as

@example
(X1 @dots{} Xn)
@end example

The priority between predicates is indicated by the order of the
call patterns.  If we analyze call patterns

@example
@group
(a1 args1)
(a2 args2)
@dots{}
(an argsn)
@end group
@end example

@noindent
then termination arguments must decrease when @code{ai} calls @code{aj}
for @math{i < j}, but calls of @code{ai} from @code{aj} may keep the
termination arguments equal.

Mutual arguments are used, for example, in the proofs of soundness (file
@*@file{examples/lp-horn/uni-sound.thm}) and completeness (file
@*@file{examples/lp-horn/uni-complete.thm}) of uniform derivations for
Horn logic.

@node Coverage, Theorem Prover, Termination, Top
@chapter Coverage

@cindex coverage
@cindex meta-theorem verification

Coverage checking can verify that no cases in the definition of a type
family have omitted.  In combination with mode and termination checking,
it is a powerful tool for analysing signatures.  Its primary use in
Twelf is for verifying totality of higher-level judgments, which can
thereby be seen to represent proofs of meta-theorems.

There are several features of LF and its use as a logical framework which
make coverage checking a complex problem.

The first is that higher-order representations often require us to
consider classes of contexts.  For example, in the program for type
inference (@pxref{Sample Program}) we introduce parameters @code{x:exp}
together with a typing assumption @code{u:of x T} for some @code{T}.
This means the type @code{exp} of expressions is dynamically extended
with new parameters, and coverage must take these into account.

The second are indexed types.  While it easy to see if all cases for a
simple data type such as the natural numbers (either zero or successor)
are covered, it is more difficult to verify whether all cases for
indexed types, such as possible deductions of @math{A} implies @math{A},
are covered.

The third is the higher-order nature of encodings.  We may have to
verify that all functions of a given type have been covered, not just
values of atomic type.  The fact that functions in LF must be parametric
makes this possible, but it can be subtle.

Coverage addresses all three of these problems in different ways.  The
programmer can specify the kinds of parameters and hypotheses considered
valid for an encoding.  @emph{World checking} verifies that this
specification is respected.  The programmer can also specify which
arguments of a given type family should cover all possibilities
exhaustively.  @emph{Coverage checking} verifies that this is indeed the
case, or produces a list of missing cases.  Coverage checking is always
relative to a world declaration.  Finally, @emph{totality checking}
verifies both coverage and termination, thereby ensuring that any
mode-correct invocation of the type family considered as a logic program
will succeed.  Hence, a total type family represents a total, possibly
non-deterministic, function and can thus be often seen to realize a
meta-theoretic proof.

@menu
* Regular Worlds::              Characterizing parameters and hypotheses
* Input Coverage::              Checking if all cases have been covered
* Totality::                    Verifying if a family is total in its input
* Subordination::               How constants depend on each other
@end menu

@node Regular Worlds, Input Coverage, Coverage, Coverage
@section Regular Worlds

@cindex regular worlds
@cindex regular context
@cindex world checking
@cindex parameter block
@findex %block
@findex %worlds

The adequacy of an encoding using higher-order abstract syntax usually
relies on a characterization of the possible parameters and hypotheses
that may be introduced.  They often occur in blocks of assumptions that
have to be made together in order for a representation to be correct.
We refer to the total collection of assumptions as @emph{regular worlds}
consisting of @emph{blocks}.

In Twelf, we first declare names for such blocks with @code{%block},
then we check if a given type family respects this block structure
with @code{%worlds}.

@example
@group
decs ::=                         % @r{Empty parameter declaration}
       | @{id:term@} decs          % @r{@math{x:A} for parameter @math{x}}
       | @{id@} decs               % @r{@math{x:A} with type @math{A} omitted}

bdecl ::= some decs block decs   % @r{Blocks with indeterminate variables}
        | block decs             % @r{Closed blocks}

worlds ::=                       % @r{Empty world}
         | id                    % @r{Block label @math{b}}
         | id | worlds           % @r{Block label @math{b} and alternatives}

wdecl ::= (worlds) callpats.     % @r{Worlds declaration}

decl ::= @dots{}
       | %block id : bdecl.      % @r{Block declaration with label @math{b}}
       | %worlds wdecl.          % @r{Regular world declaration}
@end group
@end example

The syntactic category of call patterns (@emph{callpats}) was in introduced
in @ref{Termination Declaration}.

Consider the typing judgment from @ref{Sample Program}
which can also be found in file @file{examples/guide/lam.elf}.
We show only the last three declarations here.

@example
@group
of : exp -> tp -> type.

tp_lam : of (lam E) (arrow T1 T2)
          <- (@{x:exp@} of x T1 -> of (E x) T2).

tp_app : of (app E1 E2) T1
          <- of E1 (arrow T2 T1)
          <- of E2 T2.
@end group
@end example

Note that every time the clause @code{tp_lam} is invoked, it introduces
a new parameter @code{x:exp} and also a new assumption @code{of x T}
for some @code{T}.  In order for type inference to work correctly, it
is important that those two hypotheses always occur together.  So, in
general, the context consisting of all hypotheses should have the form
@code{x1:exp, u1:of x1 T1, ..., xn:exp, un:of xn Tn}.  We call this
a @emph{regular context}.  It consists of @emph{blocks} of the
form @code{x:exp, u:of x T} for some @code{T}.

We declare this block, labeled @code{tp_var}, and then verify
that any hypotheses introduced by the type family @code{of}
will have this form.

@example
%block tp_var : some @{T:tp@} block @{x:exp@} @{u:of x T@}.
%worlds (tp_var) (of E T).
@end example

Our encoding of natural deduction (see @pxref{Sample Signature} and file
@file{examples/guide/nd.elf}) shows that regular worlds also arise when
a signature does not have an immediate operational interpretation.
In this case, we may generate either a new parameter @code{x:i}
(in @code{foralli} and @code{existse}) or a new assumption
@code{u:nd A} for some proposition @code{A} (in @code{impi},
@code{ore}, and @code{existse}).  This can be verified with

@example
%block nd_hyp : some @{A:o@} block @{u:nd A@}.
%block nd_parm : block @{x:i@}.
%worlds (nd_hyp | nd_parm) (nd A).
@end example

There are several subtleties in world checking.

@table @asis
@item Weakening.
 The blocks listed in the worlds declaration need not actually be used
anywhere in the type family that is checked.  That is, we can always
weaken blocks.

@item Duplication.
 Arbitrarily many blocks may be introduced before each call to a type
family.  That is, we can always duplicate blocks.

@item No exchange.
 No exchange of declarations, either within a block or between different
blocks is allowed.  This simplifies world checking and improves error
messages, but occasionally suggest some minor rewriting, such as using

@example
... <- (@{x:exp@} of x T -> @{y:exp@} of y S -> ...)
@end example

instead of

@example
... <- (@{x:exp@} @{y:exp@} of x T -> of y S -> ...).
@end example

@item Strengthening.
 The worlds declared for a type family @math{a} cannot anticipate all
possible future uses of @math{a}.  It is therefore legal to use @math{a}
in an extended regular world, as long as it is clear that the additional
hypotheses cannot interfere with @math{a}.  This condition of non-interference
is verified via subordination.
@end table

As a special case of regular world declaration, the form

@example
%worlds () callpats.
@end example

@noindent
declares that the type families in @math{callpats} do not introduce any
new parameters or hypotheses.

@node Input Coverage, Totality, Regular Worlds, Coverage
@section Input Coverage

@cindex input coverage
@findex %covers

Once a set of regular worlds has been declared for a type family, Twelf
can determine if all the possible cases for a given collection of input
arguments are covered.

@example
@group
decl ::= @dots{}
       | %covers mdecl.    %@r{coverage declaration}
@end group
@end example

This form reuses the mode declaration @emph{mdecl} introduced in
@ref{Modes} which comes in a short form (@pxref{Short Mode Declaration})
and long form (@pxref{Full Mode Declaration}).  The coverage checker
selects the arguments declared as input (+) and verifies that the given
family provides a clause for any combination of ground input arguments.
The term @emph{input coverage} emphasizes that we only verify the status
of input arguments to a family, but not indefinite or output arguments.

For example, in order to check that there is a typing rule for every
expression in the type inference code for Mini-ML (@pxref{Sample
Program}), we first declare the regular world and then check input
coverage.

@example
@group
%block tp_var : some @{T:tp@} block @{x:exp@} @{u:of x T@}.
%worlds (tp_var) (of E T).
%covers of +E *T.
@end group
@end example

Coverage checking takes dependent types and subordination into
account, but it is a decidable, syntactic test rather than a
semantic criterion.  This means that it can list the missing
cases when it fails.  For example, if we comment out the typing
rule for application, we obtain the following error message:

@example
@group
Coverage error --- missing cases:
@{E1:exp@} @{E2:exp@} @{T1:tp@} |- of (app E1 E2) T1.
@end group
@end example

The format of the missing cases is @code{G |- A}, where @code{A} is a
form of goal for which does not unify with the head of any clause and
@code{G} is a context declaring the types for the free (existential)
variables in @code{A}.

A more subtle error occurs, if we forget the typing assumption for
a new variable.

@example
@group
...
tp_lam : of (lam E) (arrow T1 T2)
          <- (@{x:exp@} of (E x) T2).

%block tp_var : some @{T:tp@} block @{x:exp@}. % @{u:of x T@}.
%worlds (tp_var) (of E T).
%covers of +E *T.
@end group
@end example

Clearly, coverage has to fail since there is no typing assumption for
bound variables.  In this case we get the error message

@example
@group
Coverage error --- missing cases:
@{T1:tp@} @{#tp_var:@{x:exp@}@} @{T2:tp@} |- of #tp_var_x T2.
@end group
@end example

Here we see the notation for parameters in context blocks.  The goal
@code{of #tp_var_x T2} refers to a parameter called @code{x} in the
context block @code{tp_var}.  The hypotheses available with this block
are listed in the declaration @code{@{#tp_var:@{x:exp@}@}}.  This block
contains no typing assumption for @code{x} and coverage is violated.
Note that this notation can never be an input to Twelf; it is only
used for error messages.

One of the most difficult errors to analyse occurs when coverage is
violated due to argument transposition and dependencies.  In that
situation the error is often reflected in implicit arguments which may
not be easy to discern.  An example of this form is given below in
the next section.

@node Totality, Subordination, Input Coverage, Coverage
@section Totality

@cindex output coverage
@cindex totality
@cindex meta-theorem verification
@findex %total

The most advanced application of coverage checking is verifying the
totality of a given type family.  This is usually used to ascertain that
a given higher-level type family implements a meta-theoretic proof.
Checking that a type family is total requires, in this order, mode
checking, world checking, termination checking, and coverage checking.
Mode and world declarations have to be made separately, while termination
and coverage checking are folded into a single declaration.

@example
@group
decl ::= @dots{}
       | %total tdecl.    %@r{totality declaration}
@end group
@end example

Here @emph{tdecl} is a termination declaration introduced in
@ref{Termination Declaration}.  A totality declaration is processed
in the following steps.

@table @asis
@item Modes.
 Twelf verifies that the type families in @emph{tdecl} all have
declared modes.  Indefinite modes (@code{*}) are not allowed.

@item Worlds.
 Twelf verifies that the type families in @emph{tdecl} all have
declared worlds.

@item Termination.
 Twelf executes the termination checker using the @emph{tdecl}.  If it
passes this test, it means that any well-moded query for the given
families terminates, either with success or failure.

@item Input Coverage.
 Twelf then executes coverage checking according on the input arguments
to the families based on the prior mode declarations.  If the family
passes this test, it means that a clause applies to any well-moded query
with free existential variables as output arguments.

@item Output Coverage.
 Twelf finally checks all subgoals in the given program in a final pass
If the output arguments to the subgoal cover all the possible values
that may be returned in these position, we say that @emph{output
coverage} succeeds.  In the simplest and most frequent case the output
argument is an existential variable of most general type, which automatically
covers all possibilities for closed terms of the given type.
@end table

As an example, we use type preservation, a continuation of the
sample programs for type inference and evaluation in Mini-ML
(see @pxref{Sample Program} and file @file{examples/guide/lam.elf}).
This can be proven automatically (see @pxref{Sample Theorems}), but
we can also give the proof by hand and have Twelf verify it via
totality checking.

First, the correct program and verification.  The type preservation
theorem states that for any closed evaluation @code{D:eval E V} and
typing derivation @code{P:of E T} there exists a typing derivation
@code{Q:of V T}.

@example
@group
tps : eval E V -> of E T -> of V T -> type.

tps_lam : tps (ev_lam) (tp_lam P) (tp_lam P).
tps_app : tps (ev_app D3 D2 D1) (tp_app P2 P1) Q
           <- tps D1 P1 (tp_lam Q1')
           <- tps D2 P2 Q2
           <- tps D3 (Q1' V2 Q2) Q.

%mode tps +D +P -Q.
%worlds () (tps D P _).
%total D (tps D P _).
@end group
@end example

The mode declaration specifies that the evaluation and typing derivation
for @code{E} are input, while the typing derivation for @code{V} is
output.  The worlds declaration expresses that expressions and types
must be closed, that is, not depend on any parameters.  The final
totality declaration claims that the logic programming execution of
@code{tps D P Q} for ground @code{D} and @code{P} and free existential
variable @code{Q} terminates because @code{tps} is inductively defined
based on the structure of @code{D}.  Note that this implies that the
meta-theorem of type preservation holds, because the type family
@code{cps} realizes the proof: it can always compute a typing derivation
@code{Q:of V T} when given arbitrary evaluation @code{D:eval E V} and
typing derivation @code{P:of E T}.

The signature above passes all three tests.  The main subtlety in this
example lies in the output coverage of the first subgoal

@example
  <- tps D1 P1 (tp_lam Q1')
@end example

How does Twelf know that any typing derivation @code{Q1} returned by a
call @code{tps D1 P1 Q1} must in fact have the form @code{tp_lam Q1'}
for some @code{Q1'}?  Here, this follows by the structure of the
indexed types: @code{Q1 : of (lam [x] E1' x) (arrow T2 T1)} for some
@code{E1'}, @code{T1}, and @code{T2}.  Hence there remains only one
applicable top-level constructor for @code{Q1}, namely @code{tp_lam},
which corresponds to the typing rule lambda-abstraction.  In informal
proofs, we refer to this as @emph{inversion} or @emph{genericity}.

For the sake of illustration, we introduce two bugs into our proof
and analyse the error message.  In the first, we reverse the arguments
@code{D2} and @code{D3} in rule @code{tps_app}.

@example
tps_app : tps (ev_app D2 D3 D1) (tp_app P2 P1) Q
           <- tps D1 P1 (tp_lam Q1')
           <- tps D2 P2 Q2
           <- tps D3 (Q1' V2 Q2) Q.
@end example

The resulting clause still passes all test up to input coverage, which
fails with the message

@example
Coverage error --- missing cases:
@{E1:exp@} @{E2:exp@} @{E3:exp@} @{T1:tp@} @{E4:exp -> exp@} @{E5:exp@}
   @{D1:eval (E4 E5) E3@} @{D2:eval E2 E5@}
   @{D3:eval E1 (lam ([e:exp] E4 e))@} @{T2:tp@} @{P1:of E2 T2@}
   @{P2:of E1 (arrow T2 T1)@} @{P3:of E3 T1@}
   |- tps (ev_app D1 D2 D3) (tp_app P1 P2) P3.
@end example

This clearly identifies the missing case, but it does not help much in
identifying which the rule @code{tps_app} fails to cover the given case.
If look back at the declaration for @code{tps_app} after reconstruction

@example
tps_app :
   @{E1:exp -> exp@} @{V2:exp@} @{T1:tp@} @{D3:eval (E1 V2) V2@} @{T2:tp@}
      @{Q1':@{e:exp@} of e T2 -> of (E1 e) T1@} @{Q2:of V2 T2@} @{Q:of V2 T1@}
      @{D2:eval (E1 V2) V2@} @{P2:of (E1 V2) T2@} @{E2:exp@}
      @{D1:eval E2 (lam ([e:exp] E1 e))@} @{P1:of E2 (arrow T2 T1)@}
      tps D3 (Q1' V2 Q2) Q -> tps D2 P2 Q2 -> tps D1 P1 (tp_lam Q1')
         -> tps (ev_app D2 D3 D1) (tp_app P2 P1) Q.
@end example

@noindent
we see that @code{@{D3:eval (E1 V2) V2@}} which is clearly non-sensical
and points to an argument ordering problem (@code{V} and @code{V2}
have been identified).

As the second example of an intentional problem, we use an apparently
correct implementation of a @code{copy} family implements the identity
relation on expressions recursively (see file
@file{example/guide/lam.elf}).

@example
@group
cp : exp -> exp -> type.
cp_app : cp (app E1 E2) (app F1 F2)
          <- cp E1 F1
          <- cp E2 F2.

cp_lam : cp (lam [x] E x) (lam [x] F x)
          <- (@{x:exp@} @{y:exp@} cp x y -> cp (E x) (F y)).

%mode cp +E -F.
%block cp_var : block @{x:exp@} @{y:exp@} @{u:cp x y@}.
%worlds (cp_var) (cp E _).
%total E (cp E _).
@end group
@end example

This fails with the message

@example
Coverage error --- missing cases:
@{#cp_var:@{x:exp@} @{y:exp@} @{u:cp x y@}@} @{E1:exp@} |- cp #cp_var_y E1.
@end example

@noindent
because the parameter @code{y:exp} is not accompanied by an assumption
on how to copy @code{y}.  Twelf does not perform the global analysis
that would be necessary to show that @code{y} actually can never occur
as a first argument to @code{cp}.  If we introduce such an assumption,
for example, @code{cp y y},

@example
@group
cp : exp -> exp -> type.
cp_app : cp (app E1 E2) (app F1 F2)
          <- cp E1 F1
          <- cp E2 F2.

cp_lam : cp (lam [x] E x) (lam [x] F x)
          <- (@{x:exp@} @{y:exp@} cp x y -> cp y y -> cp (E x) (F y)).

%mode cp +E -F.
%block cp_var : block @{x:exp@} @{y:exp@} @{u:cp x y@} @{w:cp y y@}.
%worlds (cp_var) (cp E _).
%total E (cp E _).
@end group
@end example

@noindent
then totality checking still fails.  The error message

@example
Totality: Output of subgoal not covered
Output coverage error --- missing cases:
@{E1:exp -> exp@} @{E2:exp -> exp -> exp@}
   |- @{x:exp@} @{y:exp@} cp x y -> cp y y -> cp (E1 x) (E2 x y).
@end example

@noindent
shows that Twelf expected the output argument of the recursive call to
possibly depend on both @code{x} and @code{y}, while the corresponding
pattern @code{F y} allowed dependency only on @code{y}.  Again, Twelf
does not perform the global analysis necessary to show that @code{x} can
never appear in the output argument of @code{cp}.

A correct and checkable implementation of @code{cp} introduces only one new
parameter, thereby avoiding the problems above.

@example
@group
cp : exp -> exp -> type.
cp_app : cp (app E1 E2) (app F1 F2)
          <- cp E1 F1
          <- cp E2 F2.

cp_lam : cp (lam [x] E x) (lam [x] F x)
          <- (@{x:exp@} cp x x -> cp (E x) (F x)).

%mode cp +E -F.
%block cp_var : block @{x:exp@} @{u:cp x x@}.
%worlds (cp_var) (cp E _).
%total E (cp E _).
@end group
@end example

@node Subordination,  , Totality, Coverage
@section Subordination

@cindex subordination
@cindex freezing families
@findex Twelf.Print.subord
@findex %freeze

An important component for termination checking and coverage
checking is @emph{subordination} @cite{Virga 99, Ph.D. Thesis}.
We say that type family @var{b} subordinates type family
@var{a} (written @code{@var{b} |> @var{a}}) if a term of typ
@code{@var{b} @dots{}}
might occur as a subterm of a term of type @code{@var{a} @dots{}}.
From the point of view of the application in Twelf, it is
the contrapositive that is important: if @var{b} does not
subordinate @var{a}, then no subterm of type @code{@var{a} @dots{}}
can occur in a subterm of type @code{@var{b} @dots{}}.  The notion
of occurrence here refers to terms in canonical form.

As Twelf performs type reconstruction, it incrementally
keeps track of the subordination relation.  It can be viewed
at any time with the

@example
Twelf.Print.subord ();
@end example

command.  For each type family it shows the families that it
subordinates.

Subordination information is used in @ref{Termination} and
@ref{Coverage}.

Sometimes it is necessary to ensure that a given type
family is not extended with additional constructors that might
invalidate meta-theorems or add new (unwanted) axioms to a theory
represented in LF.  In order to prohibit further extensions to
some type families, issue

@example
%freeze @var{a1} @dots{} @var{an}.
@end example

to prevent further declarations of type @var{a1} through @var{an}
or any other type family subordinated by one of the @var{a}'s.

@node Theorem Prover, ML Interface, Coverage, Top
@chapter Theorem Prover

@cindex theorem prover
@cindex meta-logic

@noindent
@strong{Disclaimer:} The theorem proving component of Twelf is in an
even more experimental stage and currently under active development.

Nonetheless, it can prove a number of interesting examples automatically
which illustrate our approach the meta-theorem proving which is
described in @cite{Schuermann and Pfenning 1998, CADE}.  These examples
include type preservation for Mini-ML, one direction of compiler
correctness for different abstract machines, soundness and completeness
for logic programming interpreters, and the deduction theorem for
Hilbert's formulation of propositional logic.  These and other examples
can be found in the example directories of the Twelf distribution
(@pxref{Examples}).

A @emph{theorem} in Twelf is, properly speaking, a meta-theorem: it
expresses a property of objects constructed over a fixed LF signature.
Theorems are stated in the meta-logic M2 whose quantifiers range over LF
objects.  In the simplest case, we may just be asserting the existence
of an LF object of a given type.  This only requires direct search for a
proof term, using methods inspired by logic programming.  More
generally, we may claim and prove forall/exists statements which allow
us to express meta-theorems which require structural induction, such as
type preservation under evaluation in a simple functional language
(@pxref{Sample Program}).

@menu
* Theorem Declaration::         Declaring and proving theorems
* Sample Theorems::             Two examples
* Proof Steps::                 Basic operations of the prover
* Search Strategies::           How Twelf searches
* Proof Realizations::          Using automatically constructed proofs 
@end menu

@node Theorem Declaration, Sample Theorems, Theorem Prover, Theorem Prover
@section Theorem Declaration

@cindex theorem declarations
@cindex declarations, theorem
@cindex universal quantifier
@cindex existential quantifier
@cindex quantifier, universal
@cindex quantifier, existential
@cindex regular context
@cindex context, regular
@findex %theorem
@findex %prove
@findex %establish
@findex %assert
@findex Twelf.unsafe

The theorem proving component of Twelf is in an experimental stage and
currently under active development.  This documentation describes the
present intermediate state.

There are three forms of declarations related to the proving of theorems
and meta-theorems.  The first, @code{%theorem}, states a theorem as a
meta-formula (@code{mform}) in the meta-logic M2 defined below.  The
second, @code{%prove}, gives a resource bound, a theorem, and an
induction ordering and asks Twelf to search for a proof.  After a
@code{%prove} declaration succeeds, the theorem will be made available
as a lemma to subsequent proofs.  In order to avoid that, Twelf offers
the form @code{%establish} which is like @code{%prove}, but the
established theorem will never be used in subsequent proofs.

Note that a well-typed @code{%theorem} declaration always succeeds,
while the @code{%prove} and @code{%establish} declarations only succeed
if Twelf can find a proof.

@example
@group
dec ::= @{id:term@}         % @r{@math{x:A}}
      | @{id@}              % @r{@math{x}}

decs ::= dec
       | dec decs

ctx ::= some decs pi decs
      | some decs pi decs | ctx

mform ::= forallG ctx mform  % @r{regular contexts}
        | forall* decs mform % @r{implicit universal}
        | forall decs mform  % @r{universal}
        | exists decs mform  % @r{existential}
        | true               % @r{truth}

thdecl ::= id : mform        % @r{theorem name @math{a}, spec}

pdecl ::= nat order callpats % @r{bound, induction order, theorems}

decl ::= @dots{}
       | %theorem thdecl.  % @r{theorem declaration}
       | %prove pdecl.     % @r{prove declaration}
       | %establish pdecl.  % @r{prove declaration, do not use as lemma later}
       | %assert callpats.  % @r{assert theorem (requires @code{Twelf.unsafe})}
@end group
@end example

The prover only accepts quantifier alternations of the form
@code{forall* @var{decs} forall @var{decs} exists @var{decs} true}.
Note that the implicit quantifiers (which will be suppressed when
printing the proof terms) must all be collected in front, but
after the specification of the regular contexts.

The syntax and meaning of @code{order} and @code{callpats} are explained
in @ref{Termination}, since they are also critical notions in the
simpler termination checker.

@node Sample Theorems, Proof Steps, Theorem Declaration, Theorem Prover
@section Sample Theorems

As a first example, we use the theorem prover to establish a simple
theorem in first-order logic (namely that @math{A} implies @math{A} for
any proposition @math{A}), using the signature for natural deduction
(@pxref{Sample Signature}).

@example
@group
%theorem
trivI : exists @{D:@{A:o@} nd (A imp A)@}
        true.

%prove 2 @{@} (trivI D).
@end group
@end example

The empty termination ordering @code{@{@}} instructs Twelf not to use
induction to prove the theorem.  The declarations above succeed, and
with the default setting of @code{3} for @code{Twelf.chatter} we see

@example
@group
%theorem trivI : (@{A:o@} nd (A imp A)) -> type.
%prove 2 @{@} (trivI D).
%QED
%skolem trivI#2 : @{A:o@} nd (A imp A).
@end group
@end example

The line starting with @code{%theorem} shows the way the theorem will be
realized as a logic program predicate.  In earlier versions this
was such a logic program was actually constructed; at present this feature
has been disabled while the implementation has been improved to allow
regular contexts.

The second example is the type preservation theorem for evaluation in
the lambda-calculus.  This is a continuation of the example in Section
@ref{Sample Program} in the file @file{examples/guide/lam.elf}.
Type preservation states that if and expression @code{E} has type
@code{T} and @code{E} evaluates to @code{V}, the @code{V} also has
type @code{T}.  This is expressed as the following @code{%theorem}
declaration.

@example
@group
%theorem
tpsa : forall* @{E:exp@} @{V:exp@} @{T:tp@}
       forall @{D:eval E V@} @{P:of E T@}
       exists @{Q:of V T@}
       true.
@end group
@end example

The proof proceeds by structural induction on @code{D}, the evaluation
from @code{E} to @code{V}.  Therefore we can search for the proof with
the following declaration (where the size bound of @code{5} on proof
term size is somewhat arbitrary).

@example
%prove 5 D (tpsa D P Q).
@end example

Twelf finds and displays the proof easily.  The resulting program is
installed in the global signature and can then be used to apply type
preservation in subsequent proofs (@pxref{Proof Realizations}).

The third example illustrates the use of regular contexts.
We use the theorem prover to establish a simple
theorem, namely that for every input to the copy predicate
@code{cp} in @ref{Totality} (see also file @file{examples/guide/lam.elf})
there exists a corresponding output.  This essentially is just
a reformulation of the totality checking question for @code{cp},
except that we use the more heavyweight tool of the theorem
prover.

@example
@group
%theorem cpt : forallG (pi @{x:exp@} @{y:cp x x@})
               forall @{D:exp@}
	       exists @{F:exp@} @{C:cp E F@}
               true.
%prove 5 E (cpt E _ _).
@end group
@end example

The termination ordering @code{E} instructs Twelf to do induction
over @code{E} to prove the theorem.  The @code{%prove} command executes
the proof search.  In addition, if a proof has been found, the lemma is
made accessible to the proof search evoked by subsequent theorems and
lemmas, and which might slow it down accordingly. If a lemma is not used
in subsequent proofs, the user can use @code{%establish} instead of
@code{%prove} and it will not be made available.

For certain theorems, the theorem prover will not be able to find a
proof, even that it should.  This behavior could be caused by an
incompleteness in the implementation (which still exist, but which
should be removed in the next release of Twelf), or a enormously huge
search space, which disallows the underlying LF theorem to construct a
proof term.  In these situations, one can still try to prove
subsequent theorem and lemmas by asserting the correctness of the
lemma in question.  This is done by the @code{%assert} command.
For the theorem above, one could

@example
%assert (cpt _ _ _).
@end example

after the @code{Twelf.unsafe} mode has been activated.

@node Proof Steps, Search Strategies, Sample Theorems, Theorem Prover
@section Proof Steps

@cindex filling
@cindex recursion
@cindex splitting
@findex Twelf.Prover.maxRecurse
@findex Twelf.Prover.maxSplit

We expect the proof search component of Twelf to undergo major changes
in the near future, so we only briefly review the current state.

Proving proceeds using three main kinds of steps:

@table @asis
@item Filling
 Using iterative deepening, Twelf searches directly for objects to fill
the existential quantifiers, given all the constants in the signature
and the universally quantified variables in the theorem.  The number of
constructors in the answer substitution for each existential quantifier
is bounded by the size which is given as part of the @code{%prove}
declaration, thus guaranteeing termination (in principle).

@item Recursion
 Based on the termination ordering, Twelf appeals to the induction
hypothesis on smaller arguments.  If there are several ways to use the
induction hypothesis, Twelf non-deterministically picks one which has
not yet been used.  Since there may be infinitely many different ways to
apply the induction hypothesis, the parameter
@code{Twelf.Prover.maxRecurse} bounds the number of recursion steps in
each case of the proof.

@item Splitting
 Based on the types of the universally quantified variables, Twelf
distinguishes all possible cases by considering all constructors in
the signatures.  It never splits a variable which appears as an
index in an input argument, and if there are several possibilities
it picks the one with fewest resulting cases.  Splitting can go on
indefinitely, so the parameter @code{Twelf.Prover.maxSplit} bounds
the number of times a variable may be split.
@end table

@node Search Strategies, Proof Realizations, Proof Steps, Theorem Prover
@section Search Strategies

@cindex search strategy
@findex Twelf.Prover.strategy
@findex Twelf.Prover.FRS
@findex Twelf.Prover.RFS

The basic proof steps of filling, recursion, and splitting are
sequentialized in a simple strategy which never backtracks.  First we
attempt to fill all existential variables simultaneously.  If that fails
we recurse by trying to find new ways to appeal to the induction
hypothesis.  If this is not possible, we pick a variable to distinguish
cases and then prove each subgoal in turn.  If none of the steps
are possible we fail.

This behavior can be changed with the parameter
@code{Twelf.Prover.strategy} which defaults to @code{Twelf.Prover.FRS}
(which means Filling-Recursion-Splitting).  When set to
@code{Twelf.Prover.RFS} Twelf will first try recursion, then filling,
followed by splitting.  This is often faster, but fails in some cases
where the default strategy succeeds.

@node Proof Realizations,  , Search Strategies, Theorem Prover
@section Proof Realizations

@cindex proof realizations
@cindex executing proofs

Proofs of meta-theorems can be realized as logic programs.  This is
presently disabled.  We still describe the possibility below in
anticipation of future versions.  On the other hand, theorems that
have been proved will be skolemized and used in proof of subsequent
theorems.  However, they will not be used for search.

A logic program is a relational representation of the constructive proof
and can be executed to generate witness terms for the existentials from
given instances of the universal quantifiers.  As an example, we
consider once more type preservation (@pxref{Sample Theorems}).

After the declarations,

@example
@group
%theorem
tpsa : forall* @{E:exp@} @{V:exp@} @{T:tp@}
       forall @{D:eval E V@} @{P:of E T@}
       exists @{Q:of V T@}
       true.

%prove 5 D (tpsa D P Q).
@end group
@end example

@noindent
Twelf answers

@example
@group
/tps/tp_lam/ev_lam/: 
   tps ev_lam (tp_lam ([x:exp] [P2:of x T1] P1 x P2))
      (tp_lam ([x:exp] [P3:of x T1] P1 x P3)).

/tps/tp_app/ev_app/tp_lam/: 
   tps (ev_app D1 D2 D3) (tp_app P1 P2) P6
      <- tps D3 P2 (tp_lam ([x:exp] [P4:of x T2] P3 x P4))
      <- tps D2 P1 P5
      <- tps D1 (P3 E5 P5) P6.
@end group
@end example

@noindent
which is the proof of type preservation expressed as a logic program
with two clauses: one for evaluation of a lambda-abstraction, and one
for application.  Using the @code{%solve} declaration (@pxref{Solve
Declaration}) we can, for example, evaluate and type-check the identity
applied to itself and then use type preservation to obtain a typing
derivation for the resulting value.

@example
@group
e0 = (app (lam [x] x) (lam [y] y)).
%solve p0 : of e0 T.
%solve d0 : eval e0 V.
%solve tps0 : tps d0 p0 Q.
@end group
@end example

Recall that @code{%solve c : V} executes the query @code{V} and defines
the constant @code{c} to abbreviate the resulting proof term.

@node ML Interface, Twelf Server, Theorem Prover, Top
@chapter ML Interface

@cindex ML interface
@findex open

The Twelf implementation defines a number of ML functions embedded in
structures which can be called to load files, execute queries, and set
environment parameters such as the verbosity level of the interaction.
These functions and parameters are available in the @code{Twelf}
structure.  If you open the @code{Twelf} structure with

@example
open Twelf
@end example

@noindent
after compiling and loading Twelf, you do not have to type the
@samp{Twelf.} to the functions shown below.

Previous implementations of Elf offered a stand-alone command
interpreter but this has not yet been ported.  To exit Twelf and
ML call @code{Twelf.OS.exit ();}.

@menu
* Configurations::              Managing groups of Twelf files
* Loading Files::               Loading individual files
* Environment Parameters::      Controlling appearance and verbosity of Twelf
* Signature Printing::          Printing of signatures
* Tracing and Breakpoints::     Debugging tools
* Timing Statistics::           Gathering statistics
* Twelf Signature::             The top-level signature
@end menu

@node Configurations, Loading Files, ML Interface, ML Interface
@section Configurations

@cindex Configurations
@cindex files, configuration
@findex Twelf.OS.getDir
@findex Twelf.OS.chDir
@findex Twelf.Config.suffix
@findex Twelf.Config.read
@findex Twelf.Config.load
@findex Twelf.Config.append
@findex Twelf.Config.define
@findex Twelf.OK
@findex Twelf.ABORT
@findex Twelf.make

Groups of Twelf files are managed in @emph{configurations}.  A
configuration is defined by a file, by convention called
@file{sources.cfg}, which resides in the same directory as the Twelf
source files.  The configuration file must contain at most one
Twelf source file per line, and the files must be listed in
dependency order.  A configuration @var{config} can then be
defined from the file by the ML declaration

@example
val @var{config} = Twelf.Config.read "sources.cfg";
@end example

By convention, the filenames end in the extensions
@table @samp
@item .elf
 for constant declarations and definitions or mixed files,
@item .quy
 for files which contain query declarations,
@item .thm
 for files which contain @code{%theorem} and @code{%proof} declarations.
@end table

File names may not contain whitespace.  They are interpreted relative to
the current working directory of ML, but resolved into absolute path
names when the configuration file is read.  To change the current
working directory call

@example
@group
Twelf.OS.getDir ();               (* get working directory *)
Twelf.OS.chDir "@var{directory}"; (* change working directory *)
@end group
@end example

As an example, we show how the Mini-ML configuration is defined and
loaded, assuming your current working directory is the root directory of
Twelf.

@example
@group
Twelf.make "examples/mini-ml/sources.cfg";
@end group
@end example

The call to @code{Twelf.make} returns either @code{Twelf.OK} or
@code{Twelf.ABORT}.  It reads each file in turn, starting from an empty
signature, printing the results of type reconstruction and search based
on the value of the @code{Twelf.chatter} variable (@pxref{Environment
Parameters}).  If another configuration or file has previously been
read, all the declarations will first be deleted so that
@code{Twelf.make} always starts from the same state.

To load a configuration, use @code{Twelf.Config.load @var{config}}.
This is will first reset the state and then load @var{config}.
In order to avoid resetting the state, use
@code{Twelf.Config.append @var{config}} instead.

Loading a configuration will stop at the first error encountered, issue
an appropriate message and return @code{Twelf.ABORT}.  If there is an
unexpected internal error (which indicates a bug in the Twelf
implementation), it raises an uncaught exception instead and returns
to the ML top-level.

To explore the behavior of programs interactively, you may call the
Twelf top-level with

@example
Twelf.top ();
@end example

@noindent
which is explained in @ref{Interactive Queries}.

The default suffix for configuration files is @file{cfg}; it can
be changed with

@example
Twelf.Config.suffix := "@var{suffix}";
@end example

although this may confuse the Twelf server.

Twelf configurations can also be defined explicitly from a list of
file names with

@example
Twelf.Config.define ["@var{file1}, @dots{}, @var{filen}"];
@end example

@node Loading Files, Environment Parameters, Configurations, ML Interface
@section Loading Files

@cindex loading files
@cindex files, loading
@findex Twelf.reset
@findex Twelf.loadFile

Twelf also allows direct management of the signature by loading
individual files.  This is generally not recommended because successive
declarations simply accumulate in the global signature which may lead to
unexpected behavior.  The relevant function calls are

@example
@group
Twelf.reset ();
Twelf.loadFile "@var{file}";
@end group
@end example

@noindent
where @code{Twelf.reset ()} resets the current global signature to
be empty and @code{Twelf.readFile "@var{file}"} loads the given
@var{file} whose name is interpreted relative to the current working
directory.

@strong{Caution:} Reading a file twice will not replace the declarations
of the first pass by the second, but simply add them to the current
signature.  If names are reused, old declarations will be shadowed, but
they are still in the global signature and might be used in the search
for a solution to a query or in theorem proving, leading to unexpected
behavior.  When in doubt, use configurations (@pxref{Configurations}) or
call @code{Twelf.reset ()}.

@node Environment Parameters, Signature Printing, Loading Files, ML Interface
@section Environment Parameters

@cindex parameters, environment
@cindex environment parameters

Various flags and parameters can be used to modify the behavior of Twelf
and the messages it issues.  They are given below with the assignment
of the default value.

@table @code
@item Twelf.chatter := 3;
@findex Twelf.chatter
  Controls the detail of the information which is printed when signatures
are read.
@table @code
@item 0
 Nothing.
@item 1
 Just file names.
@item 2
 File names and number of query solutions.
@item 3
 Each declarations after type reconstruction.
@item 4
 Debug information.
@item 5
 More debug information.
@item 6
 Even more debug information.
@end table

@item Twelf.doubleCheck := false;
@findex Twelf.doubleCheck
 If @code{true}, each declaration is checked again for type correctness
after type reconstruction.  This is expensive and useful only for your
peace of mind, since type checking is significantly simpler than
type reconstruction.

@item Twelf.unsafe := false;
@findex Twelf.unsafe
 If @code{true} it will allow the @code{%assert} declaration to assert
theorems without proof.

@item Twelf.Print.implicit := false;
@findex Twelf.Print.implicit
 If @code{true}, implicit arguments (normally elided) are printed.
Sometimes this is useful to track particularly baffling errors.

@item Twelf.Print.depth := NONE;
@findex Twelf.Print.depth
 If @code{SOME(d)} then terms deeper than level @code{d} are printed
as @samp{%%}.

@item Twelf.Print.length := NONE;
@findex Twelf.Print.length
 If @code{SOME(l)} then argument lists longer than @code{l} are truncated
with @samp{...}.

@item Twelf.Print.indent := 3;
@findex Twelf.Print.indent
 Controls the amount of indentation for printing nested terms.

@item Twelf.Print.width := 80;
@findex Twelf.Print.width
 The value used to decide when to break lines during printing of terms.

@item Twelf.Trace.detail := 1;
@findex Twelf.Trace.detail
 Controls the detail in information during tracing.
See @ref{Tracing and Breakpoints}

@item Twelf.Compile.optimize := true;
@findex Twelf.Compile.optimize
 Determines whether a minimal amount of optimization during
translation from signature to program is carried out.  If set to
@code{false}, unification can be traced in more detail.

@item Twelf.Prover.strategy := Twelf.Prover.FRS;
@findex Twelf.Prover.strategy
 Determines the strategy, where @code{F}=Filling, @code{R}=Recursion, and
@code{S}=Splitting.  Can also be @code{Twelf.Prover.RFS}.

@item Twelf.Prover.maxSplit := 2;
@findex Twelf.Prover.maxSplit
 The maximal number of generations of a variable introduced
by splitting.  Setting is to @code{0} will prohibit proof by cases.

@item Twelf.Prover.maxRecurse := 10;
@findex Twelf.Prover.maxRecurse
 The maximal number of appeals to the induction hypothesis in any
case during a proof.

@item Twelf.Table.strategy := Twelf.Table.Variant;
@findex Twelf.Table.strategy
 Determines the subsumption strategy for tabled logic programming which is
either @code{Twelf.Table.Variant} or @code{Twelf.Table.Subsumption}.

@item Twelf.Table.strengthen := false;
@findex Twelf.Table.strengthen
 Determines whether table entry lookup takes subordination into
account or not.
@end table


@node Signature Printing, Tracing and Breakpoints, Environment Parameters, ML Interface
@section Signature Printing

@cindex signature printing
@cindex printing, signature
@cindex TeX output
@findex Twelf.Print.sgn
@findex Twelf.Print.prog
@findex Twelf.Print.TeX.sgn
@findex Twelf.Print.TeX.prog

Twelf provides two ways to print the current global signature.

@example
@group
Twelf.Print.sgn ();
Twelf.Print.prog ();
@end group
@end example

The first prints the signature, using only forward arrows @code{->}, the
second will print the signature interpreted as a logic programming using
backward arrows @code{<-}.  Depending on your goals, one or the other
might be easier to use.

Output can also be generated in TeX format.  The necessary library
files can be found in the @file{tex/} subdirectory of the distribution.
To print the current signature using TeX format, use

@example
@group
Twelf.Print.TeX.sgn ();
Twelf.Print.TeX.prog ();
@end group
@end example

@noindent
with the same interpretation as the plain text printing commands
above.

@node Tracing and Breakpoints, Timing Statistics, Signature Printing, ML Interface
@section Tracing and Breakpoints

Twelf no incorporates some rudimentary tracing facilities for the logic
programming interpreter of signatures.  This is best used within the
Emacs server, but it is also available within the ML Interface.  It is
not available with the tabled logic programming interpreter.  Also, when
optimizations are enabled (@code{Twelf.Compile.optimize} is
@code{true}), unification can not be traced.

A tracing specification may be associated with constants in
a signature.

@table @code
@item Twelf.Trace.None
@findex Twelf.Trace.None
 Do not trace.
@item Twelf.Trace.Some ["@math{c1}",...,"@math{cn}"]
@findex Twelf.Trace.Some
 Trace clauses (object-level constants) or predicates (type families)
named @math{c1} through @math{cn}.
@item Twelf.Trace.All
@findex Twelf.Trace.All
 Trace all clauses and predicates.
@end table

One can either suspend the execution when a specified clause or
predicate is invoked, or simply trace goals

@table @code
@item Twelf.Trace.trace @math{spec}
@findex Twelf.Trace.trace
@item Twelf.Trace.break @math{spec}
@findex Twelf.Trace.break
@end table

When a breakpoint is set, execution will halt and ask for an action from
the user.  This consists of a (possible empty) line of input followed by
@key{RET}.  Current, the following actions are available.

@example
@group
<newline> - continue --- execute with current settings
n - next --- take a single step
r - run --- remove all breakpoints and continue
s - skip --- skip until current subgoals succeeds, is retried, or fails
s n - skip to n --- skip until goal (n) is considered
t - trace --- trace all events
u - untrace --- trace no events
d n - detail --- set trace detail to n (0, 1, or 2)
h - hypotheses --- show current hypotheses
g - goal --- show current goal
i - instantiation --- show instantiation of variables in current goal
v X1 ... Xn - variables --- show instantiation of X1 ... Xn
? for help 
@end group
@end example

The detail of the trace information can be set with the
variable @code{Trace.detail := @math{n};} to one of
@findex Trace.detail

@table @code
@item 0
 print no information
@item 1
 print standard information
@item 2
 print details of unification
@end table

Note that if @code{Twelf.Compile.optimize} is @code{true}, then details
of unification cannot be shown.  It is possible to examine and reset the
state of the currently traced predicates with

@table @code
@item Twelf.Trace.show ();
@findex Twelf.Trace.show
@item Twelf.Trace.reset ();
@findex Twelf.Trace.reset
@end table

@node Timing Statistics, Twelf Signature, Tracing and Breakpoints, ML Interface
@section Timing Statistics

@cindex running time
@cindex timing statistics
@cindex statistics

Twelf has a few utilities to collect run-time statistics which are
useful mainly for the developers.  They are collected in the
structure @code{Timers}.  Timing information is cumulative
in an ML session.

@table @code
@item Twelf.Timers.show ();
@findex Twelf.Timers.show
 Show the value of timers and reset them to zero.
@item Twelf.Timers.reset ();
@findex Twelf.Timers.reset
 Simply reset all timers to zero.
@item Twelf.Timers.check ();
@findex Twelf.Timers.check
 Display the value of timers, but do not reset them.
@end table

@noindent
@strong{Caution:} Normally, the various times are exclusive, except that
the runtime includes the garbage collection time which is shown
separately.  However, there is a problem the time for printing the
answer substitution to a query is charged both to @code{Printing} and
@code{Solving}.

@node Twelf Signature,  , Timing Statistics, ML Interface
@section Twelf Signature

@findex signature TWELF
@findex structure Twelf

For reference, here is the ML signature @code{TWELF} of the @code{Twelf}
structure which defines most functions and flags relevant to loading
and executing Twelf programs.

@example
@group
signature TWELF =
sig
structure Print :
sig
  val implicit : bool ref           (* false, print implicit args *)
  val depth : int option ref        (* NONE, limit print depth *)
  val length : int option ref       (* NONE, limit argument length *)
  val indent : int ref              (* 3, indentation of subterms *)
  val width : int ref               (* 80, line width *)

  val sgn : unit -> unit            (* print signature *)
  val prog : unit -> unit           (* print signature as program *)
  val subord : unit -> unit         (* print subordination relation *)
  val domains : unit -> unit        (* list constraint domains *)

  structure TeX :                   (* print in TeX format *)
  sig
    val sgn : unit -> unit          (* print signature *)
    val prog : unit -> unit         (* print signature as program *)
  end
end
@end group

@group
structure Trace :
sig 
  datatype 'a Spec =                (* trace and breakpoint spec *)
    None                            (* no tracing, default *)
  | Some of 'a list                 (* list of clauses and families *)
  | All                             (* trace all clauses and families *)

  val trace : string Spec -> unit   (* trace clauses and families *)
  val break : string Spec -> unit   (* break at clauses and families *)
  val detail : int ref              (* 0=none, 1=default, 2=unify *)

  val show : unit -> unit           (* show trace, break, and detail *)
  val reset : unit -> unit          (* reset trace, break, and detail *)
end
@end group

@group
structure Timers :
sig
  val show : unit -> unit           (* show and reset timers *)
  val reset : unit -> unit          (* reset timers *)
  val check : unit -> unit          (* display, but not no reset *)
end
@end group

@group
structure OS :
sig
  val chDir : string -> unit        (* change working directory *)
  val getDir : unit -> string       (* get working directory *)
  val exit : unit -> unit           (* exit Twelf and ML *)
end
@end group

@group
structure Compile :
sig
  val optimize : bool ref          (* true, optimize clauses *)
end
@end group

@group
structure Table : 
sig 
  datatype Strategy = Variant | Subsumption

  val strategy : Strategy ref      (* Variant, tabling strategy *)
  val strengthen : bool ref        (* false, tabling optimization *)

  val top : unit -> unit           (* top-level for tabled queries *)
end 
@end group

@group
structure Recon :
sig
  datatype TraceMode = Progressive | Omniscient
  val trace : bool ref		   (* false, trace term reconstruction *)
  val traceMode : TraceMode ref	   (* Omniscient, trace mode *)
end
@end group

@group
structure Prover :
sig
  datatype Strategy = RFS | FRS    (* F=Fill, R=Recurse, S=Split *)
  val strategy : Strategy ref      (* FRS, strategy used for %prove *)
  val maxSplit : int ref           (* 2, bound on splitting  *)
  val maxRecurse : int ref         (* 10, bound on recursion *)
end
@end group

@group
val chatter : int ref               (* 3, chatter level *)
val doubleCheck : bool ref          (* false, check internal types *)
val unsafe : bool ref               (* false, allow %assert w/o proof *)
@end group

@group
datatype Status = OK | ABORT        (* return status *)

val reset : unit -> unit            (* reset global signature *)
val loadFile : string -> Status     (* load file *)
val readDecl : unit -> Status       (* read declaration interactively *)
val decl : string -> Status         (* print declaration of constant *)

val top : unit -> unit              (* top-level for queries *)
@end group

@group
structure Config :
sig
  type config                       (* configuration *)
  val suffix : string ref           (* suffix of configuration files *)
  val read : string -> config       (* read config file *)
  val load : config -> Status       (* reset and load configuration *)
  val append : config -> Status     (* load configuration (w/o reset) *)
  val define : string list -> config (* define configuration *)
end

val make : string -> Status         (* read and load configuration *)

val version : string                (* Twelf version *)
end;  (* signature TWELF *)
@end group
@end example

@node Twelf Server, Emacs Interface, ML Interface, Top
@chapter Twelf Server

@cindex server
@cindex Twelf server

The Twelf server is a stand-alone command interpreter which provides the
functionality of the @code{Twelf} structure in ML (@pxref{ML
Interface}), but allows no ML definitions.  It is significantly smaller
than Standard ML and is the recommended way to interact with Twelf
except for developers.  Its behavior regarding configurations is
slightly different in that the server maintains a current configuration,
rather than allowing the binding of names to configurations.
Configuration are defined with the @code{Config.read} command which
takes a configuration filename as argument.

In Emacs, the Twelf server typically runs in a process buffer
called @code{*twelf-server*}.  The user can select this buffer
and directly type commands to the Twelf server.  This style
of interaction is inherited from the comint package for Emacs,
but typically one works through advanced commands in Twelf
mode (@pxref{Twelf Mode}).

The Twelf server prompts with @code{%% OK %%} or @code{%% ABORT %%}
depending on the success of failure of the previous operation.  It
accepts commands and their arguments on one line, except that additional
Twelf declarations which may be required are read separately, following
the command line.  Reading declarations can be forcibly terminated
with the end-of-file token @samp{%.}.

@menu
* Server Types::                Server command argument types
* Server Commands::             List of Twelf server commands
@end menu

@node Server Types, Server Commands, Twelf Server, Twelf Server
@section Server Types

@cindex server types
@cindex types, server

The server commands employ arguments of the following types.

@table @code
@item file
@findex file
 The name of a file, relative to the current working directory

@item id
@findex id
 A Twelf identifier

@item reconTraceMode
@findex reconTraceMode
 Either @code{Progressive} or @code{Omniscient} (@pxref{Tracing Reconstruction})

@item strategy
@findex strategy
 Either @code{FRS} or @code{RFS} (@pxref{Search Strategies})

@item tableStrategy
@findex tableStrategy
 Either @code{Variant} or @code{Subsumption} (@pxref{Tabled Logic Programming})

@item bool
@findex bool
 Either @code{true} or @code{false}

@item nat
@findex nat
 A natural number (starting at @code{0})

@item limit
@findex limit
 Either @code{*} (to indicate no limit) or a natural number
@end table

@node Server Commands,  , Server Types, Twelf Server
@section Server Commands

@cindex server commands
@cindex commands, server

The Twelf server recognized the following commands.

@table @code
@item set @var{parameter} @var{value}
@findex set
 Set @var{parameter} to @var{value}, where @var{parameter} is
one of the following (explained in @ref{Environment Parameters}).

@table @code
@item chatter @var{nat}
@c @findex chatter
@item doubleCheck @var{bool}
@c @findex doubleCheck
@item unsafe @var{bool}
@c @findex Twelf.unsafe
@item Print.implicit @var{bool}
@c @findex Print.implicit
@item Print.depth @var{limit}
@c @findex Print.depth
@item Print.length @var{limit}
@c @findex Print.length
@item Print.indent @var{nat}
@c @findex Print.indent
@item Print.width @var{nat}
@c @findex Print.width
@item Trace.detail @var{nat}
@c @findex Trace.detail
@item Compile.optimize @var{bool}
@c @findex Compile.optimize
@item Recon.trace @var{bool}
@c @findex Recon.trace
@item Recon.traceMode @var{reconTraceMode}
@c @findex Recon.traceMode
@item Prover.strategy @var{strategy}
@c @findex Prover.strategy
@item Prover.maxSplit @var{nat}
@c @findex Prover.maxSplit
@item Prover.maxRecurse @var{nat}
@c @findex Prover.maxRecurse
@item Table.strategy @var{tableStrategy}
@end table

@item get @var{parameter}
@findex get
 Print the current value of @var{parameter} (see table above).

@item Trace.trace @var{id1} ... @var{idn}
@findex Trace.trace
 Trace given constants.
@item Trace.traceAll
@findex Trace.traceAll
 Trace all constants.
@item Trace.untrace
@findex Trace.untrace
 Untrace all constants.

@item Trace.break @var{id1} ... @var{idn}
@findex Trace.break
 Set breakpoint for given constants.
@item Trace.breakAll
@findex Trace.breakAll
 Break on all constants.
@item Trace.unbreak
@findex Trace.unbreak
 Remove all breakpoints.

@item Trace.show
@findex Trace.show
 Show current trace and breakpoints.
@item Trace.reset
@findex Trace.reset
 Reset all tracing and breaking.

@item Print.sgn
@findex Print.sgn
 Print current signature.
@item Print.prog
@findex Print.prog
 Print current signature as program.
@item Print.subord
@findex Print.subord
 Print current subordination relation.
@item Print.domains
@findex Print.domains
 Print registered constraint domains.
@item Print.TeX.sgn
@findex Print.sgn
 Print current signature in TeX format.
@item Print.TeX.prog
@findex Print.prog
 Print current signature in TeX format as program.

@item Timers.show
@findex Timers.show
 Print and reset timers.
@item Timers.reset
@findex Timers.reset
 Reset timers.
@item Timers.check
@findex Timers.check
 Print, but do not reset timers.

@item OS.chDir @var{file}
@findex OS.chDir
 Change working directory to @var{file}.
@item OS.getDir
@findex OS.getDir
 Print current working directory.
@item OS.exit
@findex OS.exit
 Exit Twelf server.
@item quit
@findex quit
 Quit Twelf server (same as exit).

@item Config.read @var{file}
@findex Config.read
 Read current configuration from @var{file}.
@item Config.load
@findex Config.load
 Load current configuration.
@item Config.append
@findex Config.append
 Load current configuration without prior reset.

@item make @var{file}
@findex make
 Read and load current configuration from @var{file}.

@item reset
@findex reset
 Reset global signature.
@item loadFile @var{file} 
@findex loadFile
 Load Twelf file @var{file}.
@item decl @var{id}
@findex decl
 Show constant declaration for @var{id}.

@item top
@findex top
 Enter interactive query loop (@pxref{Interactive Queries}).
@item Table.top
@findex Table.top
 Enter interactive loop for tables queries (@pxref{Tabled Logic Programming}).

@item version
@findex version
 Show server version.

@item help
@findex help
 Show available server commands, parameters, and server types.
@end table

@node Emacs Interface, Installation, Twelf Server, Top
@chapter Emacs Interface

The Twelf mode for Emacs provides some functions and utilities for
editing Twelf source and for interacting with an inferior Twelf server
process which can load configurations, files, and individual
declarations and track the source location of errors.  It also provides
an interface to the tags package which allows simple editing of groups
of files, constant name completion, and locating of constant
declarations within the files of a configuration.

Note that in order to use the Emacs interface you need to include the
line

@example
(load "@var{directory}/emacs/twelf-init.el")
@end example

in your @file{.emacs} file, where @var{directory} is the Twelf root
directory.

@menu
* Twelf Mode::                  Major mode for editing Twelf sources
* Editing Commands::            Automatic indentation
* Type Checking Commands::      Checking declarations, files, configurations
* Printing Command::            Printing signatures
* Tracing Commands::            Debugging tools
* Error Tracking::              Jumping to error locations
* Server State::                Changing server parameters
* Info File::                   Reading this documentation
* Tags Files::                  Tagging Twelf sources
* Twelf Timers::                Obtaining runtime statistics from server
* Twelf-SML Mode::              Running Twelf under SML in Emacs
* Emacs Variables::             Customizing Twelf mode
* Syntax Highlighting::         Using multiple fonts for Twelf code
* Emacs Initialization::        For the .emacs file
* Command Summary::             Summary of Twelf mode commands
@end menu

@node Twelf Mode, Editing Commands, Emacs Interface, Emacs Interface
@section Twelf Mode

@cindex Twelf mode in Emacs
@cindex declaration, current
@cindex current declaration

The Twelf mode in Emacs provides support for editing and indentation,
syntax highlighting (including colors) (@pxref{Syntax Highlighting}),
and communication commands for interacting with a Twelf server running
as an inferior process to Emacs.  It defines a menu which is added to
the menu bar, usually at the top of each Emacs frame.

Many commands apply to the current declaration, which is the declaration
in which we find the Emacs cursor (not the cursor of the window system).
If the cursor is between declarations, the declaration after point is
considered current.  From the point of view of Emacs, single
declarations never include consecutive blank lines, which provides some
insulation against missing closing delimiters.

Normally, Twelf mode is entered automatically when a Twelf source file
is edited (@pxref{Emacs Initialization}), but it can also be switched on or
off directly with @kbd{M-x twelf-mode}.

@table @kbd
@item M-x twelf-mode
@findex M-x twelf-mode
 Toggle Twelf mode, the major mode for editing Twelf code.
@end table

@node Editing Commands, Type Checking Commands, Twelf Mode, Emacs Interface
@section Editing Commands

The editing commands in Twelf mode partially analyse the structure
of the text at the cursor position as Twelf code and try to indent
accordingly.  This is not always perfect.

@cindex editing
@cindex indentation

@table @kbd
@item @key{TAB}
@itemx M-x twelf-indent-line
@findex M-x twelf-indent-line
  Indent current line as Twelf code.
This recognizes comments, matching delimiters, and standard infix operators.

@item @key{DEL}
@itemx M-x backward-delete-char-untabify
@findex M-x backward-delete-char-untabify
 Delete character backward, changing tabs into spaces.

@item M-C-q
@itemx M-x twelf-indent-decl
@findex M-x twelf-indent-decl
 Indent each line of the current declaration.

@item M-x twelf-indent-region
@findex M-x twelf-indent-region
 Indent each line of the region as Twelf code.
@end table

@node Type Checking Commands, Printing Command, Editing Commands, Emacs Interface
@section Type Checking Commands 

@cindex type checking, from Emacs
@cindex server buffer
@cindex display, of server buffer

The Twelf mode provides simple commands which cause the server to load
or reload the current configuration, the file edited in the current
buffer, or just the declaration at point.  Each of these command can be
preceded by a prefix argument (for example, @kbd{C-u C-c C-c}) which
will select the Twelf server buffer after completion of the command.
The Twelf server buffer can also be forced to be shown with the @kbd{C-c
C-u} Emacs command.

@table @kbd
@item C-c C-c
@itemx M-x twelf-save-check-config
@findex M-x twelf-save-check-config
 Save its modified buffers and then check the current Twelf configuration.
 With prefix argument also displays Twelf server buffer.
 If necessary, this will start up an Twelf server process.

@item C-c C-a
@itemx M-x twelf-save-append-config
@findex M-x twelf-save-append-config
 Save its modified buffers and then check the current Twelf configuration
 without resetting or reloading files unmodified since the last check.
 With prefix argument also displays Twelf server buffer.
 If necessary, this will start up an Twelf server process.

@item C-c C-s
@itemx M-x twelf-save-check-file
@findex M-x twelf-save-check-file
 Save buffer and then check it by giving a command to the Twelf server.
 In Twelf Config minor mode, it reconfigures the server.
 With prefix argument also displays Twelf server buffer.

@item C-c C-d
@itemx M-x twelf-check-declaration
@findex M-x twelf-check-declaration
 Send the current declaration to the Twelf server process for checking.
 With prefix argument also displays Twelf server buffer.

@item C-c c
@itemx M-x twelf-type-const
@findex M-x twelf-type-const
 Display the type of the constant before point.
 Note that the type of the constant will be `absolute' rather than the
 type of the particular instance of the constant.

@item C-c C-u
@itemx M-x twelf-server-display
@findex M-x twelf-server-display 
 Display Twelf server buffer, moving to the end of output.
 With prefix argument also selects the Twelf server buffer.
@end table

@node Printing Command, Tracing Commands, Type Checking Commands, Emacs Interface
@section Printing Commands

@cindex printing, from Emacs

@table @kbd
@item M-x twelf-print-signature
@findex M-x twelf-print-signature
 Prints the current signature in the Twelf server buffer.

@item M-x twelf-print-program
@findex M-x twelf-print-program
 Prints the current signature as a program in the Twelf server buffer.

@item M-x twelf-print-subord
@findex M-x twelf-print-subord
 Prints the current subordination relation in the Twelf server buffer.

@item M-x twelf-print-tex-signature
@findex M-x twelf-print-tex-signature
 Prints the current signature in TeX style.
 The output appears in the  Twelf server buffer.

@item M-x twelf-print-tex-program
@findex M-x twelf-print-tex-program
 Prints the current signature as a program in TeX style.
 The output appears in the Twelf server buffer.
@end table

@node Tracing Commands, Error Tracking, Printing Command, Emacs Interface
@section Tracing Commands

@cindex tracing, from Emacs
@cindex breakpoints, from Emacs

The Twelf Emacs mode provides a simple interface to the tracer.
While tracing or breakpoints are on, you should be in the
Emacs server buffer to type your input directly to the server
as described in @ref{Tracing and Breakpoints}.

@table @kbd
@item M-x twelf-trace-trace
@findex M-x twelf-trace-trace
 Read list of constants and trace them.

@item M-x twelf-trace-trace-all
@findex M-x twelf-trace-trace-all
Trace all clauses and families.

@item M-x twelf-trace-untrace
@findex M-x twelf-trace-untrace
Untrace all clauses and families.

@item M-x twelf-trace-break
@findex M-x twelf-trace-break
Read list of constants and set breakpoints.

@item M-x twelf-trace-break-all
@findex M-x twelf-trace-break-all
Set breakpoints on all clauses and families.

@item M-x twelf-trace-unbreak
@findex M-x twelf-trace-unbreak
Remove all breakpoints.

@item M-x twelf-trace-show
@findex M-x twelf-trace-show
Show tracing and breakpoint information.
@end table

@node Error Tracking, Server State, Tracing Commands, Emacs Interface
@section Error Tracking

@cindex error tracking
@cindex tracking errors

Error messages by the Twelf server are flagged with the filename and an
educated guess as to the source of the error (@pxref{Error Messages}).
These can be interpreted by Emacs to jump directly to the suspected
site.

Sometimes, the server buffer and the the server itself believe to have
different working directories.  In that case, error tracking may not be
able to find the file, and an explicit call to @code{OS.chDir}
or @code{M-x cd} in the server buffer may be required.

@table @kbd
@item C-c `
@itemx M-x twelf-next-error
@findex M-x twelf-next-error
 Find the next error by parsing the Twelf server or Twelf-SML buffer.
 Move the error message on the top line of the window;
 put the cursor at the beginning of the error source. If the
 error message specifies a range, the mark is placed at the end.

@item C-c =
@itemx M-x twelf-goto-error
@findex M-x twelf-goto-error
 Go to the error reported on the current line or below.
 Also updates the error cursor to the current line.
@end table

@node Server State, Info File, Error Tracking, Emacs Interface
@section Server State

@cindex server state
@cindex setting server parameters
@cindex server parameters, setting
@cindex interrupt

The server state consists of the current configuration and a number of
parameters described in @ref{Twelf Server}.  The current configuration
is often set implicitly, with the @kbd{C-c C-c} command in a
configuration buffer, but it can also be set explicitly.

@table @kbd
@item C-c <
@itemx M-x twelf-set
@findex M-x twelf-set
 Sets the Twelf parameter PARM to VALUE.
 When called interactively, prompts for parameter and value, supporting
 completion.

@item C-c >
@itemx M-x twelf-get
@findex M-x twelf-get
 Prints the value of the Twelf parameter PARM.
 When called interactively, prompts for parameter, supporting completion.

@item C-c C-i
@itemx M-x twelf-server-interrupt
@findex M-x twelf-server-interrupt
 Interrupt the Twelf server process.

@item M-x twelf-server
@findex M-x twelf-server
 Start an Twelf server process in a buffer named *twelf-server*.
 Any previously existing process is deleted after confirmation.
 Optional argument PROGRAM defaults to the value of the variable
 twelf-server-program.
 This locally re-binds `twelf-server-timeout' to 15 secs.

@item M-x twelf-server-configure
@findex M-x twelf-server-configure
 Initializes the Twelf server configuration from CONFIG-FILE.
 A configuration file is a list of relative file names in
 dependency order.  Lines starting with % are treated as comments.
 Starts a Twelf servers if necessary.

@item M-x twelf-reset
@findex M-x twelf-reset
 Reset the global signature of Twelf maintained by the server.

@item M-x twelf-server-quit
@findex M-x twelf-server-quit
 Kill the Twelf server process.

@item M-x twelf-server-restart
@findex M-x twelf-server-restart
 Restarts server and re-initializes configuration.
 This is primarily useful during debugging of the Twelf server code or
 if the Twelf server is hopelessly wedged.

@item M-x twelf-server-send-command
@findex M-x twelf-server-send-command
 Restarts server and re-initializes configuration.
 This is primarily useful during debugging of the Twelf server code or
 if the Twelf server is hopelessly wedged.
@end table

@node Info File, Tags Files, Server State, Emacs Interface
@section Info File

The content of this file in Info format can be visited directly
and does not need to be tied into the Info tree.
See the documentation for the Emacs info package for
more info

@cindex info file
@cindex documentation

@table @kbd
@item C-c C-h
@itemx M-x twelf-info
@findex M-x twelf-info
 Visit the Twelf User's Guide in info format in Emacs.
 With a prefix argument it prompts for the info file name, which
 defaults to the value of the @code{twelf-info-file} variable.
@end table

@node Tags Files, Twelf Timers, Info File, Emacs Interface
@section Tags Files

Tags files provide a convenient way to group files, such as
Twelf configurations.  See the documentation for the Emacs etags
package for more information.

@cindex tags file
@cindex tagging configurations

@table @kbd
@item M-x twelf-tag
@findex M-x twelf-tag
 Create tags file for current configuration.
 If the current configuration is sources.cfg, the tags file is TAGS.
 If current configuration is named FILE.cfg, tags file will be named FILE.tag
 Errors are displayed in the Twelf server buffer.

@item M-.
@itemx M-x find-tag TAG
@findex M-x find-tag
 Selects the buffer that the tag is contained in and puts point at
 its definition.

@item C-x 4 .
@itemx M-x find-tag-other-window TAG
@findex M-x find-tag-other-window
 Selects the buffer that TAG is contained in in another window
and puts point at its definition.

@item C-c q
@itemx M-x tags-query-replace FROM TO
@findex M-x tags-query-replace 
 Query-replace-regexp FROM with TO through all files listed in tags table.

@item C-c s
@itemx M-x tags-search REGEXP
@findex M-x tags-search
 Search through all files listed in tags table for match for REGEXP.

@item M-,
@itemx M-x tags-loop-continue
@findex M-x tags-loop-continue
 Continue last C-c s or C-c q command.
@end table

@node Twelf Timers, Twelf-SML Mode, Tags Files, Emacs Interface
@section Twelf Timers

The following commands obtain the runtime statistics of the
the Twelf server.

@cindex server timers

@table @kbd
@item M-x twelf-timers-reset
@findex M-x twelf-timers-reset
 Reset the Twelf timers.

@item M-x twelf-timers-show 
@findex M-x twelf-timers-show
 Show and reset the Twelf timers.

@item M-x twelf-timers-check
@findex M-x twelf-timers-check
 Show the Twelf timers without resetting them.

@end table

@node Twelf-SML Mode, Emacs Variables, Twelf Timers, Emacs Interface
@section Twelf-SML Mode

@cindex Twelf-SML mode

There is some support for interacting with Twelf, even when it is
run within ML, rather than as a stand-alone server.  You can start
an SML in which you intend to run Twelf with @code{M-x twelf-sml};
the buffer will then be in Twelf-SML mode.

If you intend to send command to a buffer running Twelf in SML (rather
than the Twelf server), you can switch to a minor mode 2Twelf-SML with
@code{M-x twelf-to-twelf-sml}.

@table @kbd
@item M-x twelf-sml
@findex M-x twelf-sml
 Run an inferior Twelf-SML process in a buffer *twelf-sml*.
 If there is a process already running in *twelf-sml*, just
 switch to that buffer.  With argument, allows you to change the program
 which defaults to the value of twelf-sml-program.  Runs the hooks from
 twelf-sml-mode-hook (after the comint-mode-hook is run).

@item M-x twelf-to-twelf-sml-mode
@findex M-x twelf-to-twelf-sml-mode
 Toggles minor mode for sending queries to Twelf-SML instead of Twelf server.

@item C-c C-e
@itemx M-x twelf-sml-send-query
@findex M-x twelf-sml-send-query
 Send the current declaration to the inferior Twelf-SML process as a query.
 Prefix argument means switch-to-twelf-sml afterwards.

@item C-c C-r
@itemx M-x twelf-sml-send-region 
@findex M-x twelf-sml-send-region
 Send the current region to the inferior Twelf-SML process.
 Prefix argument means switch-to-twelf-sml afterwards.

@item C-c @key{RETURN}
@itemx M-x twelf-sml-send-newline
@findex M-x twelf-sml-send-newline
 Send a newline to the inferior Twelf-SML process.
 If a prefix argument is given, switches to Twelf-SML buffer afterwards.

@item C-c ;
@itemx M-x twelf-sml-send-semicolon
@findex M-x twelf-sml-send-semicolon
 Send a semi-colon to the inferior Twelf-SML process.
 If a prefix argument is given, switched to Twelf-SML buffer afterwards.

@item C-c d
@itemx M-x twelf-sml-cd DIR
@findex M-x twelf-sml-cd
 Make DIR become the Twelf-SML process' buffer's default directory and
 furthermore issue an appropriate command to the inferior Twelf-SML process.

@item M-x twelf-sml-quit
@findex M-x twelf-sml-quit
 Kill the Twelf-SML process.
@end table

@node Emacs Variables, Syntax Highlighting, Twelf-SML Mode, Emacs Interface
@section Emacs Variables

@cindex Emacs variables
@cindex variables, Emacs

A number of Emacs variables can be changed to customize the behavior of
Twelf mode.  The list below is not complete; please refer to the Emacs
Lisp sources in @code{emacs/twelf.el} for additional information.

@table @code
@item twelf-indent 
@findex twelf-indent
 Indent for Twelf expressions.

@item twelf-server-program
@findex twelf-server-program
 Default Twelf server program.

@item twelf-info-file
@findex twelf-info-file
 Default Twelf info file.

@item twelf-mode-hook
@findex twelf-mode-hook
 List of hook functions to run when switching to Twelf mode.

@item twelf-server-mode-hook
@findex twelf-server-mode-hook
 List of hook functions to run when switching to Twelf Server mode.

@item twelf-sml-program
@findex twelf-sml-program
 Default Twelf-SML program.

@item twelf-sml-mode-hook
@findex twelf-sml-mode-hook
 List of hook functions for Twelf-SML mode.
@end table

@node Syntax Highlighting, Emacs Initialization, Emacs Variables, Emacs Interface
@section Syntax Highlighting

@cindex syntax highlighting
@cindex colors
@cindex faces

Twelf also provides syntax highlighting, which helps make Elf code more
readable.  This highlighting can use different colors and faces.
Unfortunately, the necessary libraries are at present not standardized
between XEmacs and FSF Emacs, which means that highlighting support is
less general and less portable than the plain Twelf mode.

At present, highlighting has not been extensively tested in various
versions of Emacs, but the font-lock mode provided in
@file{emacs/twelf-font.el} seems to work at least in XEmacs version
19.16 and FSF Emacs version 19.34.  The alternative highlight mode
provided in @file{emacs/twelf-hilit} appears to work in FSF Emacs 19.34.

Unlike other font-lock modes, Twelf's fontification is not `electric' in
that it does not fontify as one types.  One has to explicitly issue a
command to fontify the current Twelf declaration or current buffer,
since single-line highlighting is too error-prone and multi-line
immediate highlighting is not well supported in current versions of font
lock mode.

@table @kbd
@item C-c C-l
@itemx M-x twelf-font-fontify-decl
@findex M-x twelf-font-fontify-decl
 Fontifies the current Twelf declaration.

@item C-c l
@itemx M-x twelf-font-fontify-buffer
@findex M-x twelf-font-fontify-buffer
 Fontitifies the current buffer as Twelf code

@item M-x twelf-font-unfontify
@findex M-x twelf-font-unfontify
 Removes fontification from current buffer.
@end table

@node Emacs Initialization, Command Summary, Syntax Highlighting, Emacs Interface
@section Emacs Initialization

@cindex initializing Twelf mode
@findex load-path
@findex autoload
@findex auto-mode-alist
@findex add-hook

If Twelf has been properly installed, you can use the Twelf's Emacs
interface with the default settings simply by adding the line

@example
(load "@var{directory}/emacs/twelf-init.el")
@end example

to your @file{.emacs} file, where @var{directory} is the Twelf root
directory.  In order to customize the behavior, you might copy
the file @file{emacs/twelf-init.el} or its contents and change
it as appropriate.

@node Command Summary,  , Emacs Initialization, Emacs Interface
@section Command Summary

@cindex commands, Emacs

@example
@group
--- Editing Commands ---
TAB          twelf-indent-line
DEL          backward-delete-char-untabify
M-C-q        twelf-indent-decl
@end group

@group
--- Type Checking ---
C-c C-c      twelf-save-check-config
C-c C-a      twelf-save-append-config
C-c C-s      twelf-save-check-file
C-c C-d      twelf-check-declaration
C-c c        twelf-type-const
C-c C-u      twelf-server-display
@end group

@group
--- Error Tracking ---
C-c `        twelf-next-error
C-c =        twelf-goto-error
@end group

@group
--- Syntax Highlighting ---
C-c C-l      twelf-font-fontify-decl
C-c l        twelf-font-fontify-buffer
@end group

@group
--- Server State ---
C-c <        twelf-set
C-c >        twelf-get
C-c C-i      twelf-server-interrupt
M-x twelf-server
M-x twelf-server-configure
M-x twelf-server-quit
M-x twelf-server-restart
M-x twelf-server-send-command
@end group

@group
--- Info ---
C-c C-h      twelf-info
@end group

@group
--- Timers ---
M-x twelf-timers-reset
M-x twelf-timers-show
M-x twelf-timers-check
@end group

@group
--- Tags (standard Emacs etags package) ---
M-x twelf-tag
M-.          find-tag (standard binding)
C-x 4 .      find-tag-other-window (standard binding)
C-c q        tags-query-replace (Twelf mode binding)
C-c s        tags-search (Twelf mode binding)
M-,          tags-loop-continue (standard binding)
             visit-tags-table, list-tags, tags-apropos
@end group

@group
--- Communication with inferior Twelf-SML process (not Twelf Server) ---
M-x twelf-sml
C-c C-e      twelf-sml-send-query
C-c C-r      twelf-sml-send-region
C-c RET      twelf-sml-send-newline
C-c ;        twelf-sml-send-semicolon
C-c d        twelf-sml-cd
M-x twelf-sml-quit
@end group

@group
--- Variables ---
twelf-indent
@end group
@end example

@node Installation, Examples, Emacs Interface, Top
@chapter Installation

@cindex installation
@cindex Standard ML of New Jersey
@cindex Poly/ML
@cindex MLton
@cindex ML implementations

At present, Twelf has been tested in SML of New Jersey (version 110 or
higher), Poly/ML and MLton, all of which implement Standard ML
(revised 1997) and the Standard ML Basis Library.  The instructions
below apply to a Unix system.  For instructions for other architectures
or updates please check the file @file{INSTALL} at the Twelf home page
and in the Twelf root directory after unpacking the distribution.

On a Unix system you unpack the sources with

@example
@group
gunzip twelf-1-4.tar.gz
tar -xf twelf-1-4.tar
cd twelf
make
@end group
@end example

This builds the Twelf server (@pxref{Twelf Server}) for your current
architecture and makes it accessible as @file{bin/twelf-server}.  The
@code{make} command is different for SML/NJ versions 110.20 or higher,
for PolyML, and for MLton; see the list below.  The @code{make} also
installs the Twelf Emacs interface (@pxref{Emacs Interface}), but you
must add a line

@example
(load "@var{directory}/emacs/twelf-init.el")
@end example

to your @file{.emacs} file, where @var{directory} is the root directory
into which you installed Twelf.  Note that the Twelf installation cannot
be moved after it has been compiled with @code{make}, since absolute
pathnames are built into the executable scripts.

If you would like to use Twelf as a structure in SML, you can then call

@example
@group
make twelf-sml
@end group
@end example

which creates @file{bin/twelf-sml} for the Twelf-SML mode
(@pxref{Twelf-SML Mode}).  Calling @code{make clean} will remove
temporary files created by the SML compiler, but not the
executable file.

@table @asis
@item SML of New Jersey
 See @t{http://www.smlnj.org/}

@ifhtml
<UL>
 <LI> <A HREF="http://www.smlnj.org/">SML of New Jersey Home Page</A> </LI>
</UL>
@end ifhtml

Because of minor incompatibilites between the officially released
version 110.0.3 and newer versions (110.20 or higher) you have to
compile Twelf for newer version of SML/NJ with with

@example
make -f smlnj/Makefile
@end example

@item Poly/ML
 See @t{http://www.polyml.org/}

@ifhtml
<UL>
 <LI> <A HREF="http://www.polyml.org/">Poly/ML Home Page</A> </LI>
</UL>
@end ifhtml

For Poly/ML you have to compile Twelf with

@example
make -f polyml/Makefile
@end example

@item MLton
 See @t{http://www.mlton.org/}

@ifhtml
<UL>
 <LI> <A HREF="http://www.mlton.org/">MLton Home Page</A> </LI>
</UL>
@end ifhtml

For MLton, you have to compile Twelf with

@example
make -f mlton/Makefile
@end example

@end table

@node Examples, History, Installation, Top
@chapter Examples

We give here only a brief reference to the examples in the
@file{examples/} subdirectory of the distribution.  Each example comes
in a separate subdirectory whose name is listed below.

@table @file
@item arith
@cindex arithmetic
  Associativity and commutative of unary addition.
@item ccc
@cindex Cartesian-closed categories
  Cartesian-closed categories (currently incomplete).
@item church-rosser
@cindex Church-Rosser theorem
@cindex lambda-calculus, untyped
  The Church-Rosser theorem for untyped lambda-calculus.
@item compile
@cindex Mini-ML, compilation
  Various compilers starting from Mini-ML.
@item cut-elim
@cindex cut elimination
  Cut elimination for intuitionistic and classical logic.
@item fol
@cindex first-order logic
  Simple theorems in first-order logic.
@item guide
@cindex examples, from user's guide
  Examples from Users' Guide.
@item incll
@cindex ordered logic
  Logic programming in ordered logic.
@item kolm
@cindex Kolmogorov translation
  Double-negation interpretation of classical in intuitionistic logic.
@item lp
@cindex logic programming, theory
  Logic programming, uniform derivations.
@item lp-horn
@cindex Horn logic, theory
  Horn fragment of logic programming.
@item mini-ml
@cindex Mini-ML, theory
  Mini-ML, type preservation and related theorems.
@item polylam
@cindex lambda-calculus, polymorphic
  Polymorphic lambda-calculus.
@item prop-calc
@cindex Hilbert calculus
  Natural deduction and Hilbert propositional calculus
@item units
@cindex Mini-ML, with units
  Mini-ML extended with units (currently incomplete).
@end table

In each directory or subdirectory you can find a file @file{sources.cfg}
which defines the standard configuration, usually just the basic theory.
The @file{test.cfg} which also defines an extended configuration with
some test queries and theorems.  Most examples also have a @file{README}
file with a brief explanation and pointer to the literature.

@node History, Index, Examples, Top
@chapter History

While the underlying type theory has not changed, the Twelf
implementation differs from older Elf implementation in a few ways.
Mostly, these are simplifications and improvements.  The main feature
which has not yet been ported is the Elf server interface to Emacs.
Also, while the type checker is more efficient now, the operational
semantics does not yet incorporate some of the optimizations of the
older Elf implementations and is therefore slower.  The principal
differences of Twelf 1.2 and the obsolete Elf 1.5 are given
below, followed by the new features of Twelf 1.3.  New features
in Twelf 1.4 are given in @ref{New Features}.

@table @asis
@item Syntax (@pxref{Syntax})
  The quote @samp{'} character is no longer a special character in the
lexer, and @samp{=} (equality) is now a reserved identifier.  The syntax
of @code{%name} declarations has changed by allowing only one preferred
name to be specified.  Also, @code{%name}, @code{%infix}, @code{%prefix}
and @code{%postfix} declarations must be terminated by a period @samp{.}
which previously was optional.  Further, single lines comments now must
start with @samp{%@var{whitespace}} or @samp{%%} in order to avoid
misspelled keywords of the form @samp{%@var{keyword}} to be ignored.

@item Type theory
  Elf 1.5 had two experimental features which are not available in
Twelf: polymorphism and the classification of @math{type} as a type.

@item Definitions (@pxref{Definitions})
  Twelf offers definitions which were not available in Elf.

@item Searching for definitions (@pxref{Solve Declaration})
  Elf had a special top-level query form @code{sigma [x:A] B} which
searched for a solution @code{M : A} and then solved the result of
substituting @code{M} for @code{x} in @code{B}.  In Twelf this
mechanism has been replaced by a declaration @code{%solve c : A} which
searches for a solution @code{M : A} and then defines @code{c = M : A},
where the remaining free variables are implicitly universally
quantified.

@item Query declarations (@pxref{Query Declaration})
  Twelf allows queries in ordinary Elf files as @samp{%query}
declarations.  Queries are specified with an expected number of
solutions, and the number of solutions to search for, which can be used
to test implementations.

@item Operational semantics (@pxref{Operational Semantics})
  Twelf eliminates the distinction between static and dynamic
signatures.  Instead, dependent function types @code{@{x:A@} B}
where @code{x} occurs in the normal form of @code{B} are treated
statically, while non-dependent function type @code{A -> B} or
@code{B <- A} or @code{@{x:A@} B} where @code{x} does not occur
in @code{B} are treated dynamically.

@item Modes (@pxref{Modes})
  Twelf offers a mode checker which was only partially supported in Elf.

@item Termination (@pxref{Termination})
  Twelf offers a termination checker which can verify that certain
programs represent decision procedures.

@item Theorem prover (@pxref{Theorem Prover})
  Although very limited at present, an experimental prover for theorems
and meta-theorems (that is, properties of signatures) is now available.
It does not yet support lemmas or meta-hypothetical reasoning, which
are currently under development.

@item Emacs interface (@pxref{Emacs Interface})
  The Elf mode has remained basically unchanged, but the Elf server
interface has not yet been ported.
@end table

The version 1.3 from September 13, 2000 incorporated
the following major changes from Twelf 1.2 from August 27, 1998.

@table @asis
@item Constraints (@pxref{Constraint Domains}).
 Type reconstruction and the logic programming engine (but not yet
the theorem prover) allow various constraint domains in the style
of constraint logic programming languages.  The main ones are
equalities and inequalities over rationals and integers.

@item Tracing and Breakpoints (@pxref{Tracing and Breakpoints})
 The logic programming engine now support tracing and setting
of breakpoints for illustration and debugging purposes.

@item Theorem Prover (@pxref{Theorem Prover})
 The theorem prover now allows quantification over regular context.  The
theorem prover will also use previously proved theorems with
@code{%prove}) and ignore those with @code{%establish}, which is
otherwise equivalent.  In unsafe mode, @code{%assert} can be used to
claim theorems.  However, at present no longer generates proof terms.

@item Reduction Checking (@pxref{Reduction Declaration})
 The termination checker has been extended to verify if output
arguments to a predicate are smaller than some inputs with
the @code{%reduces} declaration.

@item Signature Printing (@pxref{Signature Printing})
 Signatures can now be printed, also in TeX format.

@item Abbreviations (@pxref{Definitions})
 Added abbreviations (@code{%abbrev}) which, unlike definition, do not
need to be strict.

@item Name Preferences (@pxref{Name Preferences})
 Name preference declarations (@code{%name}) now allow an optional
second argument for naming of parameters.
@end table

@node Index,  , History, Top
@unnumbered Index

@printindex cp

@contents
@bye
