
\documentclass{book}[12pt]
\usepackage{times}
\usepackage{comment}
\usepackage{url}
\usepackage{fullpage}
\usepackage{proof}
\usepackage{xspace}
\usepackage[pdftex,
	pdfauthor={Aaron Stump},
	pdftitle={Verified Programming in Guru},
	colorlinks,
	linkcolor={red}]{hyperref}


\special{papersize=8.5in,11in}
\setlength{\pdfpageheight}{\paperheight}
\setlength{\pdfpagewidth}{\paperwidth}

\newcommand{\guru}[0]{\textsc{Guru}\xspace}
\newcommand{\carraway}[0]{\textsc{Carraway}\xspace}

\newtheorem{hint}{Theorem Proving Hint}

\begin{document}

\title{Verified Programming in \guru}

\author{Aaron Stump \\
Computer Science \\
The University of Iowa \\
Iowa City, Iowa, USA
}

\maketitle

\tableofcontents

\chapter{Introduction}
\label{ch1}

\section{Verified Programming}

Software errors are estimated to cost the U.S. economy \$60 billion a
year, and they contribute to computer security vulnerabilities which
end up costing U.S. companies a similar amount~\cite{nist02,fbi05}.
Possibly buggy software cannot be used for safety critical systems
like biomedical implants, nuclear reactors, airplanes, and utilities
infrastructure, at least not without costly backup mechanisms to
handle the case of software failure.  These reasons alone are certainly
enough to motivate our efforts to eliminate the possibility of bugs 
from our software.

But there is another reason to seek to create software that is
absolutely guaranteed to be free from errors: the basic desire we have
as computer scientists to create excellent software.  How
dissatisfying it is to write code that we know we cannot truly trust!
Even if we test it heavily, it may still fail.  It has famously been
said that testing can establish the presence of bugs, but not their
absence: we might always have missed that one input scenario that
breaks the system.  For anyone who loves the construction of elaborate
virtual edifices and intricate logical structures, verification has to
be an addicting activity.

Indeed it is.  The approach we will follow in this book is to
construct, along with our software, proofs that the software is
correct.  These proofs are formal artifacts, just like programs.  The
compiler checks that they are completely logically sound -- no missing
cases or incorrect inferences, for example -- when it compiles our
code.  If the proofs check, then we can be much more confident that
our software is correct.  Of course, it is always possible there is a
bug in the compiler (or in the operating system or standard libraries
the compiler relies on), but assuming there is not, then we know our
code truly has the properties we have proved it has.  No matter what
inputs we throw at it, it will always behave as our theorems promise
us it will.

Constructing programs and proofs together is, quite possibly, the most
complex engineering activity known to humankind.  It can be quite
challenging, and at times frustrating, for example when proofs fail to
go through not because the code is buggy, but because the property one
wishes to prove must be carefully rephrased.  But building verified
software is extremely rewarding.  The mental effort required is very
stimulating, even if we will never again write a line of
machine-checked proof.  Furthermore, even if we verify only fairly
modest properties of a piece of code -- and any verification is
necessarily incomplete, since can never exhaust the things we might
potentially wish to prove about a piece of code -- it is my experience
that even lightly verified code tends to work much, much better right
from the start than unverified code.  

\section{Functional Programming}

Mainstream programming languages like \textsc{Java} and \textsc{C++},
while powerful and effective for many applications, pose problems for
program verification.  This is for several reasons.  First, these are
large languages, with many different features.  They also come with
large standard libraries, which have to be accounted for in order to
verify programs that use them.  Also, they are based on programming
paradigms for which practically effective formal reasoning principles
are still being worked out.  For example, reasoning about programs
even with such a familiar and seemingly simple feature as
\emph{mutable state} is not at all trivial.  Mutable state means that
the value stored in a variable can be changed later.  The reader
perhaps has never even dreamed there could be languages where this is
not the case (where once a variable is assigned a value, that value
cannot be changed).  We will study such a language in this chapter.
Object-orientation of programs creates additional difficulties for
formal reasoning.

Where object-oriented languages are designed around the idea of an
object, functional programming languages are designed around the idea
of a function.  Modern examples with significant user communities and
tool support include \textsc{Caml} (pronounced ``camel'',
http://caml.inria.fr/) and \textsc{Haskell} (http://www.haskell.org/).
\textsc{Haskell} is particularly interesting for our purposes, because
the language is \emph{pure}: there is no mutable state of any kind.
Indeed, \textsc{Haskell} programs have a remarkable property: any
expression in a program is guaranteed to evaluate in exactly the same
way every time it is evaluated.  This property fails magnificently in
mainstream languages, where expressions like
``\texttt{gettimeofday()}'' are, of course, intended to evaluate
differently each time they are called.  Reasoning about impure
programs requires reasoning about the state they depend on.  Reasoning
about pure programs does not, and is thus simpler.  Nevertheless, pure
languages like \textsc{Haskell} do have a way of providing functions
like ``\texttt{gettimeofday()}''.  We will consider ways to provide
such functionality in a pure language in a later chapter.

\section{What is \guru?}

\guru is a pure functional programming language, which is similar in
some ways to Caml and Haskell.  But \guru also contains a language
for writing formal proofs demonstrating the properties of programs.
So there are really two languages: the language of programs, and the
language of proofs.  When the compiler checks a program, it computes a
type for it, just as compilers for other languages like \textsc{Java}
do.  But in \guru, such types can be significantly richer than in
mainstream or even most research programming languages.  These types
are called \emph{dependent types}, and they can express non-trivial
semantic properties of data and functions.  Analogously, when the
compiler checks a proof, it computes a formula for it, namely the
formula the proof proves.  So we really have four kinds of expressions
in \guru: programs (which we also call \emph{terms}) and their types;
proofs and their formulas.

\guru is inspired largely by the \textsc{Coq} theorem prover, used
for formalized mathematics and theoretical computer science, as well
as program verification~\cite{coq,coqart}.  Like \textsc{Coq}, \guru has
syntax for both proofs and programs, and supports dependent types.
\guru does not have as complex forms of polymorphism and dependent
types as \textsc{Coq} does. But \guru supports some features that are
difficult or impossible for \textsc{Coq} to support, which are useful
for practical program verification.  In \textsc{Coq}, the compiler
must be able to confirm that all programs are \emph{uniformly
terminating}: they must terminate on all possible inputs.  We know
from basic recursion theory or theoretical computer science that this
means there are some programs which really do terminate on all inputs
that the compiler will not be able to confirm do so.  Furthermore,
some programs, like web servers or operating systems, are not intended
to terminate.  So that is a significant limitation.  Other features
\guru has that \textsc{Coq} lacks include support for functional
modeling of non-functional constructs like destructive updates of data
structures and arrays; and better support for proving properties of
dependently typed functions.

So \guru is a verified programming language.  In this book, we will
also refer to the open-source project consisting of a compiler for
\guru code, the standard library of \guru code, and other materials
as ``\guru'' (or ``the \guru project'').  Finally, the compiler for
\guru code, which includes a type- and proof-checker, as well as an
interpreter, is called \texttt{guru}.  We will work with version 1.0
of \guru.

\section{Installing \guru}

This book assumes you will be using \guru on a Linux computer, but it
does not assume much familiarity with Linux.  To install \guru, first
start a shell. Then run the folllowing \textsc{Subversion} command:

\begin{verbatim}
svn checkout http://guru-lang.googlecode.com/svn/branches/1.0 guru-lang
\end{verbatim}

\noindent This will create a subdirectory called \texttt{guru-lang} of
your home directory.  This directory contains the \textsc{Java} source
code for \guru version 1.0 itself (\texttt{guru-lang/guru}), the
standard library written in \guru (\texttt{guru-lang/lib}), this
book's source code (\texttt{guru-lang/doc}), and a number of tests
written in \guru (\texttt{guru-lang/tests}).  A few things in the
distribution currently depend on its being called \texttt{guru-lang},
and residing in your home directory.

Before you can use \guru, you must compile it.  To do this, in your
shell, you should change to the \texttt{guru-lang} directory.  Then
run the command \texttt{make} from the shell.  This will invoke the
\textsc{Java} compiler to compile the \textsc{Java} source files in
\texttt{guru-lang/guru}.  After this is complete, you can run
\texttt{guru-lang/bin/guru} from the shell to process \guru source
files.  This will be further explained in Section~\ref{ch2:natguru}
below.

\section{The Structure of This Book}

We begin with \emph{monomorphic} functional programming in \guru.
Monomorphic means that code operates only over data of specific known
types. We will see further how to write proofs demonstrating that such
functions satisfy properties we might be interested in verifying.
Next, we consider \emph{polymorphic}, or generic, programming, where
code may operate generically over data of any type, not known in
advance by the code.  We again see how to write proofs showing that
such functions have the properties we might be interested in.  The
next step is \emph{dependently typed} programming.  Here, the types of
data and functions themselves capture the properties we are interested
in verifying.  There is no separate proof to write for such
properties, rather the program contains proofs to help the type
checker check that the code really meets its specification.  We will
then see how to write additional proofs about dependently typed
programs. Finally, we see how non-functional constructs like updatable
arrays are handled in \guru via \emph{functional modeling}.

Since this book is being used for a class, it contains a few
references to matters of course organization.  Anyone reading it who
is not part of such a class can, of course, just ignore those
references.  Also, I will usually begin chapters with a
\textbf{preview}, which gives an advance peek at the chapter's
material; and end with a \textbf{summary}.  Feel free to skip
especially the previews, if you prefer not to see the material without
a full explanation: all the material is explained in detail in the
chapter.

\section{Acknowledgments}

The following people, listed alphabetically, have assisted me with
with either the theory or implementation of \guru or its standard
library: Morgan Deters, Henry Li, Todd Schiller, Timothy Simpson,
Daniel Tratos, and Edwin Westbrook.  This research has been partially
supported by the National Science Foundation under grant CCF-0448275.

\chapter{Monomorphic Functional Programming}

Like most other functional programming languages, the heart of the
\guru's programming language is very compact and simple: we can define
inductive datatypes, write (recursive) functions, decompose inductive
data using a simple pattern-matching construct, and apply (aka, call)
functions.  That is essentially it.  Recursion is such a powerful idea
that even with such a simple core, we can write arbitrarily rich and
complex programs.  We will consider first inductive datatypes, then
non-recursive functions, pattern matching, and finally recursive
functions.  When we turn to polymorphic and especially dependently
typed programming in later chapters, we will have to revisit all these
concepts (inductive types, recursive functions, pattern matching, and
function applications), which become richer in those richer
programming settings.  So the syntax in this chapter will be enriched
in later chapters.

\section{Preview}

For those who like an overview in advance, here briefly is the syntax
for the programming features we will explore in this chapter. (For
those who dislike reading things without a full explanation, just skip
this section and you will see it all in great detail in the rest of
the chapter.)

\begin{itemize}

\item Inductive datatypes are declared using a command like this
one, for declaring the unary natural numbers:

\begin{verbatim}
Inductive nat : type :=
  Z : nat
| S : Fun(x:nat).nat.
\end{verbatim}

\item Applications of functions to arguments are written like the
following, for calling the \texttt{plus} function (which is defined,
not built-in) on \texttt{x} and \texttt{y}:

\begin{verbatim}
(plus x y)
\end{verbatim}

\item Non-recursive functions like this one to double an input
\texttt{x} are written this way:

\begin{verbatim}
fun(x:nat). (plus x x)
\end{verbatim}

\item Pattern matching on inductive data is written as follows, where
we have one \texttt{match}-clause for when \texttt{x} is \texttt{Z},
and another for when it is \texttt{S x'} for some \texttt{x'}.  This
is returning boolean true (\texttt{tt}) if \texttt{x} is \texttt{Z},
and boolean false (\texttt{ff}) otherwise:

\begin{verbatim}
    match x with 
      Z => tt 
    | S x' => ff
    end
\end{verbatim}

\item Recursive functions like \texttt{plus} can be written with this
syntax:

\begin{verbatim}
  fun plus(n m : nat) : nat.
    match n with
      Z => m
    | S n' => (S (plus n' m))
    end
\end{verbatim}

\end{itemize}


\section{Inductive Datatypes}
\label{ch2:ind}

At the heart of functional programming languages like \textsc{Caml}
and \textsc{Haskell} -- but not functional languages like
\textsc{LISP} and its dialects (e.g., \textsc{Scheme}) -- are
user-declared inductive datatypes.  An inductive datatype consists of
data which are incrementally and uniquely built up using a finite set
of operations, called the \emph{constructors} of the datatype.
Incrementally built up means that bigger data are obtained by gradual
augmentation from smaller data.  Uniquely means that the same piece of
data cannot be built up in two different ways.  Let us consider a
basic example.

\subsection{Unary natural numbers}

The natural numbers are the numbers $0,1,2,\ldots$.  We typically
write numbers in decimal notation.  Unary notation is much simpler.
Essentially, a number like 5 is represented by making 5 marks, for
example like this:

\[ |\ |\ |\ |\ | \]

\noindent A few questions arise.  How do we represent zero?  By zero
marks?  It is then hard to tell if we have written zero or just not
written anything at all.  We will write \texttt{Z} for zero.  Also,
how does this fit the pattern of an inductive datatype?  That is, how
are bigger pieces of data (i.e., bigger numbers) obtained
incrementally and uniquely from smaller ones?  One answer is that a
number like five can be viewed as built up from its \emph{predecessor}
4 by the \emph{successor} operation, which we will write $S$.  The
successor operation just adds one to a natural number.  In this book,
we will write the \emph{application} of a function $f$ to an input
argument $x$ as $f\ x$ or $(f\ x)$.  This is in contrast to other
common mathematical notation, where we write $f(x)$ for function
application.  So the five-fold application of the successor operation
to zero, representing the number 5, is written this way:

\[ (S\ (S\ (S\ (S\ (S\ Z))))) \]

Every natural number is either $Z$ or can be built from $Z$ by
applying the successor operation a finite number of times.
Furthermore, every natural number is uniquely built that way.  This
would not be true if in addition to $Z$ and $S$, we included an
operation $P$ for predecessor.  In that case, there would be an
infinite number of ways to build every number.  For example, $Z$ could
be built using just $Z$, or also in these ways (and others):

\[ 
\begin{array}{l}
(S\ (P\ Z)) \\
(S\ (S\ (P\ (P\ Z)))) \\
(S\ (S\ (S\ (P\ (P\ (P\ Z)))))) \\
\ldots
\end{array}
\]

\noindent The operations $Z$ and $S$ are the \emph{constructors} of
the natural number datatype.

The simplicity of unary natural numbers comes at a price.  The
representation of a number in unary is exponentially larger than its
representation in decimal notation.  For example, it takes very many
slash marks or applications of $S$ to write $100$ (decimal notation)
in unary.  In contrast, it only takes 3 digits in decimal.  On the
other hand, it is much easier to reason about unary natural numbers
than binary or decimal numbers, and also easier to write basic
programs like addition.  So we begin with unary natural numbers.

\subsection{Unary natural numbers in \guru}
\label{ch2:natguru}

\guru's standard library includes a definition of unary natural
numbers, and definitions of standard arithmetic functions operating on
them.  To play with these, first create a subdirectory called
\texttt{scratch} of your home directory where you will keep scratch
\guru files (we will later use such a subdirectory for homework and
the project, so we will start off that way for uniformity).  Then
start up a text editor, and create a new file in your scratch
subdirectory called \texttt{test.g}.  Start this file with the
following text:

\begin{verbatim}
Include "../guru-lang/lib/plus.g".
\end{verbatim}

\noindent This \texttt{Include}-command will tell \texttt{guru} to
include the file \texttt{plus.g} from the standard library.  Then
include the following additional command:

\begin{verbatim}
Interpret (plus (S (S Z)) (S (S Z))).
\end{verbatim}

\noindent This \texttt{Interpret}-command tells \guru to run its
interpreter on the given expression.  The interpreter will evaluate
the expression to a value, and then print the value.  This expression
is an application of the function \texttt{plus}, which we will see how
to define shortly, to 2 and 2, written in unary.  Naturally, we expect
this will evaluate to 4, written in unary.

To run \texttt{guru} on your \texttt{test.g} file, first make sure
you have saved your changes to it.  Then, start a shell, and run
the following command in your home directory

\begin{verbatim}
guru-lang/bin/guru scratch/test.g
\end{verbatim}

\noindent This runs the \texttt{guru} tool on your file.  You should
see it print out the expected result of adding 2 and 2 in unary:

\begin{verbatim}
(S (S (S (S Z))))
\end{verbatim}

The declaration of the unary natural numbers is in
\texttt{guru-lang/lib/nat.g}, which is included by the file
\texttt{plus.g} which we have included here.  If you look in
\texttt{nat.g}, you will find at the top:

\begin{verbatim}
Inductive nat : type :=
  Z : nat
| S : Fun(x:nat).nat.
\end{verbatim}

\noindent This is an \texttt{Inductive}-command.  It instructs \guru\
to declare the new inductive datatype \texttt{nat}.  The ``\texttt{nat
: type}'' on the first line of the declaration just tells \guru that
\texttt{nat} is a type.  We will see other examples later which use
more complicated declarations than just ``: \texttt{type}''.  In more
detail, ``\texttt{nat} : \texttt{type}'' means that \texttt{type} is
the \emph{classifier} of \texttt{nat}.  The concept of classifier is
central to \guru.  For example, the next two lines declare the
classifiers for \texttt{Z} (zero) and \texttt{S} (successor).  So what
is a classifier?  In \guru, some expressions are classifiers for
others.  For example, \texttt{type} is the classifier for types.
Following the processing of this \texttt{Inductive}-command, we will
also have that \texttt{nat} is the classifier for unary natural
numbers encoded with \texttt{Z} and \texttt{S}.  The classifier for
\texttt{S} states that it is a function (indicated with \texttt{Fun})
that takes in an input called \texttt{x} that is a \texttt{nat}, and
then produces a \texttt{nat}.  Generally speaking, classifiers
partition expressions into sets of expressions that have certain
similar properties.  Every expression in \textsc{Guru} has exactly one
classifier.

An additional simple piece of terminology is useful.  The constructor
\texttt{Z} returns a \texttt{nat} as output without being given any
\texttt{nat} (or any other data) as input.  In general, a constructor
of a type \texttt{T} which has the property that it returns a
\texttt{T} as output without requiring a \texttt{T} as input is called
a \emph{base} constructor.  In contrast, \texttt{S} does require a
\texttt{nat} as input.  In general, a constructor of a type \texttt{T}
which requires a \texttt{T} as input is called a \emph{recursive}
constructor.

We should note finally that \guru does not provide decimal notation
for unary natural numbers.  Indeed, \guru currently does not provide
special syntax for describing any data.  There are no built-in
datatypes in \guru: all data are inductive, constructed by applying
constructors (like \texttt{S} and \texttt{Z}) to smaller data.

\section{Non-recursive Functions}
\label{ch2:nonrec}

Suppose we want to define a doubling function, based on the
\texttt{plus} function we used before.  We have not seen how to define
\texttt{plus} yet, since it requires recursion and pattern matching.
But of course, we can write a function which calls \texttt{plus},
even if we do not know how \texttt{plus} is written.  The doubling
function can be written like this:

\begin{verbatim}
fun(x:nat).(plus x x)
\end{verbatim}

\noindent Let us examine this piece of code.  First, ``\texttt{fun}''
is the keyword which begins a function, also called a
\texttt{fun}-term.  After this keyword come the arguments to the
function, in parentheses.  In this case, there is just one argument,
\texttt{x}.  Arguments must be listed with their types (with a colon
in between).  In this case, the type is \texttt{nat}.  After the
arguments we have a period, and then the \emph{body} of the
\texttt{fun}-term.  The body just gives the code to compute the value
returned by the function.  In this case, the value returned is just
the result of the application of \texttt{plus} to \texttt{x} and
\texttt{x}, for which the notation, as we have already seen, is
\texttt{(plus x x)}.

To use this function in \guru, try the following.  In your scratch
subdirectory (of your home directory), create a file \texttt{test.g},
and begin it with

\begin{verbatim}
Include "../guru-lang/lib/plus.g".
\end{verbatim}

\noindent As for the example in Section~\ref{ch2:natguru} above,
this includes the definitions of \texttt{nat} and \texttt{plus}.
Next write:

\begin{verbatim}
Interpret (fun(x:nat).(plus x x) (S (S Z))).
\end{verbatim}

\noindent Save this file, and then from your home directory run
\guru on your file:

\begin{verbatim}
guru-lang/bin/guru scratch/test.g
\end{verbatim}

\noindent You should see it print out the expected result of doubling
2, in unary:

\begin{verbatim}
(S (S (S (S Z))))
\end{verbatim}

\noindent This example illustrates the fact that
\texttt{fun(x:nat).(plus x x)} is really a function, just like
\texttt{plus}.  Just as we can apply \texttt{plus} to arguments
\texttt{x} and \texttt{y} by writing \texttt{(plus x x)}, we can also
apply \texttt{fun(x:nat).(plus x x)} to an argument \texttt{(S (S Z))}
by writing \texttt{(fun(x:nat).(plus x x) (S (S Z)))}, as we did in
this example.

\subsection{Definitions}

Most often we write a function expecting it to be called in multiple
places in our code.  We would like to give the function a name, and
then refer to it by that name later.  In \textsc{Guru}, this can be
done with a \texttt{Define}-command. To demonstrate this, add to the
bottom of \texttt{test.g} the following:

\begin{verbatim}
Define double := fun(x:nat).(plus x x).

Interpret (double (S (S Z))).
\end{verbatim}

\noindent The \texttt{Define}-command assigns name \texttt{double} to
the \texttt{fun}-term.  We can then refer to that function by
the name \texttt{double}, as we do in the subsequent
\texttt{Interpret}-command.  If you run \guru on \texttt{test.g},
you will see the same result for this \texttt{Interpret}-command
as we had previously: \texttt{(S (S (S (S Z))))}.

\subsection{Multiple arguments}

The syntax for functions with multiple arguments is demonstrated
by this example:

\begin{verbatim}
Define double_plus := fun(x:nat)(y:nat). (plus (double x) (double y)).
\end{verbatim}

\noindent This function is supposed to double each of its two
arguments, and then add them.  The nested application \texttt{(plus
(double x) (double y))} does that.  The \texttt{fun}-term is
written with each argument and its type between parentheses, as this
example shows.  There is a more concise notation when consecutive
arguments have the same type, demonstrated by:

\begin{verbatim}
Define double_plus_a := fun(x y:nat). (plus (double x) (double y)).
\end{verbatim}

\noindent Multiple consecutive arguments can be listed in the same
parenthetical group, followed by a colon, and then their type.

\subsection{Function types}
\label{ch2:func}

You can see the classifier that \guru computes for the \texttt{double}
function as follows.  In your \texttt{test.g} file (in your home
directory, beginning with an \texttt{Include}-command to include
\texttt{plus.g}, as above), write the following:

\begin{verbatim}
Define double := fun(x:nat).(plus x x).

Classify double.
\end{verbatim}

\noindent If you (save your file and then) run \guru on \texttt{test.g},
it will print

\begin{verbatim}
Fun(x : nat). nat
\end{verbatim}

\noindent This is a \texttt{Fun}-type.  \texttt{Fun}-types classify
\texttt{fun}-term by showing the input names and types, and
the output type.  We can see that \guru has computed the (correct)
output type \texttt{nat} for our doubling function.

Earlier it was mentioned that every expression in \guru has a
classifier.  You may be curious to see what the classifier for
\texttt{Fun(x : nat). nat} is.  So add the following to your
\texttt{test.g} and re-run \guru on it:

\begin{verbatim}
Classify Fun(x : nat). nat.
\end{verbatim}

\noindent You will see the result \texttt{type}.  If you ask \guru\
for the classifier of \texttt{type}, it will tell you \texttt{tkind}.
If you ask for the classifier of \texttt{tkind}, \guru will report a
parse error, because \texttt{tkind} is not an expression.  So the
classification hierarchy stops there.  We have the following
classifications (this is not valid \guru syntax, but nicely shows the
classification relationships):

\begin{verbatim}
fun(x:nat).(plus x x)  :  Fun(x:nat).nat  :  type  :  tkind
\end{verbatim} 

\subsection{Functions as inputs}

Now that we have seen how to write function types, we can write a
function that takes in a function \texttt{f} of type
\texttt{Fun(x:nat).nat} and applies \texttt{f} twice to an argument
\texttt{a}:

\begin{verbatim}
Define apply_twice := fun(f:Fun(x:nat).nat)(a:nat). (f (f a)).
\end{verbatim}

\noindent There is no new syntax here: we are just writing another
\texttt{fun}-term with arguments \texttt{f} and \texttt{a}.  The
difference from previous examples, of course, is that the type we list
for \texttt{f} is a \texttt{Fun}-type.  An argument to a
\texttt{fun}-term (or listed in a \texttt{Fun}-type) can have any
legal \guru type, including, as here, a \texttt{Fun}-type. You can
test out this example like this (although before you run it, try to
figure out what it will compute):

\begin{verbatim}
Interpret (apply_twice double (S (S Z))).
\end{verbatim}

\subsection{Functions as outputs}

Functions can be returned as output from other functions.  This is
actually already possible with functions we have seen above.  For
example, consider the \texttt{plus} function.  Its type, as revealed
by a \texttt{Classify}-command, is 

\begin{verbatim}
Fun(n : nat)(m : nat). nat
\end{verbatim}

\noindent Now try the following:

\begin{verbatim}
Classify (plus (S (S Z))).
\end{verbatim}

\noindent \guru will say that the classifier of this expression is:

\begin{verbatim}
Fun(m : nat). nat
\end{verbatim}

\noindent This example shows that we can apply functions to fewer than
all the arguments they accept.  Such an application is called a
\emph{partial application} of the function.  In this case,
\texttt{plus} accepts two arguments, but we can apply it to just the
first argument, in this case \texttt{(S (S Z))}.  The result is a
function that is waiting for the second argument \texttt{m}, and will
then return the result of adding two to m.  This point can be brought
out with the following:

\begin{verbatim}
Define plus2 := (plus (S (S Z))).

Interpret (plus2 (S (S (S Z)))).
\end{verbatim}

\noindent We define the \texttt{plus2} function to be the partial
application of \texttt{plus} to \texttt{(S (S Z))}, and then interpret
the application of \texttt{plus2} to three.  \guru will print five
(in unary), as expected.

For another example of using functions as outputs, here is a function
to compose two functions, each of type \texttt{Fun(x:nat).nat}:

\begin{verbatim}
fun(f g : Fun(x:nat).nat). fun(x:nat). (f (g x))
\end{verbatim}

\noindent The inputs to this \texttt{fun}-term are functions \texttt{f} and \texttt{g}.
The body, which computes the output value returned by the function, is

\begin{verbatim}
fun(x:nat). (f (g x))
\end{verbatim}

\noindent This is, of course, a function that takes in input \texttt{x} of type
\texttt{nat}, and returns \texttt{(f (g x))}.  In \guru, what we have written
as the definition of our composition function is equivalent to:

\begin{verbatim}
fun(f g : Fun(x:nat).nat)(x:nat). (f (g x))
\end{verbatim}

\noindent That is, due to partial applications, we can write our
composition function as a function with three arguments: \texttt{f},
\texttt{g}, and \texttt{x}.  We can then just apply it to the first
two, to get the composition.

\subsection{Comments}

This is not a bad place to describe the syntax for comments in \guru.  To
comment out all text to the end of the line, we use \%.  For example:

\begin{verbatim}
Define plus2 := (plus (S (S Z))).  % This text here is in a comment.
\end{verbatim}

\noindent Comments can also be started and stopped by enclosing them
betwee \texttt{\%-} and \texttt{-\%}, as in:

\begin{verbatim}
%- Comments can also be written using
   this syntax. -%
\end{verbatim}

\noindent Comments can be placed anywhere in \guru input, including in the
middle of expressions, like this:

\begin{verbatim}
Interpret (plus %- here is a comment -% Z).
\end{verbatim}

\noindent Finally, it is legal to nest comments.

\section{Pattern Matching}

Like other functional languages that rely on inductive datatypes,
\guru programs can use pattern matching to analyze data by taking it
apart into its subdata.  To demonstrate this, we will write a simple
function to test whether a \texttt{nat} is zero (\texttt{Z}) or not.
For this, we need the definition of booleans, provided in
\texttt{guru-lang/lib/bool.g}.  This file is included by
\texttt{nat.g} (included by \texttt{plus.g}), so we do not need to
include \texttt{bool.g} explicitly.  It is worth noting that it is not
an error in \guru to include a file multiple times: \guru keeps track
of which files have been included (by their full pathnames), and
ignores requests after the first one to include the file.  So suppose
our \texttt{test.g} file in our home directory starts off as above:

\begin{verbatim}
Include "../guru-lang/lib/plus.g".
\end{verbatim}

\noindent This will pull in the declaration of the booleans, which is:

\begin{verbatim}
Inductive bool : type :=
  ff : bool
| tt : bool.
\end{verbatim}

\noindent Just as for the declaration of \texttt{nat} above, this
\texttt{Inductive}-command instructs \guru to add constructors
\texttt{tt} (for true) and \texttt{ff} (for false), both of type
\texttt{bool}.  Now we can define the \texttt{iszero} function as
follows:

\begin{verbatim}
Define iszero := 
  fun(x:nat). 
    match x with 
      Z => tt 
    | S x' => ff
    end.
\end{verbatim}

\noindent Let us walk through this definition.  First, we see it is
written across several lines, with changing indentation.  Whitespace
in \guru has no semantic impact.  So the indentation and line breaks
are just (intended) to make it easier to read the code.  It would have
the same meaning if we wrote it all on one line, like this:

\begin{verbatim}
Define iszero := fun(x:nat). match x with Z => tt | S x' => ff end.
\end{verbatim}

\noindent To return to the code: we have a \texttt{Define}-command,
just as we have seen above.  We are defining \texttt{iszero} to be a
certain \texttt{fun}-term.  This \texttt{fun}-term takes in input
\texttt{x} of type \texttt{nat}, and then it matches on \texttt{x}.
Here is where the pattern matching comes into play.  

We have ``\texttt{match x with}''.  In this first part of the
\texttt{match}-term, we are saying we want to pattern match on
\texttt{x}.  We are allowed to match on anything whose type is an
inductive type (i.e., declared with an \texttt{Inductive}-command).
We cannot match on functions, for example, because they have
\texttt{Fun}-types, which are not inductive.  The term we are matching
on is called the \emph{scrutinee} (because the \texttt{match}-term is
scrutinizing -- i.e., analyzing -- it).  

Next come the \texttt{match}-clauses, separated by a bar (``\texttt{|}''):

\begin{verbatim}
      Z => tt 
    | S x' => ff
\end{verbatim}

\noindent We have one clause for each constructor of the scrutinee's
type.  The scrutinee (\texttt{x} in ``\texttt{match x with}'') has
type \texttt{nat}, which has constructors \texttt{Z} and \texttt{S},
so we have one clause for each of those constructors.  It is required
in \guru to list the clauses in the same order as the constructors
were declared in the \texttt{Inductive}-command which declared the
datatype.  Our declaration of \texttt{nat} (back in
Section~\ref{ch2:natguru}) lists \texttt{Z} first and then \texttt{S},
so that explains the ordering of the \texttt{match}-clauses here.

Each \texttt{match}-case starts out with a pattern for the
corresponding constructor.  The pattern starts with the constructor,
and then lists different variables for each of the constructor's
arguments.  So we have the patterns \texttt{Z} and \texttt{S x'}.  The
first pattern has no variables, since \texttt{Z} takes no arguments.
The second pattern has the single variable \texttt{x'}, for the sole
argument of \texttt{S}.  These variables are called pattern variables.
They are declared by the pattern, and their scope is the rest of the
\texttt{match}-clause.

After the pattern, each \texttt{match}-clause has ``\texttt{=>}'', and
then its \emph{body}.  This is similar to the body of a
\texttt{fun}-term: it gives the code to compute the value returned by
the function.  For our \texttt{iszero} function, we return \texttt{tt}
in the zero (\texttt{Z}) case, and \texttt{ff} in the successor
(\texttt{S}) case.  If we then run the following example, we will get
the expected value of \texttt{tt}:

\begin{verbatim}
Interpret (iszero Z).
\end{verbatim}

\subsection{A note on parse errors}
\label{ch2:err}

\guru generally tries to provide detailed error messages.  One
exception, unfortunately, is parse errors.  These are errors in
syntax, for example, writing something like ``\texttt{(plus Z Z}''
where the closing parenthesis is missing.  Let us see one example
of the kind of error message \guru will give for a parse error.
Suppose we write our \texttt{iszero} function, but forget to put
a period after the list of arguments:

\begin{verbatim}
Define iszero := 
  fun(x:nat) 
    match x with 
      Z => tt 
    | S x' => ff
    end.
\end{verbatim}

\noindent \guru will print an error message like the following
in this case:

\begin{verbatim}
"/home/stump/guru-lang/doc/test.g", line 5, column 4: parse error.
Expected "." parsing fun term
\end{verbatim}

The error message begins with the location of the error, including the
file where the error occurred, the line number and column within that
line:

\begin{verbatim}
"/home/stump/guru-lang/doc/test.g", line 5, column 4
\end{verbatim}

 \noindent Next comes a very short statement of the rough kind of
error in question.  This is indeed a parse error, meaning that it is
arose while trying to parse the text in \texttt{test.g} into a legal
\guru expression.  Then comes the more detailed error message, which
in this case as for most parse errors is pretty short:

\begin{verbatim}
Expected "." parsing fun term
\end{verbatim}

 \noindent This happens to be somewhat informative, but regrettably,
especially for parse errors, that is not often the case.

\section{Recursive Functions}
\label{ch2:rec}

We are finally in a position now to see how to define recursive
functions.  \guru does not have iterative looping constructs like
\texttt{while}- or \texttt{for}-loops.  Instead, all looping is done
by recursion.  Here is the code for \texttt{plus}, taken from
\texttt{guru-lang/lib/plus.g}:

\begin{verbatim}
  fun plus(n m : nat) : nat.
    match n with
      Z => m
    | S n' => (S (plus n' m))
    end
\end{verbatim}

\noindent This is a recursive \texttt{fun}-term.  There are two main
differences from the non-recursive \texttt{fun}-terms we have seen
above.  First and foremost, the ``\texttt{fun}'' keyword is followed
by a name for the recursive function.  This name can be used in the
body of the function to make a recursive call.  We see it used in the
second \texttt{match}-clause.  We will walk through the
\texttt{match}-clauses in just a moment, but before that we note the
second distinctive feature of a recursive \texttt{fun}-term: after the
argument list (``\texttt{(n m : nat)}''), there is colon and then the
return type of the \texttt{fun}-term is listed (``\texttt{ : nat}'').
Since \texttt{plus} returns a \texttt{nat}, that is the return type.
The reason \guru requires us to list the return type here for a
recursive \texttt{fun}-term is that it makes it much easier to type
check the term.  Wherever \texttt{plus} is called in the body of the
function, we know exactly what its input types and output type are.
If \guru allowed us to omit the output type here at the start of the
\texttt{fun}-term, then the type checker would not know the type of
the value that is being computed by the recursive call to
\texttt{plus} in the second \texttt{match}-clause.

Syntactically, there is nothing else new in the code.  But let us try
to understand how it manages to add two unary natural numbers.  The
code is based on the following two mathematical equations:
\begin{eqnarray}
\label{ch2:eq1}
0+ m & = & m \\
(1+n')+m & = & 1+(n'+m)
\end{eqnarray}

\noindent These are certainly true statements about addition.  But
how do they relate to the \texttt{fun}-term written above?  Let us
see how to transform them step by step into that \texttt{fun}-term.
First, we should recognize that $0$ and $1+x$ are just different
notation for zero and successor of $x$.  If we use the notation we
have used in \guru so far for these, the mathematical equations
turn into:
\begin{eqnarray*}
\texttt{Z}+ m & = & m \\
(\texttt{S}\ n')+m & = & (\texttt{S}\ (n'+m))
\end{eqnarray*}

\noindent Now, we do not have infix notation in \guru for functions,
so let us replace the infix $+$ symbol with a prefix \texttt{plus}:

\begin{eqnarray*}
\texttt{(plus Z m)} & = & m \\
\texttt{(plus (S n') m)} & = & \texttt{(S (plus n' m))}
\end{eqnarray*}

\noindent Now look at the right hand sides of the equations we have
derived by this simple syntactic transformation.  They are exactly the
same as the bodies of the \texttt{match}-clauses for the recursive
\texttt{fun}-term for \texttt{plus}.  The final connection can be made
between these equations and that \texttt{fun}-term by observing that
the equations are performing a case split on the first argument
(called \texttt{n} in the \texttt{fun}-term): either it is \texttt{Z},
or else it is \texttt{S n'} for some \texttt{n'}.  This case split is
done in the \texttt{fun}-term using pattern matching.  The final point
to observe is that where we use \texttt{plus} on the right hand side
of the second equation, we are making a recursive call to
\texttt{plus}.  This corresponds to the recursive call in the
\texttt{fun}-term.  In fact, we can observe that with each recursive
call, the first argument gets smaller.  It is \texttt{(S n')} to start
with, and then decreases to \texttt{n'}, which is \emph{structurally
smaller} than \texttt{(S n')}.  Structurally smaller means that
\texttt{n'} is actually subdata of \texttt{(S n')}.  While we do not
need this observation now, it will be critical when reasoning with
\texttt{plus}, since it implies that \texttt{plus} is a \emph{total}
function.  That is, \texttt{plus} is guaranteed to terminate with a
value for all inputs we give it.

\section{Summary}

In this chapter, we have seen the four basic programming features of
\guru, in the setting of monomorphic programming:
\begin{itemize}
\item inductive datatypes, like \texttt{nat} for unary natural
numbers, which has \emph{constructors} \texttt{Z} for zero and
\texttt{S} for the successor of a number;
\item applications like \texttt{(S Z)} of a function (which happens to be a constructor) \texttt{S} to argument \texttt{Z},
and like \texttt{(plus x y)} for applying the function \texttt{plus} to arguments \texttt{x} and \texttt{y};
\item non-recursive functions, like the doubling function \texttt{fun(x:nat).(plus x x)}, and recursive ones, like \texttt{plus}; and
\item pattern matching, which allows us to analyze (i.e., take apart)
a piece of data (the \emph{scrutinee}) into its subdata.
\end{itemize}

 \noindent We have also seen how to run \guru on simple examples,
drawing on code from the \guru standard library (like the code for
\texttt{plus}).

\section{Exercises}

\begin{enumerate}

\item The standard library files in \texttt{guru-lang/lib/} define
several other functions that operate on unary natural numbers.  List
at least three, and say what you think they do.

\item The \texttt{plus} function defined above (Section~\ref{ch2:rec})
analyzes its first argument.  Write a similar function \texttt{plus'}
that also adds two natural numbers, but analyzes its second argument.
Test your function by adding 2 and 3 (in unary), using the appropriate
\texttt{Interpret}-command and \texttt{plus'}.

\item Define a inductive datatype called \texttt{day}, with one
constructor for each day of the week.  Then define a function
\texttt{next\_day} which takes a \texttt{day} as input and returns a
\texttt{day} as output.  Your function should return the next day of
the week.  Test your function by getting the next day after Saturday
(using an \texttt{Interpret}-command).

\item Using the function \texttt{next\_day}, write a function \texttt{nth\_day}
of type \texttt{Fun(d:day)(n:nat).day}.  Your function should return the \texttt{n}'th
next day after the given day \texttt{d}.  For example, if \texttt{d} is Monday and
\texttt{n} is 2, you should return Wednesday.  Test your function by getting
the 2nd day after Monday.

\item Look at the function \texttt{mult} defined in \texttt{mult.g}.
Write mathematical equations corresponding to the \texttt{fun}-term
for \texttt{mult}, like those labeled (\ref{ch2:eq1}) in
Section~\ref{ch2:rec} above.  Give a brief informal explanation of why
those equations are true mathematical facts.

\item The following equations return a \texttt{tt} or \texttt{ff} depending
on whether or not two \texttt{nat}s are in a certain relationship to each
other.  What is that relationship?

\begin{verbatim}
(f Z Z) = ff
(f (S x) Z) = tt
(f Z (S y)) = tt
(f (S x) (S y)) = (f x y)
\end{verbatim}

\noindent Define a function (in \guru) to implement these mathematical
equations.  Hint: because the equations analyze each argument, you will
need to use nested pattern matching.  Match first on one argument, and
then in each resulting \texttt{match}-clause, match on the other.  Test
your function on 2 and 3.

\item The following mathematical equations define the
\texttt{n}-fold iteration of a unary (``one argument'') function
\texttt{f} on an argument \texttt{a}:

\begin{verbatim}
(iter Z f a) = a
(iter (S n) f a) = f (iter n f a)
\end{verbatim}

\noindent First, write down the type (in \guru notation) that you
expect \texttt{iter} to have.  Next implement \texttt{iter}, and test
your function with this testcase: \texttt{(iter (S (S (S Z))) double
(S Z))}, where \texttt{double} is the doubling function of
Section~\ref{ch2:nonrec} above (before you run \guru on this: what
do you think it will compute?).

\item Write a function \texttt{first} which, given a function
\texttt{P} of type \texttt{Fun(x:nat).bool} returns the smallest
natural number \texttt{n} such that \texttt{(P n)} evaluates to
\texttt{tt}.  Hint: you will probably need to write a second
\emph{helper} function which takes as an additional argument the next
number to try (for whether \texttt{P} returns \texttt{tt} or
\texttt{ff} for that number).  

\ 

Test your function with the following commands.  Here, \texttt{eqnat}
is a function, defined in \texttt{nat.g}, which takes two
\texttt{nat}s as input and returns \texttt{tt} if they are equal, and
\texttt{ff} otherwise).  Also, \texttt{nine} is defined in
\texttt{nat.g} to be $9$ in unary.

\begin{verbatim}
Include "../guru-lang/lib/mult.g".

Interpret (first fun(x:nat). (eqnat (mult x x) nine)).
\end{verbatim}

\noindent Give an informal description of the mathematical
relationship between the value this returns and 9.

\end{enumerate}

\chapter{Equational Monomorphic Proving}
\label{ch2}

The material from the last chapter is probably not entirely alien to
most readers, since, although the functional programming paradigm is
quite a bit different from the iterative imperative programming which
most computer scientists know best, it is, after all, still
programming.  In this chapter, we will move farther afield from what
is most of our experience as programmers, and enter the world of
formal, machine-checked proofs about programs.  Proofs have a lot in
common with typed programs.  Both are written according to certain
rules of syntax, and both have a rigid compile-time semantics:
programs must type check, and proofs must proof check.  In \guru, the
compiler attempts to compute a formula for a proof in a very similar
way as it computes a type for a program.  The formula in question is
the one proved by the proof.

Before we begin, it should be noted that the particular style of
writing proofs used here is not the only one, and indeed, there are
other styles which are more widely used.  For an important example,
tools like \textsc{Coq} are based not on proofs directly, but rather
on \emph{proof scripts}.  These are higher level scripts that instruct
\textsc{Coq} on how to build the actual proof.  The level of
indirection introduced by proof scripts can make life easier for us
program provers, at least in the short run: there is less detail that
needs to be written down in a proof script than in a proof.  But in
the long run, proof scripts have serious problems: because they are
indirect, they are very hard or impossible to read; and they can be
quite brittle, breaking badly under even minor changes to the program
or proof in question.  In contrast, fully detailed proofs make the
proof information more explicit, and so are -- while still quite
difficult to read, usually -- somewhat more readable than proof
scripts.  Also, minor changes do not so immediately lead to broken
proofs.

The focus in this chapter is on equational reasoning.  In
Chapter~\ref{ch5} we will look at logical reasoning.  The distinction
I am drawing here is between reasoning which is primarily about the
equational relationships between terms (that is equational reasoning);
and reasoning which is primarily about the logical relationships
between formulas.  An example of equational reasoning is proving that
for all \texttt{nat}s \texttt{x}, \texttt{x} plus zero equals
\texttt{x}.  An example of logical reasoning is proving that if
\texttt{x} and \texttt{y} are non-zero, then so is \texttt{(plus x
y)}.

The most powerful and most difficult to master method of proof is
proof by datatype induction, introduced in Chapter~\ref{ch4}.  Every
program prover has to cope with this proof method, and learn to apply
it effectively.  We will begin in this chapter, however, with much
more manageable forms of proof.

For the next several chapters, we will be using very simple examples
of programs, like the addition program that adds two numbers.  This is
certainly not the most exciting program, but it seems to provide a
good balance of simplicity and interesting theorems to prove.  Please
be assured that we will get to more complex and realistic programming
examples after we get the basics of monomorphic programming and
proving down.

\section{Preview}

We consider two of the five kinds of formulas in \guru (the rest
are introduced in the next chapter):

\begin{itemize}

\item equations, like \texttt{\{ (plus Z Z) = Z \}}.  This one states
that zero (\texttt{Z}) plus zero equals zero.  There are also
disequations $\{ t_1\texttt{ != } t_2 \}$ stating that two entities
$t_1$ and $t_2$ are not equal.

\item \texttt{Forall}-formulas, like \texttt{Forall(x:nat).\{ (plus Z
x) = x\}}.  This one states that zero plus \texttt{x} equals
\texttt{x}, for any \texttt{nat} \texttt{x}.  This formula is provable
in \guru, since indeed, adding zero to any number just returns that number.

\end{itemize}

The forms of proof covered in this chapter are:

\begin{itemize}

\item $\texttt{join}\ t_1\ t_2$, where $t_1$ and $t_2$ are terms.
This tries to prove the equation $\{ t_1 = t_2 \}$ just by evaluating
$t_1$ and $t_2$ with the \guru interpreter, and seeing if the results
are equal.  We use partial evaluation to evaluate terms which contain
variables.

\item \texttt{foralli(x:nat).P}, where \texttt{P} is another proof, is
a \texttt{Forall}-introduction: it lets us prove
the formula \texttt{Forall(x:nat).F}, when \texttt{P} is a proof of \texttt{F}
using an arbitrary \texttt{x}, about which nothing is known.  If we
have a proof \texttt{P} of a \texttt{Forall}-formula, we can
instantiate the \texttt{Forall} quantifier, to replace the quantified
variable with a value term $t$, using the syntax $[P\ t]$.

\item \texttt{refl t}: this proves $\{ t = t \}$.

\item \texttt{symm P}: if \texttt{P} proves $\{ t_1 = t_2 \}$ , then
the \texttt{symm}-proof proves $\{ t_2 = t_1 \}$.

\item \texttt{trans P1 P2}: if \texttt{P1} proves $\{ t_1 = t_2 \}$ and
\texttt{P2} proves $\{ t_2 = t_3 \}$, then the \texttt{trans}-proof proves
$\{ t_1 = t_3 \}$.

\item \texttt{cong t* P}: if \texttt{P} proves $\{ t_1 = t_2 \}$, then
the \texttt{cong}-proof proves $\{ t*[t_1] = t*[t_2]\}$, where $t*[t_1]$
is our notation (not \guru's) for the result of substituting $t_1$ for
a special variable $*$ occurring in \emph{term context} $t*$.

\item \texttt{case}-proofs, which are syntactically quite similar
to \texttt{match}-terms, and allow us to prove a theorem by cases
on the form of a value in an inductive datatype.

\end{itemize}

\section{Proof by Evaluation}
\label{ch3:eval}

Probably the simplest form of proof in \guru, and other similar tools,
is proof by evaluation.  For example, we have seen above that
\texttt{(plus (S (S Z)) (S (S Z)))} evaluates using an
\texttt{Interpret}-command to \texttt{(S (S (S (S Z))))}.  Let us
write \texttt{two} for \texttt{(S (S Z))} and \texttt{four} for
\texttt{(S (S (S (S Z))))} -- in fact, \texttt{nat.g} makes such
definitions.  Then we can easily record this fact as a theorem, like
this:

\begin{verbatim}
Define plus224 := join (plus two two) four.

Classify plus224.
\end{verbatim}

 \noindent This code defines \texttt{plus224} to be a certain proof.
The proof is a \texttt{join}-proof.  The syntax for such a proof is
$\texttt{join}\ t_1\ t_2$, where $t_1$ and $t_2$ are terms.  Here,
$t_1$ is \texttt{(plus two two)}, and $t_2$ is \texttt{four}.  If you
run \guru on this example, it will print, in response to the
\texttt{Classify}-command, the following:

\begin{verbatim}
{ (plus two two) = four }
\end{verbatim}

\noindent This is \guru syntax for an equation.  An equation is
provable in \guru only if the left and right hand sides both diverge
(run forever), or both converge to a common value.  A
\texttt{join}-proof $\texttt{join}\ t_1\ t_2$ attempts to prove the
equation $\{ t_1 = t_2 \}$ by evaluating $t_1$ and $t_2$ (using the
interpreter), and checking to see if the results are equal.  In this
case, they are, since \texttt{(plus two two)} evaluates to
\texttt{four}, and of course, \texttt{four} also evaluates to
\texttt{four}.

Based on this description of how \texttt{join}-proofs work, we can
already see how to prove some slightly less trivial theorems: we do not
have to put a value like \texttt{four} on the right hand side, but instead,
we can put some other term that evaluates to the same value as the left hand
side.  So we could prove the formula

\begin{verbatim}
{ (plus two two) = (plus one three) }
\end{verbatim}

\noindent using this \texttt{join}-proof:

\begin{verbatim}
join (plus two two) (plus one three)
\end{verbatim}

\noindent Proof by evaluation may seem rather trivial, but since in
\guru we are reasoning about programs based directly on their
\emph{operational} behavior -- that is, on the behavior they exhibit
when they are evaluated -- it is in some sense the cornerstone of all
other forms of proof we might want to use.  Our reasoning about
programs ultimately is based on running them.

\section{\texttt{Foralli} and Proof by Partial Evaluation}
\label{ch3:peval}

Our next proof method is a slight extension of proof by evaluation,
based on the following observation: we often do not need all the
inputs to be known values in order to see how a program will run.  Let
us recall, for example, the \texttt{plus} function:

\begin{verbatim}
  fun plus(n m : nat) : nat.
    match n with
      Z => m
    | S n' => (S (plus n' m))
    end
\end{verbatim}

\noindent We can see here that it is not necessary to know what
\texttt{m} is in order to evaluate \texttt{(plus n m)}.  We do need to
know what \texttt{n} is, because \texttt{plus} pattern-matches on it
right away.  But the code for \texttt{plus} does not inspect
\texttt{m} at all: it never pattern-matches on \texttt{m}, and it does
not call any other functions which might do so.  That suggests that
we should be able to prove theorems like

\begin{verbatim}
{ (plus Z m) = m }
\end{verbatim}

\noindent just by evaluating the application (i.e., \texttt{(plus Z m)}).  
Since we usually think of evaluation as requiring all arguments to be
known values, we call this proof by partial evaluation (as this is the
name used in computer science for evaluating programs with some arguments
left as unknowns).

To demonstrate proof by evaluation, we have to be able to introduce an
unknown value \texttt{m} into our proof.  One way to do this is with a
\texttt{foralli}-proof.  This \texttt{foralli} stands for
``Forall-introduction'', and it is a simple way to prove that some
statement is true for every \texttt{m} of some type.  For our example,
we will prove:

\begin{verbatim}
Forall(m:nat). { (plus Z m) = m}
\end{verbatim}

\noindent This is a \texttt{Forall}-formula.  It says that for every
\texttt{m} of type \texttt{nat}, \texttt{(plus Z m) = m}.  Here is how
we prove this formula in \guru, using \texttt{join} and \texttt{foralli}:

\begin{verbatim}
Define Zplus := foralli(m:nat). join (plus Z m) m.

Classify Zplus.
\end{verbatim}

 \noindent If you run \guru on this, it will indeed print out, in response
to the \texttt{Classify}-command:

\begin{verbatim}
Forall(m : nat) . { (plus Z m) = m }
\end{verbatim}

 \noindent Let us look at our \texttt{Zplus} proof in more detail.
The proof begins with ``\texttt{foralli(m:nat)}''.  This is quite
similar to a \texttt{fun}-term.  Just the way a \texttt{fun}-term
shows how to compute an output from any input \texttt{m}, in a similar
way a \texttt{foralli}-proof like this one shows how to prove a
formula for any \texttt{m}.  Logically speaking, we are going to
reason about an arbitrary \texttt{nat} \texttt{m}, about which we make
no constraining assumptions other than that it is indeed a
\texttt{nat}.  Since our reasoning will make no assumptions about
\texttt{m}, it would work for any \texttt{nat} we chose to substitute
for \texttt{m}.  It is in this way that it soundly proves a
\texttt{Forall}-formula.  

In this case, we are proving the formula $\{ \texttt{(plus Z m)} =
\texttt{m} \}$.  That is done by the \texttt{join}-proof, which here
is the body of the \texttt{foralli}-proof.  As we noted above, we can
evaluate \texttt{(plus Z m)} to \texttt{m} without knowing anything
about \texttt{m}.  This is because partial evaluation only needs to
evaluate the pattern-match on the first argument (\texttt{Z}), and it
can see that the first clause of the \texttt{match}-term is taken.

\subsection{A note on classification errors}
\label{ch3:err}

A \texttt{join}-proof works in the case we have just been considering,
only because the first argument is a known value, and \texttt{plus}
only inspects that first argument.  If we try switching the arguments,
we will get a classification error:

\begin{verbatim}
Define plusZa := foralli(m:nat). join (plus m Z) m.

Classify plusZ.
\end{verbatim}

 \noindent If you run this in \guru, you will get a pretty verbose error message
(where I have truncated parts of it with ``...''):

\begin{verbatim}
"/home/stump/guru-lang/doc/test.g", line 20, column 37: classification error.
Evaluation cannot join two terms in a join-proof.
1. normal form of first term: match m by n_eq n_Eq return ...
2. normal form of second term: m


These terms are not definitionally equal (causing the error above):
1. match m by n_eq n_Eq return ...
2. m
\end{verbatim}

 \noindent Because dealing with compile-time errors is a constant part
of our work in typed programming and even more so in proving, it is
worth stopping to take a look at this one.  First, as for the parse
error example in the previous chapter (Section~\ref{ch2:err}), the
error message begins with the location where the error occurred, and a
brief description of the kind of error it is.  This is a
classification error, meaning that the expression in question is
syntactically well-formed, but an error arose trying to compute a
classifier for it.  Then comes the more detailed error message:

\begin{verbatim}
Evaluation cannot join two terms in a join-proof.
1. normal form of first term: match m by n_eq n_Eq return ...
2. normal form of second term: m
\end{verbatim}

 \noindent This says that the two terms $t_1$ and $t_2$ given to
\texttt{join} do not evaluate to the same \emph{normal forms} -- that
is, final values that cannot be further evaluated.  We use the
terminology ``normal form'' here instead of ``value'', because in
partial evaluation, we might be forced to stop (partially) evaluating
before we get a value.  This typically happens when we try to
pattern-match on an unknown.  Partial evaluation gets stuck in such a
case, because it does not know what the unknown looks like, and so
cannot proceed with the pattern-match.  The error message here is
telling us that the left hand side evaluated to \texttt{match m by
...}, while the right hand side evaluated to just \texttt{m}.  Indeed,
this makes sense: the \texttt{plus} function wants to pattern-match on
its first argument, which here is \texttt{m}, and that is where
partial evaluation got stuck, just as I was mentioning.

Finally, whenever an error is due to the failure of two expressions to be
the same, we get a further piece of information:

\begin{verbatim}
These terms are not definitionally equal (causing the error above):
1. match m by n_eq n_Eq return ...
2. m
\end{verbatim}

\noindent In this case, that does not shed much light on the problem,
but in other cases, this information can be very useful.
``Definitionally equal'' is \guru's terminology for being the same
expression, ignoring certain trivial syntactic differences.  For
example, \texttt{one} and \texttt{(S Z)} are definitionally equal,
since \texttt{one} is defined to be \texttt{(S Z)}.  Differences in
folding or unfolding definitions (going from \texttt{(S Z)} to
\texttt{one} is folding, and vice versa is unfolding) are considered
trivial, and so fall under definitional equality.

\subsection{Terms, types, formulas, and proofs}

This is a good place to highlight briefly the fact mentioned earlier
that \guru has four distinct classes of expression:

\begin{itemize}
\item terms: these constitute programs and data, as described in Chapter~\ref{ch2}.  An example is \texttt{(plus Z Z)}.
\item types: these classify terms.  Examples are \texttt{nat} and \texttt{Fun(x:nat).nat}.
\item proofs: these prove formulas (and formulas classify proofs).  We
have just seen the examples of \texttt{join}-proofs for partial
evaluation and \texttt{foralli} to prove a universal.
\item formulas: these make statements about terms (and, we will see
later, also about types).  Examples we have seen so far are equations
like \texttt{\{ (plus two two) = four \}}; and
\texttt{Forall}-formulas (also called \emph{universal quantifications}
or universal formulas), like \texttt{Forall(m:nat). \{ (plus Z m) = m
\}}.
\end{itemize}

These classes use different syntax, except for a few commonalities
like variables; and so we can generally tell just by looking at a
\guru expression (and not needing to run \guru, for instance) what
kind of expression it is: term, type, proof, or formula.  Terms and
proofs are similar, and types and formulas are similar: the latter
pair classifies the former pair.

\subsection{Instantiating \texttt{Forall}-formulas}

To return to our methods of proof: we have just defined (in
Section~\ref{ch3:peval}) \texttt{Zplus} to be a proof of the following
formula:

\begin{verbatim}
Forall(m:nat). { (plus Z m) = m }
\end{verbatim}

\noindent When we have a proof of a \texttt{Forall}-formula, we know
that something is true for every value we can substitute for the
quantified variable (\texttt{m} in this case).  This substitution is
called an \emph{instantiation} of the \texttt{Forall}-formula.  There
is a form of proof for instantiating \texttt{Forall}-formulas.  It is
similar to application of a \texttt{fun}-term, but is written with
square brackets.  To instantiate the formula proved above by
\texttt{Zplus} with, for example, \texttt{three}, we write:

\begin{verbatim}
[Zplus three]
\end{verbatim}

\noindent So, our complete \texttt{test.g} file in our scratch
subdirectory of our home directory -- just to refresh this after
all the previous discussion -- can be written like this to demonstrate
this instantiation:

\begin{verbatim}
Include "../guru-lang/lib/plus.g".

Define Zplus := foralli(m:nat). join (plus Z m) m.

Classify [Zplus three].
\end{verbatim}

\noindent In response to the \texttt{Classify}-command, \guru will print:

\begin{verbatim}
{ (plus Z three) = three }
\end{verbatim}

\noindent In this case, there is no need for instantiation, since we
could have proved the same formula just as easily by \texttt{join
(plus Z three) three}.  Using instantiation is just for explanatory
purposes.  We will see a bit later a situation where using
instantiation in a case like this can be necessary.

Now is not a bad time to see what classifies a formula:

\begin{verbatim}
Classify { (plus Z three) = three }.
\end{verbatim}

\noindent \guru will print: \texttt{formula}.  \guru does not allow
you to ask what the classifier of \texttt{formula} is (for some
implementation reasons), but internally its classifier is
\texttt{fkind}.  There is no classifier of \texttt{fkind}, as it is
not considered an expression.  So we see that we have these
classification relationships for proofs and formulas:

\begin{verbatim}
[Zplus three]  :  { (plus Z three) = three }  :  formula  :  fkind
\end{verbatim} 

\noindent This is similar to the classifications described in
Section~\ref{ch2:func} above for terms and types:

\begin{verbatim}
fun(x:nat).(plus x x)  :  Fun(x:nat).nat  :  type  :  tkind
\end{verbatim} 

 \noindent We call \texttt{formula} and \texttt{type} \emph{kinds}
(the distinction between \texttt{tkind} and \texttt{fkind} is not
important in the current version of \guru).  

\section{Reflexivity, Symmetry and Transitivity}
\label{ch3:equiv}

The basic equivalence properties of equality are captured in the
\texttt{refl}, \texttt{symm} and \texttt{trans} proof forms.  Suppose
we have these definitions, similar to one we had in
Section~\ref{ch3:eval} above:

\begin{verbatim}
Define plus224 := join (plus two two) four.
Define plus413 := join four (plus one three).
\end{verbatim}

\noindent These proofs prove:

\begin{verbatim}
{ (plus two two) = four }
{ four = (plus one three) }
\end{verbatim}

\noindent We can put these two proofs together using a \texttt{trans}-proof:

\begin{verbatim}
Classify trans plus224 plus413.
\end{verbatim}

\noindent \guru will respond with:

\begin{verbatim}
{ (plus two two) = (plus one three) }
\end{verbatim}

\noindent If we want to swap the left and right hand side of this equation, we put a \texttt{symm}
around our existing proof:

\begin{verbatim}
Classify symm trans plus224 plus413.
\end{verbatim}

\noindent \guru will respond with:

\begin{verbatim}
{ (plus one three) = (plus two two) }
\end{verbatim}

\noindent Note that we do not use parentheses here.  \guru uses
parentheses exclusively for application terms.  The parsing rules for
\texttt{symm} and \texttt{trans} determine how things are grouped: the
syntax is \texttt{symm P1} and \texttt{symm P1 P2}, where \texttt{P1}
and \texttt{P2} are proofs.  Judicious use of indentation is used to
improve readability.  These example show that there can be more than
one way to prove something: we could have proved the theorems we just
got using \texttt{trans} and \texttt{symm} a different way, namely
with \texttt{join} directly.

Here is an example of a \texttt{refl}-proof:

\begin{verbatim}
Classify refl (fun loop(b:bool):bool. (loop b) tt).
\end{verbatim}

\noindent This proves that

\begin{verbatim}
{  (fun loop(b : bool) : bool. (loop b) tt)
 = (fun loop(b : bool) : bool. (loop b) tt) }
\end{verbatim}

\noindent This example is somewhat interesting, because the term
\texttt{(fun loop(b : bool) : bool. (loop b) tt)} runs forever, as you
will see if you run \guru with:

\begin{verbatim}
Interpret (fun loop(b : bool) : bool. (loop b) tt).
\end{verbatim}

\noindent In most cases, the work of \texttt{refl t} can be done with
\texttt{join t t}, but when \texttt{t} runs for a long time or does
not terminate, \texttt{refl} is preferable or even necessary.

\subsection{Error messages with \texttt{trans}-proofs}

It is very easy to make a mistake trying to connect two equational
subproofs using \texttt{trans}.  Let us look at an example, so it
is not shocking when such an error arises.  Suppose we have
these proofs:

\begin{verbatim}
Define plus224 := join (plus two two) four.
Define plus134 := join (plus one three) four.
\end{verbatim}

 \noindent We cannot, of course, glue them together with
\texttt{trans}, because the right hand side of the equation proved by
one must be the same as the left hand side of the equation proved by
the other.  If we try the following, we will get an error:

\begin{verbatim}
Classify trans plus224 plus134.
\end{verbatim}

\noindent The error from \guru is:

\begin{verbatim}
"/home/stump/guru-lang/doc/test.g", line 12, column 14: classification error.
A trans-proof is attempting to go from a to b and then b' to c,
where b is not definitionally equal to b'.

1. First equation:  { (plus two two) = four }
2. Second equation: { (plus one three) = four }

These terms are not definitionally equal (causing the error above):
1. (S three)
2. (plus one three)
\end{verbatim}

\noindent As above, we see the location of the error message first,
and the fact that it is a classification error (i.e., the proof is in
the correct syntax, but \guru encountered an error trying to compute a
classifier for it).  The error message states that the right hand side
of equation 1 is not definitionally equal to the left hand side of
equation 2.  That is, they are not syntactically the same expression
(ignoring certain minor syntactic differences).  Then we see the
last part of the error message:

\begin{verbatim}
These terms are not definitionally equal (causing the error above):
1. (S three)
2. (plus one three)
\end{verbatim}

\noindent The first term listed is definitionally equal to \texttt{four},
the right hand side of equation 1.  The second term is the left hand
side of equation 2.  \guru expects these to be definitionally equal,
but they are not.

\section{Congruence}

Along with reflexivity, symmetry, and transitivity, the main
equational reasoning inference is \emph{congruence}.  Consider again
our simple proof \texttt{plus224} from above:

\begin{verbatim}
Define plus224 := join (plus two two) four.
\end{verbatim}

\noindent As we have seen several times now, this proves:

\begin{verbatim}
{ (plus two two) = four }
\end{verbatim}

\noindent From this, we can also prove:

\begin{verbatim}
{ (S (plus two two)) = (S four) }
\end{verbatim}

\noindent That is, we can prove that the successor of two plus two is
equal to the successor of four (namely five).  What we are doing is
substituting the left and right hand sides of our first equation into
a pattern \texttt{(S *)} to get the second equation.  The pattern is
called a \emph{term context}, and it uses the special symbol $*$ to
indicate the position or positions where the substitution should take
place.  With these ideas, we can understand the \texttt{cong} form of
proof in \guru which formalizes this congruence reasoning:

\begin{verbatim}
Classify cong (S *) plus224.
\end{verbatim}

\noindent \guru will respond with the following, as expected:

\begin{verbatim}
{ (S (plus two two)) = (S four) }
\end{verbatim}

\noindent As another demonstration of \texttt{cong}, try the following in \guru:

\begin{verbatim}
Classify cong (plus * *) plus224.
\end{verbatim}

\section{Reasoning by Cases}
\label{ch3:case}

With the proof forms we have seen so far, we cannot prove very
exciting theorems.  For interesting theorems, we usually have to use
induction.  Induction involves a form of reasoning by cases.  So as a
warmup for induction, we will consider now a proof construct for
reasoning by cases, without doing induction.  This is the \texttt{case}
proof construct.

To demonstrate \texttt{case}-proofs, let us look at a definition of
boolean negation:

\begin{verbatim}
Define not :=
  fun(x:bool).
    match x with
      ff => tt
    | tt => ff
    end.
\end{verbatim}

\noindent This \texttt{Define}-command defines \texttt{not} to be a
function (i.e., a \texttt{fun}-term) that takes input \texttt{x} of
type \texttt{bool} and pattern-matches on it.  If \texttt{x} is
\texttt{ff} (boolean true), then we return \texttt{tt} for its
negation, and vice versa (if it is \texttt{tt}, we return
\texttt{ff}).  Notice that we have to list the \texttt{match}-clauses
in this order, since that is the order in which the constructors
for the \texttt{bool} datatype are declared, in \texttt{bool.g}:

\begin{verbatim}
Inductive bool : type :=
  ff : bool
| tt : bool.
\end{verbatim}

We will now see how to prove the following slightly interesting
theorem:

\begin{verbatim}
Forall(b:bool). { (not (not b)) = b }
\end{verbatim}

\noindent Informally, the reasoning needed to prove this theorem is
very simple.  Suppose we have an arbitrary value \texttt{b} of type
\texttt{bool}.  Either \texttt{b} is \texttt{ff} or it is \texttt{tt},
given the declaration of the \texttt{bool} datatype.  So suppose
\texttt{b} is \texttt{ff}.  Then \texttt{(not (not b))} is equal to
\texttt{(not (not ff))}, which evaluates to \texttt{ff}, which is
again equal to \texttt{b}.  So by transitivity of equality,
\texttt{(not (not b)) = b}.  We can write this down (informally) with
the following three equational steps:

\begin{verbatim}
(not (not b)) = (not (not ff)) = ff = b
\end{verbatim}

\noindent Similar reasoning applies in the case where \texttt{b} is
\texttt{tt}.

We can write this proof formally in \guru, as follows:

\begin{verbatim}
Define not_not : Forall(b:bool). { (not (not b)) = b } :=
  foralli(b:bool).
    case b with
      ff => trans cong (not (not *)) b_eq
            trans join (not (not ff)) ff
                  symm b_eq
    | tt => trans cong (not (not *)) b_eq
            trans join (not (not tt)) tt
                  symm b_eq           
    end.
\end{verbatim}

\noindent You can find this theorem in \texttt{guru-lang/lib/bool.g}.
We will walk through this and see how it works.  First, this is a
\texttt{Define}-command, but it uses one feature of \texttt{Define}
that we have not seen previously.  We can list a classifier that the
defined expression is supposed to have, and \guru will check for us
that it does.  So what we have written is of the form:

\begin{verbatim}
Define not_not : expected_classifier := proof.
\end{verbatim}

\noindent \guru will compute a formula for the proof, and then make
sure that that formula is definitionally equal (i.e., equal ignoring a
few minor syntactic variations, like folding and unfolding defined
symbols) to \texttt{expected\_classifier}.

Looking now at the actual proof that is given in the definition, it
is:

\begin{verbatim}
  foralli(b:bool).
    case b with
      ff => trans cong (not (not *)) b_eq
            trans join (not (not ff)) ff
                  symm b_eq
    | tt => trans cong (not (not *)) b_eq
            trans join (not (not tt)) tt
                  symm b_eq           
    end.
\end{verbatim}

\noindent This is a \texttt{foralli}-proof (see
Section~\ref{ch3:peval} above).  We are assuming an arbitrary value
\texttt{b} of type \texttt{bool}, just as in our informal proof above.
The body of the \texttt{foralli}-proof is a \texttt{case}-proof, again
corresponding to our informal case reasoning above.  The syntax for a
\texttt{case}-proof is very similar to the syntax for a
\texttt{match}-term.  We are performing a case analysis on the
scrutinee \texttt{b}, and we have one clause for each form of
\texttt{b}.  The body of each \texttt{case}-clause gives the proof of
the theorem in the case where \texttt{b} equals the pattern listed for
the clause.  To understand this better, let us look at the proof given
as the body of the clause for \texttt{ff}:

\begin{verbatim}
trans cong (not (not *)) b_eq
trans join (not (not ff)) ff
      symm b_eq
\end{verbatim}

 \noindent This consists of the following three subproofs, which are
glued together with \texttt{trans} (Section~\ref{ch3:equiv}):

\begin{enumerate}
\item \texttt{cong (not (not *)) b\_eq}
\item \texttt{join (not (not ff)) ff}
\item \texttt{symm b\_eq}
\end{enumerate}

\noindent Let us try to compute what theorem is proved by each of
these subproofs.  They all use familiar syntax, except that at this
point, we have not seen what \texttt{b\_eq} is.  This is an
\emph{assumption variable} introduced by the \texttt{case}-proof.  If
the scrutinee is a symbol (as \texttt{b} is), then the
\texttt{case}-proof introduces two assumption variables about
\texttt{b}: \texttt{b\_eq} and \texttt{b\_Eq}.  We will not use the
second until quite a bit later.  The variable \texttt{b\_eq} can be
used as a proof in the body of each \texttt{case}-clause that the
scrutinee is equal to the pattern.  For indeed, when this code is run,
if we enter the body of the clause for \texttt{ff}, say, that can only
be because \texttt{b} is, in fact, \texttt{ff}.  So for the first
of our three subproofs, let us determine what formula it proves.
Our assumption variable \texttt{b\_eq} proves

\begin{verbatim}
{ b = ff }
\end{verbatim}

\noindent and we are applying \texttt{cong} to this proof.  So the
first subproof (i.e., ``\texttt{cong (not (not *)) b\_eq}'') proves

\begin{verbatim}
{ (not (not b)) = (not (not ff)) }
\end{verbatim}

\noindent The second subproof is a \texttt{join}-proof, proving

\begin{verbatim}
{ (not (not ff)) = ff }
\end{verbatim}

\noindent Finally, the third subproof is \texttt{symm b\_eq}.  We
know \texttt{symm P} just switches the left and right hand side
of the equation proved by \texttt{P}.  So here, our \texttt{symm}-proof
proves

\begin{verbatim}
{ ff = b }
\end{verbatim}

\noindent We can see that putting these three steps together with transitivity
corresponds to the three informal equational reasoning steps we saw above:

\begin{verbatim}
(not (not b)) = (not (not ff)) = ff = b
\end{verbatim}

\noindent This does indeed prove \texttt{\{ (not (not b)) = b \}}, as
required, and completes the proof in the \texttt{ff}
\texttt{case}-clause.  The proof in the \texttt{tt}
\texttt{case}-clause is similar, except that there, our assumption
variable \texttt{b\_eq} proves

\begin{verbatim}
{ b = tt }
\end{verbatim}

\noindent and the rest of the proof uses \texttt{tt} instead of \texttt{ff}
appropriately.

\section{Summary}

The forms of proof we have seen in this chapter are:

\begin{itemize}

\item proof by evaluation and proof by partial evaluation, both
written in \guru using the syntax \texttt{join t1 t2}, which tries to
prove \texttt{\{ t1 = t2 \}} by evaluating the two terms to a common
normal form.  A normal form is an expression which cannot evaluate
further, either because it is a value like three or because evaluation
is stuck trying to pattern match on a variable (during partial
evaluation).

\item \texttt{foralli}-proofs and instantiation proofs, the latter
written like term applications except with square brackets instead
of parentheses.  These are for proving a \texttt{Forall}-formula,
and for substituting a value for the quantified variable in a proven
\texttt{Forall}-formula, respectively.

\item equivalence reasoning and congruence reasoning, using
\texttt{refl}, \texttt{symm}, \texttt{trans}, and \texttt{cong}.

\item \texttt{case}-proofs for reasoning by cases on the form
of a piece of inductive data.

\end{itemize}

\section{Exercises}

\begin{enumerate}

\item Include \texttt{guru-lang/lib/mult.g}, and prove the following
theorems by evaluation.  Here, \texttt{lt} is less-than and \texttt{le}
is less-than-or-equal on \texttt{nat}s, defined in \texttt{nat.g}:
\begin{itemize}
\item \texttt{ \{ (mult zero three) = zero \}}
\item \texttt{ \{ (lt zero three) = tt \}}
\item \texttt{ \{ (le one three) = tt \}}
\end{itemize}

\item Now prove the following, using \texttt{foralli} and \texttt{join}:
\begin{verbatim}
Forall(x:nat). { (mult Z x) = Z }
\end{verbatim}

\item Prove the following formula using \texttt{foralli} and
\texttt{join}:

\begin{verbatim}
Forall(x : nat)(y : nat) . { (lt Z (plus (S x) y)) = tt }
\end{verbatim}

\noindent Note that you can introduce multiple variables in a
\texttt{foralli}-proof in a similar way as you accept multiple inputs
in a \texttt{fun}-term.

\item The \texttt{and} function defined in \texttt{bool.g} computes
the conjunction of two \texttt{bool}s.  Prove the following theorem
about \texttt{and}:

\begin{verbatim}
Forall(x:bool). { (and ff x) = ff }
\end{verbatim}

\item Formulate and prove the theorem that \texttt{and}'ing any
boolean with itself just returns that same value.

\item Prove the following formula using \texttt{foralli} and
then a \texttt{case}-proof scrutinizing the universally quantified 
variable \texttt{x}:

\begin{verbatim}
Forall(x : nat) . { (le Z x) = tt }
\end{verbatim}

\item Consider the following datatype for buildings on The University of Iowa Pentacrest:

\begin{verbatim}
Inductive penta : type :=
  MacBride : penta
| MacLean : penta
| Schaeffer : penta
| Jessup : penta
| OldCapitol : penta.
\end{verbatim}

\begin{itemize}

\item Define a function \texttt{clockwise} that takes a \texttt{penta}
as input, and returns the next building in clockwise order (looking
down on the Pentacrest) around the perimeter.  We will consider the
Old Capitol to be clockwise from itself.

\item Similarly, define a function \texttt{counter} that returns the
next building in counter-clockwise order, again considering the Old
Capitol to be counter-clockwise from itself.

\item Formulate and prove the theorem that going clockwise and then
counter-clockwise gets you back to the same building.

\end{itemize}

\end{enumerate}

\chapter{Inductive Equational Monomorphic Proving}
\label{ch4}

In this chapter, we take our first look at proof by induction in
\guru.  We will use induction to prove equational theorems about
monomorphic functions.  In later chapters we will prove more complex
theorems about polymorphic and dependently typed functions, but
beginning with this simple setting will make induction in \guru easier
to master.  When we wish to prove properties of recursive functions --
which are, of course, the most interesting functions and the ones we
have to use to accomplish most non-trivial tasks -- we generally need
induction.  Proof by induction and definition by recursion are very
similar.  Indeed, a deeper understanding of the connection helps in
mastering induction, so we will start with that.  Then we will see
several examples of proof by induction in \guru.

\section{Preview}

The syntax for \texttt{induction}-proofs is demonstrated by this 
skeleton for induction on a \texttt{nat} \texttt{n}:

\begin{verbatim}
  induction(n:nat) return F with
    Z => P1
  | S n' => P2
  end
\end{verbatim}

\noindent This will prove \texttt{Forall(n:nat).F}, where \texttt{F}
is a formula mentioning \texttt{n}; assuming that \texttt{P1} and
\texttt{P2} are the base and step case proofs of \texttt{F}.  In each
of these (\texttt{P1} and \texttt{P2}), two special variables are
available, which the \texttt{induction}-proof automatically declares:

\begin{itemize}
\item \texttt{n\_eq}: in the body of each clause, this is an assumption that
\texttt{n} equals the pattern of the clause (\texttt{Z} or \texttt{(S n')},
respectively).
\item \texttt{n\_IH}: in the step case (\texttt{P2}), this serves as a
proof of the induction hypothesis.  It proves
\texttt{Forall(n:nat).F}, but may only be instantiated with
\texttt{n'}, the subdatum (smaller piece of data) of \texttt{n}.
\end{itemize}


\section{Induction and Terminating Recursion}
\label{ch4:indrec}

In \guru, we are allowed to define functions by \emph{general
recursion}: we can make recursive calls on any inputs we want, even if
that means the function might not terminate.  For example, we saw the
following simple example of a looping function in Chapter~\ref{ch2}:

\begin{verbatim}
fun loop(b:bool):bool. (loop b)
\end{verbatim}

\noindent This function calls itself recursively on the input it was
given.  Hence, when we call this function on an argument \texttt{b},
it will loop forever, as it tries again and again to evaluate
the term \texttt{(loop b)}.

If we want to define a function that terminates on all inputs,
however, we cannot use recursion in an unrestricted manner.  A typical
simple restriction to ensure (uniform) termination is the following:

\begin{itemize}
\item The function has a single input called the \emph{parameter of
recursion}.
\item In every recursive call in the function's code, the argument
passed for the parameter of recursion is smaller than the input
parameter.  In more detail, recursive calls can only be made on the
parameter of recursion's subdata, obtained via pattern matching.
\end{itemize}

\noindent Functions that satisfy this requirement are called
\emph{structurally terminating}.  For example, the \texttt{plus}
function we saw is structurally terminating:

\begin{verbatim}
  fun plus(n m : nat) : nat.
    match n with
      Z => m
    | S n' => (S (plus n' m))
    end
\end{verbatim}

\noindent The parameter of recursion is input \texttt{n}.  In the
recursive call in the second \texttt{match}-clause, the argument given
for the parameter of recursion is \texttt{n'}. This is indeed the
subdatum of \texttt{n}, obtained by pattern-matching.  So
\texttt{plus} is structurally terminating.  Functions like this are
indeed guaranteed to terminate for all inputs (as long as any other
functions they call are also terminating), because the argument given
for the parameter of recursion cannot get smaller and smaller forever:
eventually there are no more subdata to extract.  In the case of
\texttt{nat}, for example, we eventually reach \texttt{Z}, which has
no subdata.

We will be interested later in proving termination of functions like
\texttt{plus}.  For now, though, the reason to consider structurally
terminating functions is that they are very similar to induction
proofs.  Indeed, proof by induction can be thought of as the
structurally terminating recursive construction of a proof.  For
example, for natural number induction, which the reader has probably
seen in a discrete mathematics class, our goal is to prove that some
formula $\phi(x)$ mentioning $x$ is true for all natural numbers $x$.
Proof by induction tells us that to do this, it is sufficient to
prove:

\begin{itemize}
\item $\phi(Z)$
\item $\phi(n)$ implies $\phi(S\ n)$.
\end{itemize}

\noindent The first case is called the base case, while the second is
called the inductive (or step) case.  Informally, proof by induction
is sound for the following reason.  Every natural number $x$ is
constructed by applying $S$ some finite number of times (possibly
zero) to $Z$.  To prove $\phi(x)$ for a particular such $x$, we must
merely use the second fact above $n$ times, starting with the first
fact.  For example, if we want to prove $\phi(S\ (S\ (S\ Z)))$ (that is,
$\phi(3)$), we reason like this:

\begin{itemize}
\item We have $\phi(Z)$ by the first fact above.
\item We get $\phi(S\ Z)$ from $\phi(Z)$, which we just derived, using the second fact above.
\item We get $\phi(S\ (S\ Z))$ from $\phi(S\ Z)$, which we just derived, using the second fact above.
\item We get $\phi(S\ (S\ (S\ Z)))$ from $\phi(S\ (S\ Z))$, which we just derived, using the second fact above.
\end{itemize}

Another way to view what is happening with proof by induction is to
think of the step case as making a recursive call to the proof.  That
is, we are trying to prove $\phi(S\ n)$, but we are allowed to use the
assumption, usually called the \emph{induction hypothesis} (IH), that
$\phi(n)$ holds.  Here we can see the structural decrease in the
\emph{parameter of induction} from $(S\ n)$ to $n$.  This is similar to
what we saw in the case of structural termination of recursive
functions.  When we appeal to the induction hypothesis, it is like we
are making a structurally recursive call to the proof we are in the
middle of writing.  Even though this looks like circular reasoning, it
is sound for the same reason that structurally terminating functions
terminate: the argument given for the parameter of induction is
getting structurally smaller.  This cannot happen forever, so
eventually the self-referential reasoning will ``bottom out''; that
is, will terminate in a base case.

Most students who have not studied induction previously find it takes
a while to get used to.  We will continue to try to provide intuition
for why induction is sound, as we turn now to simple examples of
induction proofs in \guru.

\section{A First Example of Induction, Informally}
\label{ch4:indinf}

In Section~\ref{ch3:peval}, we proved the following formula in \guru
using partial evaluation and \texttt{foralli}:

\begin{verbatim}
Forall(m:nat). { (plus Z m) = m}
\end{verbatim}

\noindent We also saw in Section~\ref{ch3:err} that a similar proof
did not succeed in proving 

\begin{verbatim}
Forall(m:nat). { (plus m Z) = m}
\end{verbatim}

\noindent The reason is that as we have defined it, \texttt{plus}
performs a pattern-match on its first argument.  For the theorem we
succeeded in proving, the first argument is \texttt{Z}, and so partial
evaluation can evaluate the pattern-match, even though the second
argument is just a variable \texttt{m}.  For the theorem we failed to
prove, partial evaluation gets stuck trying to pattern-match on the
variable \texttt{m}, and so the proof cannot go through.

Here, we will see how to prove the second theorem by induction.  Let us
begin with a proof in English, and then see how this can be written in
\guru.  We wish to prove \texttt{Forall(m:nat).\{ (plus m Z) = m\}} by
induction on \texttt{m}.  For this, as described in Section~\ref{ch4:indrec},
it suffices to prove the following base case and step case:

\begin{itemize}
\item \texttt{\{(plus Z Z) = Z \}}
\item If \texttt{\{(plus n Z) = n \}}, then also \texttt{\{(plus (S n) Z) = (S n) \}}
\end{itemize}

\noindent The base case is easily proved by partial evaluation.  For
the step case, we first assume \texttt{\{(plus n Z) = n \}}.  This is
the induction hypothesis.  Now we must prove, under this assumption,
that \texttt{\{(plus (S n) Z) = (S n) \}}.  We can prove by partial
evaluation that

\begin{verbatim}
{ (plus (S n) Z) = (S (plus n Z)) }
\end{verbatim}

\noindent This follows because, as we noted before, \texttt{plus} is
pattern-matching on its first argument, so partial evaluation can
proceed past that pattern-match, up to the recursive call. Now using
our induction hypothesis and congruence, we can prove

\begin{verbatim}
(S (plus n Z)) = (S n)
\end{verbatim}

\noindent Chaining the two equational steps we have done with transitivity,
we conclude the desired formula:
\begin{verbatim}
{ (plus (S n) Z) = (S n) }
\end{verbatim}

\section{Example Induction in \guru}
\label{ch4:indguru}

Now let us write the above proof in \guru.  In fact, since the theorem
we are proving, while simple, turns out to be rather important, we
already have a proof of it in \texttt{guru-lang/lib/plus.g}:

\begin{verbatim}
Define plusZ : Forall(n:nat). { (plus n Z) = n } :=
  induction(n:nat) return { (plus n Z) = n } with
    Z => trans cong (plus * Z) n_eq
         trans join (plus Z Z) Z
               symm n_eq
  | S n' => trans cong (plus * Z) n_eq
            trans join (plus (S n') Z) (S (plus n' Z))
            trans cong (S *) [n_IH n']
                  symm n_eq
  end.
\end{verbatim}

\noindent Let us walk through this.  First, this is a
\texttt{Define}-command, just like ones we have already seen.  We are
defining \texttt{plusZ}, and instructing \guru to confirm that what we
are defining it to equal has the classifier listed between the colon
and the colon-equals, namely \texttt{Forall(n:nat).\{ (plus n Z) = n
\}}.  Then, after the colon-equals, comes the proof:

\begin{verbatim}
  induction(n:nat) return { (plus n Z) = n } with
    Z => trans cong (plus * Z) n_eq
         trans join (plus Z Z) Z
               symm n_eq
  | S n' => trans cong (plus * Z) n_eq
            trans join (plus (S n') Z) (S (plus n' Z))
            trans cong (S *) [n_IH n']
                  symm n_eq
  end.
\end{verbatim}

\noindent This begins with the \texttt{induction} keyword.  Next comes
the parameter of induction, with its type.  Notice that this looks
very similar to the argument list for a \texttt{fun}-term.  We will
see more complex versions of the argument list later, but this is
typical for now.  Then comes a \texttt{return}-clause, consisting of
the \texttt{return} keyword, followed by the classifier \texttt{\{
(plus n Z) = n \}}.  This classifier is the formula proved, for all
\texttt{n}, by the induction proof.  Each clause of the
\texttt{induction}-proof must prove this formula.  \guru requires a
\texttt{return}-clause here for the same reason that it requires
recursive \texttt{fun}-terms to specify their return type: it makes
bottom-up type checking easy.  Without this \texttt{return}-clause,
\guru would have to infer the induction hypothesis.  With the
\texttt{return}-clause, however, the induction hypothesis can be
easily computed.

After the \texttt{return}-clause, we have the keyword \texttt{with},
as for pattern-matching and \texttt{case}-proofs.  Then come the
\texttt{induction}-clauses, one for each constructor of the datatype,
in the order the constructors are listed in the datatype's declaring
\texttt{Inductive}-command.  Let us look at the bodies of those
\texttt{induction}-clauses.

\subsection{The base case}

The first subproof is for when \texttt{n} is zero:

\begin{verbatim}
trans cong (plus * Z) n_eq
trans join (plus Z Z) Z
      symm n_eq
\end{verbatim}

\noindent This proof consists of three subproofs, glued together with \texttt{trans}:

\begin{itemize}
\item \texttt{cong (plus * Z) n\_eq}
\item \texttt{join (plus Z Z) Z}
\item \texttt{symm n\_eq}
\end{itemize}

\noindent Remember that we are obliged to prove \texttt{\{ (plus n Z)
= n \}} in this clause (and in the clause for \texttt{S}).  Just as in
a \texttt{case}-proof (Section~\ref{ch3:case}), we get an assumption
variable \texttt{n\_eq} that we can use in each clause as a proof that
the parameter of induction (i.e., \texttt{n}) equals the pattern in
the clause.  So in the body of the clause for \texttt{Z}, we have

\begin{verbatim}
n_eq : { n = Z }
\end{verbatim}

\noindent The first step uses \texttt{n\_eq} and congruence to prove:

\begin{verbatim}
{ (plus n Z) = (plus Z Z) }
\end{verbatim}

\noindent The second step uses proof by evaluation (i.e., \texttt{join})
to prove:

\begin{verbatim}
{ (plus Z Z) = Z }
\end{verbatim}

\noindent Finally, the third step proves

\begin{verbatim}
{ Z = n }
\end{verbatim}

\noindent Chaining these steps together, we have this reasoning:

\begin{verbatim}
(plus n Z)   =   (plus Z Z)   =   Z   =   n
\end{verbatim}

\noindent Notice that this is a bit more detailed than in the informal proof above,
because we have to map from \texttt{n} to \texttt{Z} and back using \texttt{n\_eq}.

\subsection{The step case}

The second subproof of our example \texttt{induction}-proof is for when \texttt{n}
is \texttt{(S n')}:

\begin{verbatim}
trans cong (plus * Z) n_eq
trans join (plus (S n') Z) (S (plus n' Z))
trans cong (S *) [n_IH n']
      symm n_eq
\end{verbatim}

\noindent Just as in the base case, we must map from \texttt{n} to \texttt{(S n')} and back
using \texttt{n\_eq}.  That is what is happening in the first and last of the four subproofs
glued together by \texttt{trans}.  So let us look at the middle two:

\begin{itemize}
\item \texttt{join (plus (S n') Z) (S (plus n' Z))}
\item \texttt{cong (S *) [n\_IH n']}
\end{itemize}

\noindent The first is a proof by partial evaluation, corresponding to
the first step we took above in our informal proof
(Section~\ref{ch4:indinf}).  The second uses congruence and the
induction hypothesis.  The induction hypothesis is \texttt{n\_IH},
whose name is automatically derived from the name of the parameter of
induction, as for \texttt{n\_eq}.  In the \guru formalization of induction,
the induction hypothesis proves exactly the same theorem as the proof.
So in this case, we have

\begin{verbatim}
n_IH : Forall(n:nat) . { (plus n Z) = n }
\end{verbatim}

\noindent But as discussed above, the use of the induction hypothesis
is restricted.  We can only instantiate the \texttt{Forall}-quantifier
here with a strict subterm (subdatum) of the parameter of induction.
The \guru compiler will ensure that this restriction is met, and
report an error if the induction hypothesis is not instantiated
accordingly.  So in our subproof, we have \texttt{[n\_IH n']} for the
instantiation of the \texttt{Forall}-formula with \texttt{n'}.  Since
\texttt{n'} is indeed a strict subterm (from the pattern of the
\texttt{induction}-clause for \texttt{n}), this is a legal use of the
induction hypothesis.  Finally, we use \texttt{cong} similarly to the
way we used congruence in our informal proof above.

\section{A Second Example Induction Proof in Guru}

Let us look now at a second example \texttt{induction}-proof.  The
proof we will be constructing in this section can also be found as the
lemma \texttt{plusS} in \texttt{guru-lang/lib/nat.g}.  We wish to
prove the formula

\begin{verbatim}
Forall(n m : nat). { (plus n (S m)) = (S (plus n m))}
\end{verbatim}

\noindent Here we are faced with a small puzzle: we have two universally
quantified variables \texttt{n} and \texttt{m}, so which one should be
our parameter of induction?  Furthermore, whichever variable we select
for the parameter of induction, how do we handle the other variable?
The answers to these questions are relatively easy to reach for this
example, but for other more complicated ones can be trickier.  The
basic hint we should always keep in mind is:

\begin{hint}
\label{hint:indrec}
As a first idea, we should choose our parameter of induction to be a
variable which is used as the parameter of recursion (see
Section~\ref{ch4:indinf}) for one of the functions in our theorem. 
\end{hint}

\noindent Of course, this hint only applies when a function has a
(structurally decreasing) parameter of recursion.  Not all interesting
recursive functions do.  Also, this hint does not tell us exactly what
to do when there are multiple functions mentioned in the theorem,
since then we may have several different variables all used as
parameters of recursion.  Nevertheless, induction and recursion do go
hand in hand, and so a rough rule of thumb is to perform induction on
a variable which is analyzed by recursion.

To return to our second example theorem: of our two variables,
\texttt{n} and \texttt{m}, only one is used as a parameter of
recursion by a call to \texttt{plus}: this is \texttt{n}.  Our
definition of \texttt{plus} analyzes its first argument, and we pass
\texttt{n} as this argument in both recursive calls in the theorem
(i.e., \texttt{(plus n (S m))} on the left hand side of the equation,
and \texttt{(plus n m)} on the right).  So following Theorem Proving
Hint~\ref{hint:indrec}, we should try doing induction on \texttt{n}.
So we start our proof with ``\texttt{induction(n:nat).}''.  Now we
must list the \texttt{return}-clause for our \texttt{induction}-proof,
as described in our first example above.  This \texttt{return}-clause
must give the rest of the formula being proved.  So our
\texttt{induction}-proof starts with:

\begin{verbatim}
induction(n:nat) 
  return Forall(m : nat). { (plus n (S m)) = (S (plus n m))}
\end{verbatim}

\noindent The theorem we are proving, also called our \emph{goal}
formula, begins with ``\texttt{Forall(n m:nat).}'', which \guru views
as definitionally equal to ``\texttt{Forall(n
:nat). Forall(m:nat).}''.  That explains why, once we have started
proving our goal formula with ``\texttt{induction(n:nat)}'', the
\texttt{return}-clause starts with a \texttt{Forall}-quantification of
the variable \texttt{m}.

There is really no choice what to write next; we have to have clauses
for each way of constructing the \texttt{nat} \texttt{n} (after the
keyword \texttt{with}):

\begin{verbatim}
induction(n:nat) 
  return Forall(m : nat). { (plus n (S m)) = (S (plus n m))}
with
  Z => ...
| S n' => ...
end
\end{verbatim}

\noindent We are not ready yet to fill in the bodies of the clauses,
where I have written ``...'' (not \guru syntax).  A good strategy for
developing a proof like this is to put something -- anything, or
almost anything -- in for those ``...'', so that \guru can parse our
proof and start trying to classify it.  I find this is more effective
and less frustrating than writing a large proof and then trying to get
it to go through the \guru compiler all at once.  It is better to
write the proof incrementally, and get each piece of it through \guru,
since then the inevitable error messages you are dealing with are ones
concerning the proof you are just focused on writing (not one you
wrote twenty minutes ago when you started your proof).  A good
placeholder to put instead of ``...'' is \texttt{truei}.  This proves
the formula \texttt{True}.  It is indeed a proof, so the \guru parser
can parse it.  Of course, it does not prove the right theorem yet, so
we will definitely get a classification error.  But that is alright,
since we will gradually fill in more and more of the proof properly,
and eventually eliminate all those errors.  This gives rise to:

\begin{hint}
\label{hint:truei}
Write down a skeletal proof using \texttt{truei} as a placeholder
for missing subproofs, and gradually refine it to a proof that
can pass \guru's proof checker by replacing those uses of
\texttt{truei} with the correct subproof.
\end{hint}

\noindent So in this example, we could write the following
\texttt{Classify}-command:

\begin{verbatim}
Classify
induction(n:nat) 
  return Forall(m : nat). { (plus n (S m)) = (S (plus n m))}
with
  Z => truei
| S n' => truei
end.
\end{verbatim}

\noindent If we run this through \guru, as expected we will get this
classification error:

\begin{verbatim}
"/home/stump/guru-lang/doc/ch4.g", line 7, column 2: classification error.
The classifier computed for the body of a case in an induction-proof
is different from the expected one.
1. computed classifier: True
2. expected classifier: Forall(m : nat) . { (plus n (S m)) = (S (plus n m)) }
3. the case: Z

These terms are not definitionally equal (causing the error above):
1. Forall(m : nat) . { (plus n (S m)) = (S (plus n m)) }
2. True
\end{verbatim}

\noindent This exactly describes what we knew would happen: we have
put a proof of \texttt{True} in each of the clauses of our
\texttt{induction}-proof, where a proof of \texttt{Forall(m : nat)
. \{ (plus n (S m)) = (S (plus n m)) \}} was expected.  

Now, let us start refining our proof by replacing some of these
\texttt{truei}-proofs with the correct proofs for the cases.
When \texttt{n} is \texttt{Z}, we know that \texttt{(plus n m)} equals
\texttt{m}, and similarly \texttt{(plus n (S m))} equals \texttt{(S m)}.
That is because of how \texttt{plus} partially evaluates when its first
argument is \texttt{Z}.  So our proof for the \texttt{Z} case is similar
to proofs we did above.  We start it with \texttt{foralli}, to introduce
the universal variable \texttt{m}:

\begin{verbatim}
Classify
induction(n:nat) 
  return Forall(m : nat). { (plus n (S m)) = (S (plus n m))}
with
  Z => 
  foralli(m:nat).
  trans cong (plus * (S m)) n_eq
       trans join (plus Z (S m)) (S (plus Z m))
             cong (S (plus * m)) symm n_eq
| S n' => truei
end.
\end{verbatim}

\noindent When we run this proof through \guru, we get this error message:

\begin{verbatim}
"/home/stump/guru-lang/doc/ch4.g", line 25, column 2: classification error.
The classifier computed for the body of a case in an induction-proof
is different from the expected one.
1. computed classifier: True
2. expected classifier: Forall(m : nat) . { (plus n (S m)) = (S (plus n m)) }
3. the case: (S n')

These terms are not definitionally equal (causing the error above):
1. Forall(m : nat) . { (plus n (S m)) = (S (plus n m)) }
2. True
\end{verbatim}

\noindent Notice that item (3) listed in the message has changed from
our first error message.  \guru proof-checks the
\texttt{induction}-clauses in order starting with the one which is
textually first.  We have successfully gotten the proof for the
\texttt{Z} case through the proof checker, since our error message now
concerns the second case (the one for \texttt{(S n')}).

Now we are ready to tackle the \texttt{S} case.  We can expect we will
need to use our induction hypothesis, since we make a recursive call
in the \texttt{S} case for \texttt{plus}, and uses of the induction
hypothesis tend to mirror recursive calls.  Let us see informally
what our reasoning will be:

{\small
\begin{verbatim}
(plus (S n') (S m)) = (S (plus n' (S m))) = (S (S (plus n' m))) = (S (plus (S n') m))
\end{verbatim}
}

\noindent The first step is by partial evaluation.  The second step
uses the induction hypothesis to get:

\begin{verbatim}
{ (plus n' (S m)) = (S (plus n' m)) }
\end{verbatim}

\noindent The second step then uses congruence.  The third step is
again by partial evaluation.  Formalizing this reasoning in \guru, we get
the following final proof, which successfully checks:

\begin{verbatim}
Classify
induction(n:nat) 
  return Forall(m : nat). { (plus n (S m)) = (S (plus n m))}
with
  Z => 
  foralli(m:nat).
  trans cong (plus * (S m)) n_eq
       trans join (plus Z (S m)) (S (plus Z m))
             cong (S (plus * m)) symm n_eq
| S n' => 
  foralli(m : nat).
  trans cong (plus * (S m)) n_eq
  trans join (plus (S n') (S m)) (S (plus n' (S m)))
  trans cong (S *) [n_IH n' m]
  trans join (S (S (plus n' m))) (S (plus (S n') m))
        cong (S (plus * m)) symm n_eq
end.
\end{verbatim}

\noindent We have a new subproof in the \texttt{S n'} clause,
corresponding to the informal proof we just did above.  We have to map
from \texttt{n} to \texttt{(S n')} using the assumption variable
\texttt{n\_eq}, just as above.  Then we do some partial evaluation
(with \texttt{join}), then use the appropriately instantiated
induction hypothesis (that is \texttt{[n\_IH\ n' m]}), do some more
partial evaluation, and then map back from \texttt{(S n')} to
\texttt{n}.

\section{Commutativity of Addition in \guru}

As a final example, let us use the lemmas proved in the previous
two sections to prove commutativity of addition:

\begin{verbatim}
Forall(n m:nat). { (plus n m) = (plus m n) }
\end{verbatim}

\noindent The proof is in \texttt{guru-lang/lib/plus.g}, and it uses the
following lemmas, which we proved above and which are also defined in \texttt{plus.g}:

\begin{verbatim}
plusZ : Forall(n:nat). { (plus n Z) = n }
plusS : Forall(n m : nat). { (plus n (S m)) = (S (plus n m))}
\end{verbatim}

\noindent Indeed, we proved those lemmas just so we could prove commutativity of \texttt{plus}.
The informal reasoning is as follows.  We proceed by induction on \texttt{n}, and then in
each case assume arbitrary \texttt{m}.  So for the base case we must prove

\begin{verbatim}
(plus Z m) = (plus m Z)
\end{verbatim}

\noindent The left hand side partial-evaluates to \texttt{m}, while the right hand side is
equal to \texttt{m} by our \texttt{plusZ} lemma.  

For the step case, we must prove

\begin{verbatim}
(plus (S n') m) = (plus m (S n'))
\end{verbatim}

\noindent under the assumption (the induction hypothesis) that
\texttt{\{(plus n' m) = (plus m n')\}}.  Our equational reasoning is
as follows:

\begin{verbatim}
(plus (S n') m) = (S (plus n' m)) = (S (plus m n')) = (plus m (S n'))
\end{verbatim}

\noindent The first step is by partial evaluation.  The second is by
the induction hypothesis (and congruence).  The third is by our
\texttt{plusS} lemma.  That concludes our informal proof.

The proof in \guru mirrors this reasoning, although in a bit more
detailed way:

\begin{verbatim}
induction (n : nat) return Forall(m : nat).{ (plus n m) = (plus m n) } with
  Z => foralli(m : nat).
       trans cong (plus * m) n_eq
       trans join (plus Z m) m
       trans cong * symm [plusZ m]
             cong (plus m *) symm n_eq
| S n' => foralli(m : nat).
          trans cong (plus * m) n_eq
          trans join (plus (S n') m) (S (plus n' m))
          trans cong (S *)  [n_IH n' m]
          trans cong * symm [plusS m n']
                cong (plus m *) symm n_eq
end
\end{verbatim}

\noindent This is not terribly fun to read, but we can spot the uses
of the induction hypothesis \texttt{[n\_IH n' m]} in the \texttt{(S
n')} case, and the uses of \texttt{plusZ} and \texttt{plusS}.

\section{Summary}

We have seen several examples of \texttt{induction}-proofs for proving
equations about monomorphic programs like \texttt{plus}.
\texttt{Induction}-proofs are similar to structurally terminating
recursive functions: uses of the induction hypothesis are like
recursive calls, which construct the desired proof for a structurally
smaller piece of data.  We have seen also several theorem proving
hints, which can help make it easier to tackle a proof.

\section{Exercises}

As you browse through the \guru standard library, you will come across
proof methods we have not seen yet, particularly \texttt{hypjoin}.
For these exercises, you should use only the proof methods we have
seen so far in this book.

\begin{enumerate}

\item Include \texttt{guru-lang/lib/mult.g} and prove by induction on
\texttt{n}:

\begin{verbatim}
Forall(n:nat).{ (mult n Z) = Z }
\end{verbatim}

\item Including \texttt{guru-lang/lib/plus.g}, prove the following,
but do not use induction.  Just use existing theorems in \texttt{plus.g}
(in particular, \texttt{plus\_assoc} and \texttt{plus\_comm}):

\begin{verbatim}
Forall(x y z:nat). { (plus x (plus y z)) = (plus z (plus y x)) }
\end{verbatim}

\item Again including \texttt{mult.g}, prove the following by induction, first
determining which variable you should do induction on:

\begin{verbatim}
Forall(x y z :nat).{(mult (plus x y) z) = (plus (mult x z) (mult y z))}
\end{verbatim}

Hint: my proof uses the lemma \texttt{plus\_assoc} from \texttt{guru-lang/lib/plus.g}
(and that is the only lemma I need).

\item The exclusive-or function is defined as \texttt{xor} in \texttt{guru-lang/lib/bool.g}.
Prove the following (this does not need induction):

\begin{verbatim}
Forall(x y : bool). { (xor (not x) y) = (not (xor x y)) } 
\end{verbatim}

\item The \texttt{mod2} function defined in
\texttt{guru-lang/lib/pow.g} takes a \texttt{nat} \texttt{n} as input,
and returns \texttt{ff} if \texttt{n} is even, and \texttt{tt} if
\texttt{n} is odd.  In this problem, we will prove the following non-trivial
property of \texttt{mod2}:

\begin{verbatim}
Forall(n m : nat). { (mod2 (plus n m)) = (xor (mod2 n) (mod2 m)) }
\end{verbatim}

\noindent An intuitive way to view this theorem is as saying how the
parity of numbers is combined when the numbers are added.  When we add
an even number and an even number we get another even number; when we
add odd and even we get odd; and when we add odd and odd we get even.
With \texttt{ff} for even and \texttt{tt} for odd, we see that this
description corresponds to exclusive-or: \texttt{ff} (even) and
\texttt{ff} (even) gives \texttt{ff} (even); \texttt{ff} (even) and
\texttt{tt} (odd) gives \texttt{tt} (odd); and \texttt{tt} (odd) and
\texttt{tt} (odd) gives \texttt{ff} (even).  This is, of course, a fact
about addition of numbers.

\ 

To prove this theorem, first identify which variable you should
most likely do induction on.  During the course of the proof, I found
I needed to use the lemma proved in the previous problem.

\end{enumerate}

\chapter{Logical Monomorphic Proving}
\label{ch5}

The last two chapters focused on equational proofs about monomorphic
programs.  That is, we were just trying to prove universally
quantified equations, like \texttt{Forall(x y:nat).\{(plus x y) =
(plus y x)\}}.  Of course, there are other kinds of logical statements
we would like to make.  For one simple example, we might like to prove
that if \texttt{x} plus \texttt{y} equals zero, then \texttt{x} must
be zero, for \texttt{x} and \texttt{y} of type \texttt{nat} (of
course, \texttt{y} must also be zero in this case).  An ``if-then''
statement is called an \emph{implication}.  In \guru, implications are
written with \texttt{Forall}, which turns out to make notation a bit
more concise.  So the statement would be written this way in \guru:

\begin{verbatim}
Forall(x y:nat)(u : { (plus x y) = Z }). { x = Z }
\end{verbatim}

\noindent We need some other proof constructs to reason in the
presence of implications.  These will be introduced in this chapter.
We will also see \emph{conjunctions}, for ``and'' statements; and
existential formulas, for saying that something exists with a certain
property.  As usual, we will try these out with several examples.

\section{Preview}

In this chapter we will see these additional kinds of formulas:

\begin{itemize}

\item Implications, which say that \texttt{F1} implies \texttt{F2},
are written as \texttt{Forall(u:F1).F2}.  This can be thought of as
saying that for any proof \texttt{u} of \texttt{F1}, \texttt{F2} is
true.

\item \texttt{Exists}-formulas, like \texttt{Exists(y:nat). \{ (plus y
(S Z)) = Z \}}.  This one states that there is a \texttt{nat}
\texttt{y} such that \texttt{y} plus one (that is, ``\texttt{(S Z)}'')
equals zero.  This is not provable in \guru, because for natural
numbers, there is no number we can add to one to get zero.  Of course,
if we had negative numbers, we could prove this.  But we are making a
statement about \texttt{nat}s \texttt{y}, not integers \texttt{y}.

\begin{comment}
\item Conjunctions, which assert that \texttt{F1} and \texttt{F2} are
both true, are written as \texttt{Exists(u:F1).F2}. This can be
thought of as saying that there exists a proof \texttt{u} of
\texttt{F1} such that \texttt{F2} is true.
\end{comment}

\end{itemize}


\noindent The forms of proof covered in this chapter are:

\begin{itemize}
\item Implication-introduction and elimination are done using
\texttt{Forall}-introduction and elimination.

\item \texttt{existsi t F* P}, where \texttt{t} is a term, \texttt{F*}
is a formula context, and \texttt{P} is a proof.  This is to prove the
formula \texttt{Exists(x:nat).F*[x]}.  The situation is that we have a
term \texttt{t} and a proof \texttt{P} that that term has a certain
property.  The property is described using a formula context, which is
a formula containing the special symbol $*$.  A shorthand for proving
a conjunction (written as an \texttt{Exists}-formula) is \texttt{andi P1 P2}.

\item \texttt{existse P1 P2}.  If \texttt{P1} is a proof of
the formula \texttt{Exists(x:nat).F}, and if \texttt{P2} is a proof of the formula
\texttt{Forall(x:nat)(u:F).F2} for some \texttt{F2} not mentioning
\texttt{x}, then the \texttt{existse}-proof also proves \texttt{F2}.

\item \texttt{clash t1 t2}.  If t1 and t2 are values built with
different constructors, like \texttt{(S x)} and \texttt{Z}, this
proves the disequation \texttt{\{ t1 != t2 \}}.  We will also see how
to use \texttt{symm} and \texttt{trans} with disequations.

\item \texttt{contra P F}.  If \texttt{P} proves \texttt{\{ t != t
\}}, then this proof proves \texttt{F}.  It is used to prove any
formula \texttt{F} you happen to need in your proof, if you have
derived a contradictory statement (i.e., \texttt{\{ t != t \}}).

\end{itemize}

\section{Reasoning with Implication}

An \emph{implication} is an if-then formula.  It says if formula
\texttt{F1} is true, then so is \texttt{F2}.  An example is, ``x is
zero, then x plus x equals zero.''  In \guru, implications are written
using \texttt{Forall}.  The example implication just mentioned is written

\begin{verbatim}
Forall(u : { x = Z }). { (plus x x) = Z}
\end{verbatim}

\noindent You can think of this as saying, for all proofs \texttt{u} of
\texttt{\{ x = Z \}}, we have \texttt{\{(plus x x) = Z\}}.  Using
\texttt{Forall} for implications makes formulas a little more concise
than they might otherwise be.  For example, we can write:

\begin{verbatim}
Forall(x:nat)(u : { x = Z }). { (plus x x) = Z}
\end{verbatim}

\noindent This quantifies over \texttt{x} of type \texttt{nat}, and
then continues with the example implication.  This idea of combining
implication and universal quantification comes from other languages,
for example \textsc{Coq}~\cite{coq}.

We reason with implications in exactly the same way as universal
quantifications.  To prove an implication, we use \texttt{foralli}.
For example, here is the proof of our example formula:

\begin{verbatim}
Define plusZ' :=
foralli(x:nat)(u : { x = Z }). 
  trans cong (plus * *) u
        join (plus Z Z) Z.
\end{verbatim}

\noindent Here, \texttt{u} is an arbitrary proof of \texttt{\{x =
Z\}}.  So \texttt{u} acts as an assumption that \texttt{\{x = Z\}}.
We use this assumption to transform \texttt{x} into \texttt{Z} in
\texttt{(plus x x)}.  This is done by the \texttt{cong}-proof.  Then
we can join \texttt{(plus Z Z)} with \texttt{Z}.

To use an implication, we instantiate it using the square brackets
notation.  This makes for a rather convenient notation for
instantiating theorems.  For example, to use this \texttt{plusZ'}
theorem we have just proved, we can write:

\begin{verbatim}
[plusZ' Z refl Z]
\end{verbatim}

\noindent Here, we are instiating \texttt{x} in the theorem with
\texttt{Z} (the first argument), and \texttt{u} with \texttt{refl Z}
(the second argument.

\section{Existential Introduction}

An existential formula is one that states that there is a value
\texttt{x} of some type \texttt{T} which satisfies a stated property.
Here is an example:

\begin{verbatim}
Forall(x:nat). Exists(y:nat). { (le x y) = (le y x) }
\end{verbatim}

\noindent In English, this formula says, ``for all \texttt{x} of type
\texttt{nat}, there exists a \texttt{y} of type \texttt{nat} such that
the (boolean) value returned by \texttt{(le x y)} is equal to that
returned by \texttt{(le y x)}.''  In other words, for every
\texttt{nat} \texttt{x}, there is a \texttt{nat} \texttt{y} such that
\texttt{x} is less than \texttt{y} if and only if \texttt{y} is less
than \texttt{x}.  The only number with this property, in fact, is
\texttt{x} itself.  This uses the \texttt{le} function for
less-than-or-equal-to on the unary natural numbers, which is defined
in \texttt{guru-lang/lib/nat.g}.

To prove an existential, we must specify a value that has the
property.  That value is called the \emph{witness} of the existential.
So in this case, we will specify \texttt{x} as the witness, since
\texttt{\{(le x x) = (le x x)\}}.  Notice that this last formula
has four occurrences of \texttt{x} in it.  Two of these we wish
to view as occurrences of our witness, and two are part of the
property.  This is indicated by using a \emph{formula context},
which is a formula with a $*$ in it: 

\begin{verbatim}
{ (le x *) = (le * x) }
\end{verbatim}

\noindent To prove our existential, we will use an
\texttt{existsi}-proof, to introduce the existential.  The syntax for
an \texttt{existsi}-proof is \texttt{existsi t F* P}, where \texttt{t}
is the witness, \texttt{F*} is the formula context corresponding to
the property the witness is supposed to have, and \texttt{P} is a
proof that \texttt{t} has that property.  In particular, \texttt{P} is
a proof of the formula \texttt{F*[t]}, which is our notation (not
\guru's) for the formula you get if you substitute the witness
\texttt{t} for the $*$ in \texttt{F*}.  Note that it is required that
the witness term \texttt{t} be a value.  So here, we will write:

\begin{verbatim}
existsi x { (le x *) = (le * x) } P
\end{verbatim}

\noindent where \texttt{P} is a proof of

\begin{verbatim}
{ (le x x) = (le x x) }
\end{verbatim}

\noindent The complete proof in \guru is:

\begin{verbatim}
Define ltcomm : Forall(x:nat).Exists(y:nat). { (le x y) = (le y x) } :=
  foralli(x:nat).
    existsi x { (le x *) = (le * x) } refl (le x x).
\end{verbatim}

\noindent We start off with \texttt{foralli}, to introduce the
variable \texttt{x} for an arbitrary \texttt{nat}.  Then comes our
\texttt{existsi}-proof.  We can just use \texttt{refl (le x x)} as the
proof \texttt{P} of \texttt{\{(le x x) = (le x x)\}} mentioned above.
You can see the importance of the formula context in
\texttt{existsi}-proofs by considering this modification of the proof:

\begin{verbatim}
foralli(x:nat).
  existsi x { (le x *) = (le * *) } refl (le x x)
\end{verbatim}

\noindent The only change is that we are using a different formula
context, one with three $*$s instead of two.  The formula proved by
this proof is

\begin{verbatim}
Forall(x:nat).Exists(y:nat). { (le x y) = (le y y) }
\end{verbatim}

\noindent This says something quite different from the formula proved
above.

\subsection{Another example}
\label{ch5:existsi2}

Let us prove this formula:

\begin{verbatim}
Forall(x:nat). Exists(y:nat). { (le x y) = tt}
\end{verbatim}

\noindent In English, this formula says, ``for all \texttt{x} of type
\texttt{nat}, there exists a \texttt{y} of type \texttt{nat} such that
\texttt{x} is less than or equal to \texttt{y}.''  To prove this
formula, we must just show how to find, for every \texttt{nat}
\texttt{x}, a \texttt{nat} \texttt{y} such that \texttt{x} is less
than or equal to y \texttt{y}.  Of course, for any \texttt{x}, there
are an infinite number of numbers that would serve for such a
\texttt{y}: all the numbers greater than or equal to \texttt{x}.  We
must just pick one of them to serve as the witness of the existential
quantification (i.e., the value that has the desired property).  We
will pick \texttt{x} as the witness, since there is a theorem
\texttt{x\_le\_x} defined in \texttt{guru-lang/lib/nat.g} which
proves:

\begin{verbatim}
Forall(a:nat).{ (le a a) = tt}
\end{verbatim}

In \guru, our proof looks like this:

\begin{verbatim}
Define existsle : Forall(x:nat).Exists(y:nat). {(le x y) = tt } :=
  foralli(x:nat). existsi x { (le x *) = tt } [x_le_x x].
\end{verbatim}

\noindent We are proving the theorem, which we call \texttt{existsle},
by first introducing the variable \texttt{x} for an arbitrary
\texttt{nat} using \texttt{foralli}.  Then we have our
\texttt{existsi}-proof, with the witness \texttt{x}, the formula
context \texttt{\{(le x *) = tt\}}, and the proof \texttt{[x\_le\_x x]},
which instantiates the \texttt{x\_le\_x} theorem with \texttt{x} to
conclude \texttt{\{(le x x) = tt \}}.

\section{Existential Elimination}
\label{ch5:existse}

If we have a proof of an \texttt{Exists}-formula, stating that there
is a value which has a certain property, we can make use of that proof
as follows.  We may introduce a new variable \texttt{x} for the value
that is stated to exists.  We may also assume that this \texttt{x} has
the stated property.  In \guru, this is done using an
\texttt{existse}-proof.  The syntax is unfortunately a little
cumbersome, although this is a problem with how existential
elimination has been done in logic for around 80 years.  We write
\texttt{existse P1 P2}, where for any type \texttt{T}:

\begin{itemize}
\item \texttt{P1} proves \texttt{Exists(x:T).F}.
\item \texttt{P2} proves \texttt{Forall(x:T)(u:F).F'}, where
\texttt{x} may not be mentioned by the formula \texttt{F'}.
\end{itemize}

\noindent The role of \texttt{P1} is clear enough: this is our proof
of the existential.  The role of \texttt{P2} is a bit more puzzling.
It proves some other formula \texttt{F'}, but the proof is allowed to
make use of arbitrary \texttt{x} of type \texttt{T}, and an assumption
\texttt{u} that \texttt{x} has property \texttt{F}.  This corresponds
to the informal intuition above: we introduce a variable \texttt{x}
for the value that is stated to exist, along with an assumption that
\texttt{x} has the stated property.  The formula proven (\texttt{F'})
is not allowed to mention \texttt{x}, because the entire
\texttt{existse}-proof then proves \texttt{F'} (and if \texttt{F'}
mentioned \texttt{x}, that \texttt{x} would be used outside its scope,
which is the \texttt{Forall}-formula).

Here is a simple example of existential elimination.  In
Section~\ref{ch5:existsi2} just above, we proved: 

\begin{verbatim}
Forall(x:nat). Exists(y:nat). { (le x y) = tt}
\end{verbatim}

\noindent So for any value \texttt{x} of type \texttt{nat}, there is a
value \texttt{y} of type \texttt{nat} such that \texttt{x} is less
than or equal to \texttt{y}.  Let us introduce variable \texttt{y} for
this value, and assume that \texttt{\{(le x y) = tt\}}.  Since
\texttt{y} is less than \texttt{(S y)}, we can conclude that
\texttt{(lt x (S y))}.  Taking \texttt{(S y)} as our witness, we may
conclude that there exists a \texttt{z} such that \texttt{(lt x z)}.
This informal argument proves, in a somewhat roundabout way:

\begin{verbatim}
Forall(x:nat). Exists(z:nat). { (lt x z) = tt}
\end{verbatim}

\noindent We may write this proof in \guru, making use of several lemmas
from \texttt{guru-lang/lib/nat.g}:

\begin{verbatim}
lt_S : Forall(a:nat).{ (lt a (S a)) = tt}

lelt_trans : Forall(a b c:nat)(u:{ (le a b) = tt })(v:{ (lt b c) = tt }).
               { (lt a c) = tt }
\end{verbatim}

\noindent The first lemma says \texttt{a} is less than \texttt{(S a)}.  The second says that if

\begin{enumerate}
\item $\texttt{a} \le \texttt{b}$, and
\item $\texttt{b} < \texttt{c}$,
\end{enumerate}

\noindent then $\texttt{a} < \texttt{c}$.  So this is a form of
transitivity combining less-than-or-equals and less-then.  The proof
is then the following (the line numbers are not valid \guru syntax):

\begin{verbatim}
0. Define existslt : Forall(x:nat). Exists(z:nat). {(lt x z) = tt } :=
1.   foralli(x:nat).
2.   existse [existsle x]
3.     foralli(y:nat)(u:{(le x y) = tt}).
4.         existsi (S y) { (lt x *) = tt }
5.           [lelt_trans x y (S y) u [lt_S y]].
\end{verbatim}

\noindent Let us walk through this line by line.

\begin{enumerate}
\item Introduce our arbitrary \texttt{x} of type \texttt{nat}.
\item Use existential elimination.  The proof \texttt{[existsle x]} is
our instantiation of the previously proved theorem.  It proves
\texttt{Exists(y:nat).\{(le x y) = tt\}}.  This is the first proof that
\texttt{existse} requires, namely, the proof that something exists which
has a certain property.
\item The second proof \texttt{existse} requires begins here and
stretches for the rest of the proof.  This proof begins by assuming
arbitrary \texttt{y} of type \texttt{nat}, along with an assumption
\texttt{u} that \texttt{\{(le x y) = tt\}}.
\item Now we use \texttt{existsi} to prove the formula
\texttt{Exists(z:nat).\{(lt x z) = tt\}}.  There is no mention of the
variable \texttt{z} in the proof itself.  In fact, by default \guru
names the variable \texttt{x}, keeping track of the fact that this
\texttt{x} is different from other variables in scope which might have
the same name.
\item Here we instantiate \texttt{lelt\_trans}.  We provide five arguments
corresponding to the five inputs of \texttt{lelt\_trans}:
\begin{itemize}
\item \texttt{x} for \texttt{a:nat}
\item \texttt{y} for \texttt{b:nat}
\item \texttt{(S y)} for \texttt{c:nat}
\item \texttt{u} for \texttt{u:\{ (le a b) = tt \}}
\item \texttt{[lt\_S y]} for \texttt{v:\{ (lt b c) = tt \}}
\end{itemize}

\noindent The \texttt{lelt\_trans}-proof then proves the desired \texttt{\{(lt x (S y)) = tt\}}.
\end{enumerate}

\section{Proving a Function Terminates}

One of the most basic properties one might want to prove about a
recursively defined function is that it terminates for all inputs.
When the function is structurally terminating (see
Section~\ref{ch4:indrec}), this can be easily done by induction.  To
do this, we must first formalize the statement that the function
terminates.  In \guru, this is done by stating that for all inputs to
the function, there exists an output of the function on those inputs.
For example, here is the formalized statement that \texttt{plus}
terminates on all inputs:

\begin{verbatim}
Forall(x y : nat). Exists(z:nat).{(plus x y) = z}
\end{verbatim}

\noindent Quantifiers in \guru range over values of the given types.
So this says that for all values \texttt{x} and \texttt{y} of type
\texttt{nat}, there exists a value \texttt{z} such that \texttt{(plus
x y)} equals \texttt{z}.  As stated earlier, if an equality between
terms is provable in \guru, it implies that the two terms either both
diverge (run forever) or both converge to a common value.  Since the
variable \texttt{z} ranges over values, this implies that
\texttt{(plus x y)} converges to \texttt{z} (since \texttt{z}
evaluates just to itself).

The proof in \texttt{guru-lang/lib/plus.g} that \texttt{plus} is total
is called \texttt{plus\_total}:

\begin{verbatim}
induction (x : nat) return Forall(y:nat). Exists(z:nat).{(plus x y) = z} with
  Z => foralli(y:nat).
       existsi y {(plus x y) = *}
       trans cong (plus * y) x_eq
             join (plus Z y) y
| S x' => foralli(y:nat).
          existse [x_IH x' y] foralli(z':nat)(u:{(plus x' y) = z'}). 
          existsi (S z') {(plus x y) = *}  
            trans cong (plus * y) x_eq
            trans join (plus (S x') y) (S (plus x' y))
                  cong (S *) u
	end. 
\end{verbatim}

\noindent We will not walk through this in all detail, but focus just
on the clause for \texttt{(S x')}.  Here, we use an instantiation of
the induction hypothesis, \texttt{[x\_IH x' y]}, to prove:

\begin{verbatim}
Exists(z:nat). {(plus x' y) = z}
\end{verbatim}

\noindent The \texttt{existse}-proof's second subproof, which begins
\texttt{foralli(z':nat)}, picks up from this existential formula.  It
introduces a variable \texttt{z'} for the value \texttt{z} such that
\texttt{\{(plus x' y) = z\}}.  It is fine to use a different name
(here \texttt{z'}) for the variable introduced by \texttt{foralli}
than for the variable mentioned by the \texttt{Exists}-formula (here
\texttt{z}).  The rest of the clause is:

\begin{verbatim}
existsi (S z') {(plus x y) = *}  
trans cong (plus * y) x_eq
trans join (plus (S x') y) (S (plus x' y))
      cong (S *) u
\end{verbatim}

\noindent The reasoning here is as follows.  If \texttt{\{(plus x' y)
= z'\}}, then \texttt{(plus (S x') y)} can be shown to be equal to
\texttt{(S z')}; and so \texttt{\{(plus x y) = (S z')\}}.  This
reasoning is done by the last three lines of the subproof.  So we will
take \texttt{(S z')} as our witness for the existential statement that
there exists \texttt{z} such that \texttt{\{(plus x y) = z\}}.  That is
why the \texttt{existsi}-proof begins with \texttt{(S z')}: that is
the witness.

\subsection{Registering a function as total}
\label{ch5:regtotal}

When a function has been proved total in the sense just discussed, we
can register it as total with \guru, using a \texttt{Total}-command.
For example, in \texttt{guru-lang/lib/plus.g}, this command is used
to register \texttt{plus} as total, where \texttt{plus\_total} is
defined to be the proof discussed in the previous section:

\begin{verbatim}
Total plus plus_total.
\end{verbatim}

\noindent The first expression is a symbol defined to be a function,
and the second is a proof that for all inputs that may be given to the
function, there exists an output produced by the function on those
inputs.  Why is it useful to register functions as total?  Because of
an important restriction on \texttt{Forall}-elimination and
\texttt{Exists}-introduction which we have glossed over up to now.
When instantiating a \texttt{Forall}-formula, the argument given must
be a terminating term.  Similarly, the witness used to prove an
\texttt{Exists}-formula must also be a terminating term.  The reason
is simple.  As remarked above, quantifiers in \guru range over values.
So when we have a proof of a formula like
\texttt{Forall(x:nat).\{(plus x Z) = x\}}, that \texttt{x} ranges over
values.  So it is not legal to instantiate it with a term which might
not terminate in a value; i.e., a non-terminating term.  Similarly,
since existential quantifications range over values, it is not legal
to offer as a witness a term which might fail to terminate.  For this
reason, proving termination of functions is quite important in \guru.
When a function has been registered as total, it may then be used in
terms which will instantiate universal quantifiers or witness
existential ones.  If we try to instantiate a quantifier with a term
including a function that has not been registered as total, \guru will 
report an error.  For example, suppose we run the following:

\begin{verbatim}
Include "../guru-lang/lib/plus.g".

Define loop := fun f(x:nat):nat.(f x).

Classify [plusZ (loop Z)].
\end{verbatim}

\noindent \guru will report:

\begin{verbatim}
Forall(x : nat)(u : { x = Z }) . { (plus x x) = Z }
"/home/stump/guru-lang/doc/test.g", line 37, column 17: classification error.
Checking termination, the head of an application is neither
declared total nor a term constructor.
1. the application in spine form: (loop Z)
2. the head: loop
\end{verbatim}

\noindent We have defined \texttt{loop} as a looping function (since
it just takes in \texttt{x} and immediately makes a recursive call on
\texttt{x}).  The \guru proof checker then reports an error when we
attempt to instantiate the universal formula proved by \texttt{plusZ}
with \texttt{(loop Z)}, since that term is not known to be terminating
(in fact, it is non-terminating).

\subsection{Aside: \texttt{show}-proofs}

Sometimes while we are incrementally developing a proof, it is useful
to see exactly what formula some subproof proves.  There is a way to
do that in \guru.  You simply use a \texttt{show}-proof.  The syntax
is:

\begin{verbatim}
show P1 ... Pn end
\end{verbatim}

\noindent where \texttt{P1} through \texttt{Pn} are proofs.  \guru will compute
the classifiers for those proofs and print them.  It will then stop any other
classification, as if we had a classification error.  For example, to see
the equational steps in the \texttt{S}-clause of the proof from the
previous section that \texttt{plus} is a total function, we can use \texttt{show}:

\begin{verbatim}
induction (x : nat) return Forall(y:nat). Exists(z:nat).{(plus x y) = z} with
  Z => foralli(y:nat).
       existsi y {(plus x y) = *}
       trans cong (plus * y) x_eq
             join (plus Z y) y
| S x' => foralli(y:nat).
          existse [x_IH x' y] foralli(z':nat)(u:{(plus x' y) = z'}). 
          existsi (S z') {(plus x y) = *}  
            show
              trans cong (plus * y) x_eq
              trans join (plus (S x') y) (S (plus x' y))
                    cong (S *) u
            end
	end. 
\end{verbatim}

\noindent \guru will then print:

\begin{verbatim}
"/home/stump/guru-lang/doc/test.g", line 14, column 20: classification error.
We have the following classifications:

1. (plus x y) =

2. (plus (S x') y) =

3. (S (plus x' y)) =

4. (S z')
\end{verbatim}

\noindent \guru lists this as an error, but of course, it is really
just informational. We see the four equational steps going into the
\texttt{trans}-proof that is being displayed with \texttt{show}.
\guru prints \texttt{trans}-proofs specially with \texttt{show}, by
printing what is proved by its subproofs.  For any other kind of
proof, \guru will print just the formula proved by the entire proof.

\section{Reasoning with Disequations}

For some theorems, particularly implications, we need disequational
reasoning: that is, we need to use disequalities between terms, which
state that the terms do not either converge to different values (this
is the case we are interested in) or do not both diverge (I have never
had a case like this of interest).  Here is a simple example.  We would
like to prove the following formula:

\begin{verbatim}
Forall(x:nat)(u:{(le x Z) = tt}). {x = Z}
\end{verbatim}

\noindent This says that for all \texttt{x} of type \texttt{nat}, if
\texttt{x} is less than or equal to zero, then \texttt{x} must equal
zero.  We certainly believe this to be true (for natural numbers), but
how is it proved?  Let us assume an arbitrary \texttt{x} of type
\texttt{nat}, and let us assume that \texttt{x} is less than or equal
to \texttt{Z}.  Now let us do a case split on \texttt{x}.  If
\texttt{x} is zero, then we are done, since that is what we are
supposed to prove.  If \texttt{x} is \texttt{(S x')} for some
\texttt{x'}, then our assumption that \texttt{x} is less than or equal
to zero is contradicted.  If we evaluate \texttt{(le (S x') Z)}, we
will get \texttt{ff}.  But our assumption says that \texttt{(le (S x')
Z)} evaluates to \texttt{tt}.  And \texttt{tt} is disequal to
\texttt{ff}.  So we reach a contradiction, because we have:

\begin{verbatim}
tt   =   (le (S x') Z)   =    ff 
\end{verbatim}

\noindent and also \texttt{\{ tt != ff \}}.  From a contradiction we
can conclude anything, since false implies anything.  So in particular
we can conclude \texttt{\{ x = Z \}}.

The two parts of reasoning used in this informal proof which we have
not seen formalized in \guru are the use of the contradiction to prove
any formula, and the proof of the disequation \texttt{\{ff != tt\}}.  

\begin{itemize}

\item To prove a disequation like \texttt{\{ff != tt\}}, the syntax in \guru is

\begin{verbatim}
clash ff tt
\end{verbatim}

\noindent A \texttt{clash}-proof takes any two values built with
different constructors, and proves that they are disequal.  So another
example is \texttt{clash Z (S Z)}, which proves \texttt{\{ Z != (S
Z)\}}.  

\item To derive a formula from a contradiction in \guru, we use a
\texttt{contra}-proof.  The syntax is \texttt{contra P F}, where
\texttt{P} proves that \texttt{\{ t != t \}} for some term \texttt{t}.
The \texttt{contra}-proof then proves \texttt{F}, which may be any
formula we want.

\end{itemize}

\noindent Before we can formalize our proof of \texttt{Forall(x:nat)(u:\{(le x
Z) = tt\}).\{x = Z\}} in \guru, we need one more ingredient, which is
how to do equational reasoning for disequations.  It works quite easily.
The proof rules \texttt{symm} and \texttt{trans} work also with
proofs of disequations.  If 

\begin{verbatim}
P  :  { t1 != t2 }
\end{verbatim}

\noindent then we have:

\begin{verbatim}
symm P  :  { t2 != t1 }
\end{verbatim}

\noindent And if we have 

\begin{verbatim}
P1  :  { t1 = t2 }
P2  :  { t2 != t3 }
\end{verbatim}

\noindent then we also have:

\begin{verbatim}
trans P1 P2 : { t1 != t3 }
\end{verbatim}

\noindent So with \texttt{trans}, the first subproof must prove an
equation, but the second one can prove an equation or a disequation.
Notice that we cannot conclude anything about the relationship between
\texttt{t1} and \texttt{t3} if we have two disequations \texttt{\{ t1
!= t2\}} and \texttt{\{t2 != t3\}}.  That is why \texttt{trans}
requires the first proof to prove an equation.  Now we have the tools
we need to formalize our informal reasoning above in \guru:

\begin{verbatim}
Define le_Z1 : Forall(x:nat)(u:{(le x Z) = tt}). {x = Z} :=
  foralli(x:nat)(u:{(le x Z) = tt}).
  case x with
    Z => x_eq
  | S x' => 
    contra 
      trans symm u
      trans cong (le * Z) x_eq
      trans join (le (S x') Z) ff
            clash ff tt
    { x = Z }
  end.
\end{verbatim}

\noindent We start off by assuming arbitrary \texttt{x} of type
\texttt{nat} such that \texttt{\{(le x Z) = tt\}}, using
\texttt{foralli}.  Now we case split on \texttt{x}, just as in our
informal proof.  The base case is really easy, since \texttt{x\_eq} is
a proof that \texttt{\{x = Z\}}, and that is what we are supposed to
prove.  For the step case, we have the following equational steps,
which you can see by putting a \texttt{show} around the first
argument to \texttt{contra} (i.e., from ``\texttt{trans symm u}'' to the
end of the \texttt{clash}-proof):

\begin{verbatim}
1. tt =

2. (le x Z) =

3. (le (S x') Z) =

4. ff !=

5. tt
\end{verbatim}

\noindent This chain of steps proves \texttt{\{tt != tt\}}, which is
just the kind of contradictory equation that \texttt{contra} requires
for its subproof.  Then we give \texttt{contra} the formula
\texttt{\{x = Z\}}, since that is what we wish to derive from our
contradiction.

\section{Case Splitting on Terminating Terms}
\label{ch5:case}

For \texttt{case}-proofs (Section~\ref{ch3:case}), the expression we
are case splitting on must be a terminating term, like the
instantiating and witnessing terms discussed in
Section~\ref{ch5:regtotal}.  If the term is something other than just
a symbol, we need to use a feature of \texttt{case}-proofs we have not
seen up until now, which is a \texttt{by}-clause.  Suppose we are
trying to prove the following:

\begin{verbatim}
Forall(x y:nat). {(eqnat x y) = (eqnat y x)}
\end{verbatim}

\noindent Here, \texttt{eqnat} is a function testing whether or not
\texttt{nat}s \texttt{x} and \texttt{y} are equal.  We could prove
this theorem by induction on \texttt{x}, but there is actually an
easier proof using the following theorems in \texttt{nat.g}:

\begin{verbatim}
eqnatEq : Forall(n m:nat)(u:{(eqnat n m) = tt}). { n = m }

eqnatNeq : Forall(n m:nat)(u:{(eqnat n m) = ff}). { n != m } 

neqEqnat : Forall(n m : nat)(u:{n != m}).{ (eqnat n m) = ff } 
\end{verbatim}

\noindent The idea of this easier proof is to case split on
\texttt{(eqnat x y)}.  This is allowed since \texttt{eqnat} is
registered as a total function in \texttt{nat.g}.  In the case where
\texttt{(eqnat x y)} is \texttt{tt}, we can use the theorem
\texttt{eqnatEq} to conclude that \texttt{\{x = y\}}.  Using that
fact, we can easily transform \texttt{(eqnat y x)} into \texttt{(eqnat
x y)}.  In the case where \texttt{(eqnat x y)} is \texttt{ff}, we can
use \texttt{eqnatNeq} to conclude that \texttt{\{x != y\}}.  From this
we obtain \texttt{\{y != x\}} by symmetry, and from there, we get
\texttt{\{(eqnat y x) = ff\}} by \texttt{neqEqnat}.

Here is the formalization of this proof in \guru, which I added to
\texttt{nat.g} while writing this section.  The new feature is the
\texttt{by}-clause at the very start of the \texttt{case}-proof, which
we will explain just below.

\begin{verbatim}
Define eqnat_symm : Forall(x y:nat). { (eqnat x y) = (eqnat y x) } :=
  foralli(x y:nat).
  case (eqnat x y) by u ign with
    ff => trans u
                symm [neqEqnat y x symm [eqnatNeq x y u]]
  | tt => trans cong (eqnat * y) [eqnatEq x y u]
                cong (eqnat y *) symm [eqnatEq x y u]
  end.                
\end{verbatim}

\noindent Our \texttt{case}-proof begins with ``\texttt{case (eqnat x
y) by u ign with}''.  We have the \texttt{case} keyword, and then the
terminating term (aka, the \emph{scrutinee}) on which we are case
splitting.  Next comes the \texttt{by}-clause ``\texttt{by u ign}'',
and then the \texttt{with} keyword.  The \texttt{by}-clause is used
when case splitting on a term which is not literally a symbol (like
\texttt{x}).  Here, we are splitting on \texttt{(eqnat x y)}, which is
not a symbol; it is an application.  \guru does not attempt to
introduce a name automatically for the assumption variable relating
the scrutinee with the pattern in each case, unless the scrutinee is a
symbol, say \texttt{x}.  In that case, we have seen that \guru
automatically introduces this assumption variable, with the name
\texttt{x\_eq}.  When splitting on a term that is not a symbol, it is
up to us to choose the name of the assumption variable.  There are
actually two such variables introduced by a \texttt{case}-proof.  The
first one is the one we need here, and I have called it \texttt{u}.
The second one, ``\texttt{ign}'' is \underline{\texttt{ign}}ored here.
We will see what it is does, when we study dependently typed
programming.

The clauses for the \texttt{case} proof are a bit dense, but they do
follow the informal reasoning mentioned above.  Let us just consider
part of the \texttt{ff}-clause.  The subproof \texttt{[eqnatNeq x y
u]} proves that \texttt{\{x != y\}}.  We use \texttt{symm} to reverse
this.  Call that proof \texttt{P}.  It proves \texttt{\{y != x\}}.
Then \texttt{[neqEqnat y x P]} proves \texttt{\{(eqnat y x) = ff\}},
as you can see if you instantiate the variables in the formula listed
above for \texttt{neqEqnat} as \texttt{[neqEqnat y x P]} is doing.


\section{Summary}

We have seen how to reason with implications, existential formulas,
and disequations.  Implications are written using \texttt{Forall}, and
then \texttt{Forall}-introduction and elimination are used for
implications.  To prove an existential, we must give to
\texttt{existsi} a witness, which is a value that has the specified
property.  The property is specified to \texttt{existsi} with a
formula context (a formula containing $*$).  We have seen also how to
state that a function terminates: for all possible inputs to the
function, there exists an output such that the function applied to the
inputs equals the output.  We may instantiate universal quantifiers
and witness existential ones only with values, which are terms
guaranteed to terminate.  Once we have proved a function terminates on
all inputs, we can register it as total using a
\texttt{Total}-command.  This function may then be used in
instantiating or witnessing terms.  

\section{Exercises}

As usual, please use only the proof constructs we have seen so far in
the book.  You are free, however, to use any lemmas proved in the
standard library (files in \texttt{guru-lang/lib/}).

\begin{enumerate}

\item Give an informal English translation of the following \guru formula:

\begin{verbatim}
Forall(a b:nat)(u:{ (le (S a) b) = tt }).{ (le a b) = tt }
\end{verbatim}

\item Prove the following formula:

\begin{verbatim}
Forall(x:nat)(u:{(lt Z x) = tt}). Exists(x':nat). { x = (S x') }
\end{verbatim}

\noindent HINT: my proof does not require induction, just a case split
on \texttt{x}, and then in the \texttt{Z} case, a proof using
\texttt{contra} and \texttt{clash}.

\item Write a formula in \guru that says that raising natural number
\texttt{x} to the power 1 gives you \texttt{x}.  What is the name of
that theorem in the standard library (where it is indeed proved)?

\item Prove

\begin{verbatim}
Forall(x y:nat)(u:{(mult y (S x)) = Z}). { y = Z }
\end{verbatim}

\noindent HINT: this can be proved by induction without using any
other lemmas, just reasoning directly about the behavior of
\texttt{mult} (and \texttt{plus}).

\item Prove the following theorem about the exponentiation function
\texttt{pow}, defined in \texttt{guru-lang/lib/pow.g}:

\begin{verbatim}
Forall(b e : nat)(u:{ b != Z }). { (le (S Z) (pow b e)) = tt }
\end{verbatim}

\noindent HINT: my proof begins by case splitting on \texttt{(pow b
e)} (see Section~\ref{ch5:case}), so that in the base case I can use
the lemma \texttt{pow\_not\_zero}, defined in \texttt{pow.g}.  In the
step case I made use of lemmas \texttt{S\_le\_S} and \texttt{leZ} from
\texttt{nat.g}.

\end{enumerate}


\chapter{Polymorphic Programming and Proving}

Up until now, we have limited ourselves to monomorphic programming,
where programs operate just on particular specified types of data.
With polymorphic programming, also known as generic programming, we
can write functions that operate polymorphically (or generically) for
any type of data.  This kind of polymorphism, the only kind we will
study in this book, is crucial for implementing generic data
structures, which can hold any type of data.  Such data structures
are, of course, of central importance for achieving code reuse.  We do
not wish to code up a different list datatype for every new type of
data we might wish to store in a list.  With a generic list datatype,
we design one datatype for lists of any single type of data, and write
functions operating on such lists.  With verified programming, we of
course also have the burden of writing proofs about those programs.
Naturally, those proofs are also generic, proving theorems for any
kind of data stored in the generic data structure. 

\section{Preview}

The main differences we find moving to generic programming are:

\begin{itemize}

\item polymorphic datatypes are described using datatype constructors,
also just called type constructors.  A type constructor constructs a
type when applied, at the type level, to some arguments (here, just
other types).  The notation for type-level application uses angle
brackets.  So for example, \texttt{<list nat>} is \guru notation for
applying the type constructor \texttt{list} to the type \texttt{nat}
to get the type of lists which store \texttt{nat}s.

\item pattern-matching will automatically equate type variables $A$ in
the type of the scrutinee with corresponding variables $A'$ in the
type of the pattern.  

\item the class of examples we can consider becomes much richer,
because we are now working with data structures -- i.e., structures
designed to hold other data -- rather than basic data like
\texttt{nat}s and \texttt{bool}s.

\end{itemize}

\section{Polymorphic Datatypes}
\label{ch6:lists}

In \guru, we use polymorphic datatypes to implement generic data
structures.  Polymorphic datatypes are declared like monomorphic
datatypes, using an \texttt{Inductive}-command.  The difference is
that they use type variables in several places, instead of particular
types.  We will begin by looking at a representative and frequently
used polymorphic datatype, the type for polymorphic lists.  We are all
familiar with various list datatypes in object-oriented programming
languages.  Lists in functional languages are implemented a bit
differently, because they must be described as inductive datatypes,
where bigger data are incrementally and uniquely built from smaller
data (see Section~\ref{ch2:ind}).  

Before we look at the polymorphic type, let us consider how we would
implement a monomorphic datatype \texttt{nlist} for lists of
\texttt{nat}s.  As an inductive datatype, lists are usually considered
to be built up from the empty list by gradually adding elements
(\texttt{nat}s for \texttt{nlist}s) one at a time to the front of the
list.  The constructor to do this is traditionally called
\texttt{cons} (going back to \textsc{LISP}).  The constructor for the
empty list is \texttt{nil}.  Here is the declaration in \guru for
this:

\begin{verbatim}
Inductive nlist : type :=
  nil : nlist
| cons : Fun(n:nat)(l:nlist).nlist.
\end{verbatim}

\noindent The value in \guru for the list ``1,2,3'' would then be
\texttt{(cons one (cons two (cons three nil)))}.  We apply
\texttt{cons} three times to incrementally grow our final list from
the starting list \texttt{nil}, the empty list.  Now let us see how to
declare the polymorphic \texttt{list} datatype:

\begin{verbatim}
Inductive list : Fun(A:type).type :=
  nil : Fun(A:type).<list A>
| cons : Fun(A:type)(a:A)(l:<list A>). <list A>.
\end{verbatim}

\noindent This is similar to the definition for \texttt{nlist}: we
still have constructors \texttt{nil} and \texttt{cons}, for example.
But obviously, there are some significant differences.  The first line
of the \texttt{Inductive}-command declares \texttt{list} to have
classifier \texttt{Fun(A:type).type}.  This makes \texttt{list} a
\emph{type constructor}.  We can think of it as a function that takes
an input \texttt{A} which is a type, and returns a type as output.
The input type \texttt{A} is the type for elements of the list, and
the output type is they type for lists of \texttt{A}s.  

Let us look now at the types of the constructors.  The type for
\texttt{nil} says that \texttt{nil} takes an input \texttt{A} which is
a type, and then returns an output of type \texttt{<list A>}.  This
notation, with the angle brackets, is for applying a type constructor
to arguments.  Such an application is called a \emph{type-level}
application, since it takes place at the level of types; in
particular, it produces a type as output.  Here, \texttt{list} is the
type constructor, and the argument is \texttt{A}.  Since \texttt{A}
has classifier \texttt{type}, and since \texttt{list} expects its
argument to have classifier \texttt{type}, this application (i.e.,
\texttt{<list A>}) is allowed, and has classifier \texttt{type}.
Sometime classifiers like \texttt{type} and \texttt{Fun(A:type).type},
which classify types and type constructors, are called \emph{kinds}
(see also Section~\ref{ch2:func}, where the classification hierarchy
for terms is mentioned).

Finally, we have the type for \texttt{cons}, which is
\texttt{Fun(A:type)(a:A)(l:<list A>).<list A>}.  This type says that
\texttt{cons} takes three inputs: a \texttt{type} \texttt{A}, a value
\texttt{a} of type \texttt{A}, and a list \texttt{l} of \texttt{A}s.
Then \texttt{cons} produces as output another list of \texttt{A}s.
Here we see how type variables like \texttt{A} enable us to describe
generic datatypes.  For any type \texttt{A} we like, we can pass a
piece of data ``\texttt{a}'' of type \texttt{A} to \texttt{cons}, to
be stored in the list.  Notice that a single list can hold data of
just a single type \texttt{A}.  Such lists are sometimes called
\emph{homogeneous}.  We cannot store a \texttt{nat} and a
\texttt{bool} in the same list.  Lists that allow different types of
data in the same list are sometimes called \emph{heterogeneous}.  As
an example of how the datatype works, here is the value that we will
write for the list ``1,2,3'':

\begin{verbatim}
(cons nat one (cons nat two (cons nat three (nil nat))))
\end{verbatim}

\noindent The sole argument to \texttt{nil} is a type, and the first
argument to \texttt{cons} is a type.  Here, the type is \texttt{nat}.
It is a bit annoying that \texttt{nat} is repeated all these times,
and it would be an improvement to \guru if it could be instead
inferred from the types of the data values like \texttt{one} that are
stored in the list.  Functional programming languages like
\textsc{OCaml} and \textsc{Haskell} provide powerful type inference
mechanisms to support polymorphic programming without type annotations
in code such as these uses of \texttt{nat} as arguments here.
Unfortunately, in the presence of the kind of polymorphism supported
by \guru, the problem of inferring a type for a term with no type
annotations is provably unsolvable (similarly to the way the more
familiar \emph{halting problem}, of whether or not a Turing machine
halts, is unsolvable).  So type inference is necessarily limited or
approximate in some way for such languages.  At the moment, \guru does
not attempt to provide such type inference, and we must live with
writing annotations like type arguments to polymorphic functions.

\section{Polymorphic Functions}
\label{ch6:func}

Programming with polymorphic data is similar to programming with
monomorphic data, except that we use type variables.  For example, let
us write an \texttt{append} function, for concatenating two
polymorphic lists.  As a warmup, here is code for appending
monomorphic \texttt{nlist}s, where we will rename the constructors
slightly so that they do not clash with those for \texttt{list}s:

\begin{verbatim}
Inductive nlist : type :=
  nnil : nlist
| ncons : Fun(n:nat)(l:nlist).nlist.

Define nappend : Fun(l1 l2:nlist).nlist :=
  fun(l1 l2:nlist).
    match l1 with
      nnil => l2
    | ncons n l1' => (ncons n (nappend l1' l2))
    end.
\end{verbatim}

\noindent The basic idea behind this function can perhaps be easier
seen via these equations:

\begin{verbatim}
(nappend nnil l2) = l2
(nappend (ncons n l1') l2) = (ncons n (nappend l1' l2))
\end{verbatim}

\noindent If the first list is empty, then we just return the second
(that is what the first equation says).  If the first list consists of
a \texttt{nat} \texttt{n} followed by a sublist \texttt{l1'}, then we
recursively append the sublist to l2.  This is done with
\texttt{(nappend l1' l2)} in the second equation.  Then we put
\texttt{n} at the front of the result.  This code has the effect of
working through the first list completely until it reaches
\texttt{nnil}, which it replaces with \texttt{l2}.  So the first list
is rebuilt starting with \texttt{l2} instead of with \texttt{nnil}.

Now let us see the polymorphic version of \texttt{append}, working on
polymorphic lists.  We can include the definition of \texttt{list}
given in the previous section from \texttt{guru-lang/lib/list.g}.  Because
some of the theorems in that file take a while to check, it is helpful
to do the include of \texttt{list.g} like this:

\begin{verbatim}
Include trusted "../guru-lang/lib/list.g".
\end{verbatim}

\noindent The ``\texttt{trusted}'' option tells \guru not to check any
proofs that are \texttt{Define}d in the included file or recursively
any files that file includes.  A better long-term solution is to
implement separate compilation for \guru, where once a file has been
checked, a summary of its declarations and definitions is created
which can be used later without rechecking the file.  This has not
been implemented yet, however.  When \guru terminates, it will print a
list (which can get rather long) of all the theorems whose proofs it
is trusting due to the use of ``\texttt{trusted}''.  To return: the
code for \texttt{append} can be written as follows.  Note that a much
more complicated definition is given in \texttt{list.g}, for reasons
which we will explain later.  We call our version here
\texttt{append'} to avoid a name conflict.

\begin{verbatim}
Define append' : Fun(A:type)(l1 l2:<list A>).<list A> :=
  fun append'(A:type)(l1 l2:<list A>):<list A>.
    match l1 with
      nil _ => l2
    | cons _ a l1' => (cons A a (append' A l1' l2))
    end.
\end{verbatim}

\noindent There are, clearly, several differences from the monomorphic
\texttt{nappend} defined above.  First, \texttt{append'} takes a type
\texttt{A} as its first argument.  The second and third arguments are
then of type \texttt{<list A>}, meaning that they are lists whose
elements are of type \texttt{A}.  Then \texttt{append'} returns a list
of \texttt{A}s.  Other differences include the fact that \texttt{A} is
passed as an argument to \texttt{cons}, and also in the recursive call
to \texttt{append}.  This makes sense from a classification
perspective, since \texttt{cons} and \texttt{append} require a type as
their first arguments, and that type has to match up in the
appropriate way with later arguments.  One feature we have not
discussed yet is used for the patterns of the cases.  Here, an
underscore is written for the type argument (the first argument to
\texttt{nil} and \texttt{cons}).  There is no special meaning to
underscore: it is just another pattern variable in this case.  I am
using underscore here just to indicate informally that that variable
is not used later.  So it is essentially an ignored variable.  Again,
this is all informal: \guru does not check that it is ignored.  

The one subtle point we must note here is that for the second pattern,
say, to classify, it must be the case that the pattern variable
\texttt{a} has classifier \texttt{\_}\,.  This is because
\texttt{cons}'s type says that the first argument is some type, here
\texttt{\_}\,, and the second argument then has that type.  So
\texttt{a} really has type \texttt{\_}\,.  How then can we treat it as
if it has type \texttt{A}, for example when we pass it to
\texttt{cons} in the body of the clause for \texttt{cons}?  Because
\guru automatically equates \texttt{\_} and \texttt{A} in this
situation.  The algorithm \guru uses is the following.  

\begin{enumerate}
\item Compute the type, call it $T_S$, for the scrutinee.  Here, the
scrutinee is \texttt{l1}, and its type is \texttt{<list A>}.
\item Then for each clause, compute the type, call it $T_P$, for the
clause's pattern.  In the clause for \texttt{cons}, for example, the
type of the pattern is \texttt{<list \_>}.
\item Match $T_S$ against $T_P$.  That is, treat $T_P$ as a pattern,
and pattern match it against $T_S$.  Pattern variables occurring in
$T_P$ are considered variables which can be instantiated by this
pattern matching.  So here, we are matching \texttt{<list A>} against
\texttt{<list \_>}, where \texttt{\_} is considered an instantiable
variable (because \texttt{\_} is a variable in the pattern
\texttt{cons \_ a l1'}).  The instantiation that makes these two types
equal is the one which maps \texttt{\_} to \texttt{A}.
\item Extend definitional equality in the body of the clause to equate
any variables instantiated by pattern matching with whatever they were
instantiated to.  So in the body of the clause for \texttt{cons}, definitional
equality is extended to equate \texttt{\_} and \texttt{A}.
\item Now classify the body of the case with the extended definitional
equality.  This explains why \texttt{(cons A a)} type checks in the
body of the \texttt{cons}-clause: once we have given \texttt{A} as the
first argument to \texttt{cons}, the second argument is expected to have
type \texttt{A}; the given second argument ``\texttt{a}'' actually has
type \texttt{\_}\,; but these are considered definitionally equal in this
case, so the application type checks.
\end{enumerate}

We will see later situations where this simple algorithm is not
sufficient, particularly for dependently type programming.  In those
situations, explicit type casts are used in code, which begin with the
keyword \texttt{cast}.  You will see some of these in library files,
including \texttt{list.g} (for reasons explained in
Section~\ref{ch6:compile}).  But for polymorphic programming as we
usually encounter it (certainly in \textsc{OCaml} or \textsc{Haskell}
without some of its recent extensions to the type system), this is
enough to make the connection between the type of the scrutinee and
the type of the pattern, in a fully automatic way.

\section{Polymorphic Proving}

Let us now prove that \texttt{append'} is associative.  The theorem we wish to prove
is written this way in \guru:

\begin{verbatim}
Forall(A:type)(l1 l2 l3 : <list A>). 
  { (append' l1 (append' l2 l3)) = (append' (append' l1 l2) l3) }
\end{verbatim}

\noindent There are two points to explain here.  First, we are
quantifying over a type \texttt{A}, similarly to the way our code for
\texttt{append'} above takes in a type \texttt{A}.  The second point,
which is somewhat subtle, is in the phrasing of the equation we are
proving.  Notice that here, unlike in our code above, no type argument
is given to \texttt{append'}.  We just call \texttt{append'} with the
two lists.  Here we are seeing in action one of the main features of
\guru over related proving environments like \textsc{Coq}.  Equations
are always stated and proved between terms without any type
annotations.  In fact, \guru's definitional equality erases type
annotations from terms.  So \texttt{(nil bool)} and \texttt{(nil nat)}
are considered definitionally equal, when we compare classifiers.  In
fact, note that when we drop their type annotations, we get just
\texttt{nil}, with no parentheses.

The rationale for this approach is that we are interested in reasoning
about the computational behavior of programs, which in \guru does not
depend on type annotations.  So we may reason about the programs with
their annotations dropped.  Practically speaking, this greatly
simplifies reasoning about code with annotations, since they are
erased for purposes of equational reasoning.  Tools like \textsc{Coq}
do not erase such annotations, which then clutter proofs.  The problem
becomes much worse with dependently typed programming, where programs
contain much more complex annotations than just a few type arguments
here for polymorphic programming.

\begin{verbatim}
Define append'_assoc : 
  Forall(A:type)(l1 l2 l3 : <list A>). 
    { (append' l1 (append' l2 l3)) = (append' (append' l1 l2) l3) } :=
foralli(A:type).
induction(l1:<list A>) 
return Forall(l2 l3 : <list A>).
        { (append' l1 (append' l2 l3)) = (append' (append' l1 l2) l3) } 
with
  nil _ => 
  foralli(l2 l3 : <list A>). 
    trans cong (append' * (append' l2 l3)) l1_eq
    trans join (append' nil (append' l2 l3)) (append' (append' nil l2) l3)
          cong (append' (append' * l2) l3) symm l1_eq
| cons _ a l1' =>
  foralli(l2 l3 : <list A>).
    trans cong (append' * (append' l2 l3)) l1_eq
    trans join (append' (cons a l1') (append' l2 l3))
               (cons a (append' l1' (append' l2 l3)))
    trans cong (cons a *) [l1_IH l1' l2 l3]
    trans join (cons a (append' (append' l1' l2) l3))
               (append' (append' (cons a l1') l2) l3)
          cong (append' (append' * l2) l3) symm l1_eq
end.
\end{verbatim}

\noindent This proof does not use any features we have not already
discussed.  The algorithm described in the previous section for
connecting the scrutinee's type and the pattern's type is used here
also for the clauses of the \texttt{induction}-proof (the same
algorithm is used for \texttt{case}-proofs, too).  We do induction on
the first list \texttt{l1}, following Hint~\ref{hint:indrec}, since
\texttt{l1} is used twice in an analyzed argument position, here the
first argument position of \texttt{append} (while \texttt{l2} is used
once and \texttt{l3} not at all in such a position).  Otherwise, we
just perform straightforward equational reasoning, where as explained
just above, we do not need to include the type annotations in any of
the terms we use in equational reasoning.  In particular, we give
completely unannotated terms to \texttt{join} and \texttt{cong}.

\section{The Fold-Right Function}

An important polymorphic function often defined on lists is the
fold-right function, which we will call \texttt{foldr'}; the name is
to avoid a conflict with a more complex version \texttt{foldr} defined
in \texttt{guru-lang/lib/list.g}, which we will discuss below.  The
basic idea is that \texttt{foldr'} should take a function
``\texttt{f}'' of type \texttt{Fun(a:A)(b:B).B} and a starting value
\texttt{b} of type \texttt{B}.  It will iterate \texttt{f} over the
elements of the list, starting with value \texttt{b} and accumulating
a resulting value of type \texttt{B} for the whole list.  For example,
given a list like ``a1,a2,a3'' of elements of type \texttt{A},
\texttt{foldr'} with \texttt{f} and \texttt{b} will return:

\begin{verbatim}
(f a1 (f a2 (f a3 b)))
\end{verbatim}

\noindent We will see in just a moment why this is useful, but let
us first write the type for \texttt{foldr'}:

\begin{verbatim}
Fun(A B:type)
   (f:Fun(a:A)(b:B).B)
   (b:B)
   (l:<list A>).B 
\end{verbatim}

\noindent I have split this across multiple lines for readability.  We can
see that we must first take in the types \texttt{A} and \texttt{B}.  Then
we take in the function \texttt{f} and the starting value \texttt{b},
and finally the list of \texttt{A}s.  The code for \texttt{foldr'} is
easy to write:

\begin{verbatim}
fun foldr'(A B:type)(f:Fun(a:A)(b:B).B)(b:B)(l:<list A>):B.
  match l with
    nil _ => b
  | cons _ a l' => (f a (foldr' A B f b l'))
  end.
\end{verbatim}

\noindent When the list \texttt{l} is empty, we return our starting
value \texttt{b}.  When it consists of an element ``\texttt{a}'' and a
sublist \texttt{l'}, we apply \texttt{f} to \texttt{a} and also to the
result of folding \texttt{f} on \texttt{l'}.

\subsection{Using \texttt{foldr'} to compute length}

As a simple example, we can use \texttt{foldr'} to give a very concise
(and non-recursive) definition of a function to compute the length of
a list:

\begin{verbatim}
Define length' :=
   fun(A:type)(l:<list A>).
     (foldr' A nat fun(a:A)(n:nat).(S n) Z l).
\end{verbatim}

\noindent First we should confirm that this type checks.  For example,
the third argument's type is \texttt{Fun(a:A)(n:nat).nat}, which is
correct given that the first two arguments are \texttt{A} and
\texttt{nat}.  To understand how this definition of \texttt{length}
works, let us look at what \texttt{foldr'} will return for a list
``a,b,c''.  Writing \texttt{F} for the function
\texttt{fun(a:A)(n:nat).(S n)}, the returned value is computed by:

\begin{verbatim}
(F a (F b (F c Z)))
\end{verbatim}

\noindent The starting value we have given \texttt{foldr'} is the
fourth argument, \texttt{Z}.  So we see ``\texttt{Z}'' at the right of
the expression just above.  Then we have the iteration of \texttt{F}
through the data of the list.  We can easily see that \texttt{\{ (F x
y) = (S y) \}} for all \texttt{x} and \texttt{y}.  Transforming the
above expression one step at a time (just for emphasis), we see that
the expression is indeed equal to the length of the list (namely,
three):

\begin{verbatim}
(F a (F b (F c Z))) =
(S (F b (F c Z))) =
(S (S (F c Z))) =
(S (S (S Z)))
\end{verbatim}

\subsection{Using \texttt{foldr'} to map a function}

Another common operation in polymorphic functional programming with
lists is to transform an input list of \texttt{A}s into a list of
\texttt{B}s by applying a function \texttt{f} of type
\texttt{Fun(x:A).B} to the elements of the input list.  This operation
is called \emph{map}.  We can implement a version of this called
\texttt{map'} using \texttt{foldr'}, as follows:

\begin{verbatim}
Define map' := 
  fun(A B:type)(f:Fun(x:A).B)(l:<list A>).
    (foldr' A <list B> fun(x:A)(l2:<list B>).(cons B (f x) l2) (nil B) l).
\end{verbatim}

\noindent The second argument to \texttt{foldr'} is always the type of
the data that is being computed by the function we are folding across the
list's data.  We wish to compute a list of \texttt{B}s from a list of \texttt{A}s,
so the final result we want from our folding operation is of type \texttt{<list B>}.
That explains the second argument to \texttt{foldr'}.  For the third, we can confirm
it has the correct type:

\begin{verbatim}
Fun(x:A)(l2:<list B>).<list B>
\end{verbatim}

\noindent This fits the pattern for these functions: their types
should be of the form \texttt{Fun(x:X)(b:Y).Y}, for some types
\texttt{X} and \texttt{Y}.  The function we are folding takes in the
element of the list first, as \texttt{x} of type \texttt{A}, and it
takes the result of folding the function over a sublist (\texttt{L},
say), and returns the result of folding the function over
\texttt{(cons A a L)}.  So we just use \texttt{cons} to put together
\texttt{(f x)} and the result \texttt{l2} of mapping the sublist.
Our starting value for this folding operation is \texttt{(nil B)},
the empty list at type \texttt{B}.

\subsection{Some complications due to compilation}
\label{ch6:compile}

If you look in \texttt{guru-lang/lib/list.g}, you will see first our
definition of polymorphic lists (from Section~\ref{ch6:lists}), and
definitions of functions \texttt{foldr}, \texttt{map}, and
\texttt{length} that behave just like the functions with similar names
that we have defined above.  But the definitions are more complicated,
and indeed a bit ugly.  For example, \texttt{foldr} is declared to
have this type:

\begin{verbatim}
Fun(A B C: type)(owned cookie:C)
   (fcn: Fun(owned cookie:C)(owned x:A)(y:B).B)
   (b:B)(owned l : <list A>).B
\end{verbatim}

\noindent This is similar to, but not the same as, the type for
\texttt{foldr'} that we have above:

\begin{verbatim}
Fun(A B: type)
   (f: Fun(x:A)(y:B).B)
   (b:B)(l : <list A>).B
\end{verbatim}

\noindent The difference (other than the different name for the
function which is being folded -- a purely syntactic difference with
no semantic import) is that the type of \texttt{foldr} takes three
types, \texttt{A}, \texttt{B}, and \texttt{C}; where \texttt{foldr'}
takes just \texttt{A} and \texttt{B}.  Then \texttt{foldr} expects a
\emph{cookie} of type \texttt{C}, and the function \texttt{fcn} that
it takes as its fifth input expects to be called with such a cookie. 
Furthermore, the keyword \texttt{owned}, which we have not seen up to
now, is used in several places.  What is going on?

What is going on is that we are, for the first time, encountering code
that is actually intended to be compiled to C code and executed
efficiently.  Up until now, all the code we have considered is not
intended for compilation to C, but rather just in specifying such
code.  After all, what computation do we really want to do with unary
natural numbers?  Efficient computations should be done with machine
integers, which we will discuss in a later section.  Unary
\texttt{nat}s are much better than machine integers for specification,
however, since they are much easier to reason with.  The boolean
datatype is used heavily in practice, but it is so simple it turns out
to constitute a special case: it is just an enumeration, and those can
be handled specially during compilation to C code.  But with the list
datatype, we actually encounter a non-trivial datatype that we wish to
use in compiled code.  So here, we run into several issues in \guru as
it currently stands, that must be dealt with.  These issues are not
fundamental to the language; we could change \guru so that we did not
have to deal with them.  But it turns out there are some reasons for
not doing so, even though it results in somewhat less pleasant code.
We will explore all three of these issues in more detail later.  For
now, this is just a preview so we can handle the code in
\texttt{lib/list.g}.

\begin{enumerate}
\item When \guru programs are compiled to C, memory is managed using
reference counting, not garbage collection as is typical in other
memory-safe languages (a memory-safe language is, at least roughly,
one where we it is not possible to read uninitialized memory or read
or write freed memory).  \guru uses ownership annotations like
\texttt{owned} here to help reduce the cost of reference counting.

\item When compiling \texttt{fun}-terms to C, the compiler requires
that they do not contain any free variables.  For example, a
\texttt{fun}-term like \texttt{fun(x:nat).(plus x y)} is disallowed by
the compiler.  Such \texttt{fun}-terms are supported by functional
languages like \textsc{OCaml} and \textsc{Haskell}, and indeed, many
would consider them crucial to the functional programming methodology.
They are disallowed in the current version of \guru for reasons again
related to memory management.  A language that supports (compilation
of) functions with free variables is said to support \emph{closures}
(this is the name of the compiler technique used to support functions
with free variables).

\item In code which will be compiled, again for reasons related to
memory management, it is sometimes necessary to use explicit type
casts, even though the algorithm presented at the end of
Section~\ref{ch6:func} succeeds in connecting the type of the
scrutinee with the type of a pattern in a \texttt{match}-term.
The syntax for these casts is

\begin{verbatim}
cast t by P
\end{verbatim}

\noindent where \texttt{t} is a term of type \texttt{T}, and \texttt{P} is
a proof of \{ \texttt{T} = \texttt{T'}\}, for some type \texttt{T'}.  The
\texttt{cast} then has type \texttt{T'}.  

\end{enumerate}

\noindent So, our \texttt{foldr} code includes some \texttt{owned}
annotations related to memory management.  The type \texttt{C} for
cookies is to accomodate functions that might want to rely on
auxiliary data.  If \guru supported closures, we would not need these
cookies, since auxiliary data could be included in the function itself
via free variables.  Since we do not support closures, the auxiliary
data must be passed in via a cookie, which is some other data
structure that exists just to hold that auxiliary data.

The functions \texttt{foldr} and \texttt{map} in \texttt{lib/list.g}
are written to use cookies, just in case the functions being folded or
mapped need to use cookies.  The \texttt{length} function just uses a
trivial cookie \texttt{unit} of type \texttt{Unit}, defined in
\texttt{lib/unit.g}.  For purposes of proving lemmas about these
functions, it should be possible to:

\begin{itemize}

\item Ignore ownership annotations completely in your proofs.  You
should never have to type a keyword like \texttt{owned} anywhere in
your proofs.  This is because these annotations are dropped out by
definitional equality inside proofs (though not inside terms).

\item Reason about those functions as if they had the simpler
definitions above.  They do the same thing, except that they pass
cookies around in some cases where the simpler definitions do not.
\end{itemize}

\noindent When writing new code using these functions, we can also
avoid ownership annotations by using the \texttt{spec} option with the
\texttt{Define}-command.  For example, the following definition uses
\texttt{foldr} (the one from \texttt{lib/list.g} with cookies) to
define a function \texttt{concat} that takes a list whose elements are
lists of \texttt{A}s and appends all those elements to get just a list
of \texttt{A}s.  Without the \texttt{spec} option just after the
\texttt{Define} keyword, this will not type check in \guru due to the
lack of ownership annotations:

\begin{verbatim}
Define spec concat : Fun(A:type)(l:<list <list A>>).<list A> :=
  fun(A:type)(l:<list <list A>>).
    (foldr <list A> <list A> Unit unit 
       fun(u:Unit)(l1 l2:<list A>).(append A l1 l2) 
       (nil A) l).
\end{verbatim}

\begin{comment}
\section{Termination Casts}

Termination of higher-order functions is typically conditional on
termination of any functional arguments they take in.  For example,
the \texttt{member} function, defined in \texttt{lib/list.g}, has this
type (dropping some ownership annotations):

\begin{verbatim}
Fun(A:type)(x:A)(l:<list A>)
   (eqA:Fun(owned x1 x2:A).bool).
 bool
\end{verbatim}

\noindent So \texttt{member} takes in a type \texttt{A}, an element
\texttt{x} of type \texttt{A}, and a list \texttt{l} of \texttt{A}s.
The goal is to test whether or not \texttt{x} is a member of
\texttt{l}.  For this to be possible, however, \texttt{member} needs a
function \texttt{eqA} to test equality of elements of type \texttt{A}.
Without such a function, \texttt{member} has no way to check whether
\texttt{x} is equal to an element \texttt{a} of the list.

Termination of \texttt{member} is predicated on termination of this
\texttt{eqA} function: if it were to diverge, then so would
\texttt{member}.  So \texttt{member} is, in fact, a partial function.
It terminates on some inputs (namely those where \texttt{eqA} is
terminated), but diverges on other (where \texttt{eqA} is diverging
and the list is non-empty).  
\end{comment}

\section{Exercises}

The usual restriction on using proof methods discussed in the book so far applies.

\begin{enumerate}
\item Prove the following theorem about the \texttt{fill} function in \texttt{guru-lang/lib/list.g}:

\begin{verbatim}
Forall(A:type)(a:A)(n m:nat).
      { (fill a (plus n m)) = (append (fill a n) (fill a m)) }
\end{verbatim}

\noindent In the code for \texttt{fill}, you will see \texttt{inc a}.
This \texttt{inc} is for incrementing a reference count.  In proofs,
\texttt{inc a} is definitionally equal to \texttt{a}.

\noindent HINT: I proved this using induction on one of the variables
(which one would it most likely be?), and I did not need any other
lemmas.

\item Prove that \texttt{fill} is total.

\item Prove the following theorem, which states that mapping
``\texttt{f}'' and then mapping ``\texttt{g}'' is the same as mapping
their composition.  Note how \texttt{fun}-terms are written with
annotations dropped, on the right hand side of the equation (for the
composition of ``\texttt{f}'' and ``\texttt{g}'').  The type for cookies
is taken to be just \texttt{Unit}, for simplicity.

\begin{verbatim}
Forall(A B C:type)
      (f:Fun(u:Unit)(x:A).B)
      (g:Fun(u:Unit)(x:B).C)
      (l:<list A>).
  { (map unit g (map unit f l)) = (map unit fun(u x).(g u (f u x)) l) } 
\end{verbatim}

\noindent HINT: my proof is by induction on one of the variables (which?), and
uses no other lemmas.

\item Using \texttt{foldr} defined in \texttt{guru-lang/lib/list.g},
define a function \texttt{some} with the same type as the function
\texttt{all} defined at the bottom of \texttt{lib/list.g}.  This
function \texttt{some} should return \texttt{tt} if the given function
\texttt{f} returns \texttt{tt} for some element of the list, and
\texttt{ff} otherwise.  In contrast, the \texttt{all} function returns
\texttt{tt} if \texttt{f} returns \texttt{tt} for all elements of the
list, and \texttt{ff} otherwise.

\item Write down two universally quantified formulas in \guru syntax,
where each one mentions two functions from \texttt{\{ foldr, length,
append, foldr, all, some, fill \}}, and where you believe the formula
to be provable in \guru.  Your formulas should not be trivially
provable, in the sense that they should not be provable using only
\texttt{foralli} and \texttt{join}: \texttt{induction} or at least
\texttt{case}-proofs should be required to prove the formulas.  

\ 

Optional: prove one of the formulas you have written.

\end{enumerate}

\chapter{Dependently Typed Programming}

In the preceding chapters, we have seen how to write monomorphic and
later polymorphic programs, and to prove properties about their
operational (i.e., run-time) behavior.  Those proofs are external to
programs, in the sense that they reside outside the code for the
functions in question, and from that external position prove
operational properties of the code.  With external verification,
proofs and programs are distinct and separate artifacts.

In this chapter, we study internal verification, where a program and a
proof are written as a single combined artifact.  Syntactically this
artifact is a program (i.e., a term), but it contains proofs inside
it.  These proofs are there to demonstrate to the type checker that
the code has a semantically rich type, called a \emph{dependent type}.
The semantic richness and the dependency of these types arises because
dependent types are allowed to mention (``depend on'') terms.  We have
seen in the previous chapter how types can mention other types: the
type \texttt{<list A>} of lists of \texttt{A}s mentions the type
\texttt{A}.  More concretely, \texttt{<list nat>} mentions the type
\texttt{nat}.  With dependent types, we can have a type like
\texttt{<vec A n>}, where \texttt{n} is a \texttt{nat}, and hence a
term.  This \texttt{<vec A n>} is the type for lists (``vectors'') of
\texttt{A}s of length \texttt{n}.  A dependent datatype like this is
also sometimes called an \emph{indexed} type (where \texttt{vec} is
considered to be indexed by \texttt{n}).  The length \texttt{n} is
present in the type, which allows the expression of more complex
relationships between the types of program data than we have seen up
to now.  For example, we may write an append function on vectors that
takes a \texttt{<vec A n>} and a \texttt{<vec A m>} as inputs, and
produces a \texttt{<vec A (plus n m)>} as output.  At various places
in the code for this vector append function, it is necessary to use a
proof to convince the \guru type checker that two types are
equivalent.  For example, we might need to convince the type checker
that \texttt{<vec A (plus n m)>} and \texttt{<vec A (plus m n)>} are
equivalent.  We can do this using congruence and commutativity of
\texttt{plus}.

Programming with dependent types has been studied intensively in the
past few years, with a number of different research languages for
dependently typed programming proposed
~\cite{nanevski+08,norell07,pasalic+07,sheard06,licata+05,chenxi05,wsw-icfp05,mcbride+04}.
The motivation for this is that programming with rich dependent types
seems to be closer to more traditional programming than a combination
of traditional programming and external theorem proving, and still can
give stronger correctness properties than are possible with
traditional type checking.  The \textsc{ghc} implementation of
\textsc{Haskell} has recently added support for a limited kind of
dependent types called Guarded Algebraic Datatypes
(GADTs)~\cite{Jones+06}.  Dependent types arose much earlier than
these works, in type theoretic formulations of logic.  A well-known
example is Martin-L\"of type theory~\cite{ml84}.

Because practical dependently typed programming is rather new, there
is not yet consensus on effective methodology for using it.  One
question is, when to use dependent types and when to use external
verification (assuming a language supports both, as \guru does).  One
simple practical answer is that it can quickly become infeasible to
use external verification for large functions.  Certainly in \guru,
external verification relies heavily on partial evaluation, which will
become unbearable with functions more than a few tens of lines long:
otherwise we will end up \texttt{join}ing one gigantic program term
with another, which will bloat proofs unacceptably.  In such cases,
dependent types are very useful, because we need never write a proof
about the large function.  Instead, we give it a rich type which
captures some critical properties of it, the way the type mentioned
above for vector append captures the property that the length of the
output list is equal to the sum of the lengths of the input lists.

\section{Preview}

In this chapter we will see how to define dependent types like
\texttt{<vec A n>}, and how to write dependently typed programs
operating on such types.  In the next chapter we will discuss external
verification of dependently typed programs.

\begin{itemize}
\item A dependent type like \texttt{vec} is declared using an \texttt{Inductive}-command like this:
\begin{verbatim}
Inductive vec : Fun(A:type)(n:nat).type :=
  vecn : Fun(A:type).<vec A Z>
| vecc : Fun(A:type)(n:nat)(a:A)(l:<vec A n>).
              <vec A (S n)>.
\end{verbatim}

\item Proofs of type equivalence enter code in \texttt{cast}-terms, mentioned at the end
of the last chapter.

\item Previously, we have seen how \texttt{match}-terms,
\texttt{case}-proofs, and \texttt{induction}-proofs introduce an
assumption variable like \texttt{n\_eq} for a match on ``\texttt{n}''.
This variable proves that the scrutinee is equal to the pattern in
each clause of the expression.  These expressions also have a second
assumption variable, which is \texttt{n\_Eq} for ``\texttt{n}''.  This
proves that the scrutinee's type is equal to the pattern's type.
These assumptions can be needed to reason based on the fact that
indices to the scrutinee's type are equal to corresponding indices of
the pattern's type.  Injectivity, embodied in \texttt{inj}-proofs, is
used to go from the proof that the types are equal to the proof that
the indices are equal.

\end{itemize}

\section{Indexed Datatypes}

The declaration for the indexed datatype \texttt{vec} for vectors
(i.e., lists) of \texttt{A}s of length \texttt{n} in \guru is:

\begin{verbatim}
Inductive vec : Fun(A:type)(n:nat).type :=
  vecn : Fun(A:type).<vec A Z>
| vecc : Fun(A:type)(n:nat)(a:A)(l:<vec A n>).
              <vec A (S n)>.
\end{verbatim}

\noindent You can find this declaration in
\texttt{guru-lang/lib/vec.g} (ignoring for now the \texttt{spec}
keyword that appears in one place there).  In the first line, we
declare \texttt{vec} to be a type constructor, similarly to the
declaration we have in Section~\ref{ch6:lists} for \texttt{list}.
Here we see that \texttt{vec}'s classifier (its \emph{kind}) is
\texttt{Fun(A:type)(n:nat).type}.  So when we apply \texttt{vec} --
which is done at the type level using angle brackets, as we saw for
\texttt{list} -- we will have to supply two arguments: a type and a
\texttt{nat}.  So for example, \texttt{<vec nat Z>} is a correct
type-level application of \texttt{vec}, and will have classifier
\texttt{type}.  So \texttt{<vec nat Z>} is a type.

Now let us look at the declarations of the constructors, \texttt{vecn}
and \texttt{vecc}.  This \texttt{vecn} corresponds to \texttt{nil} for
lists: it creates the vector of \texttt{A}s of length zero.  That is
indeed what its type tells us.  Given \texttt{A} that is a type,
\texttt{vecn} will return a value of type \texttt{<vec A Z>}.  To
extend a vector by adding a new element to the front, we use
\texttt{vecc}, corresponding to \texttt{cons} for lists.  This takes
in a type \texttt{A}, a \texttt{nat} ``\texttt{n}'', an element
\texttt{a} of type \texttt{A} (this is the element to add to the front
of the vector), and a subvector \texttt{l}.  The subvector should have
type \texttt{<vec A n>}.  Since ``\texttt{n}'' is the length of the
subvector, the length for the new vector being built by \texttt{vecc}
is \texttt{(S n)}.  This is because we have added one element to the
front of ``\texttt{l}'', thus yielding a list whose length is one
greater than \texttt{l}'s.

The interpretation of ``\texttt{n}'' in \texttt{<vec A n>} as the
length of the vector is not machine-checked.  We have given the index
\texttt{n} this interpretation informally.  We have not proven any
theorem relating this \texttt{n} to the length of the vector as
computed by some \texttt{length} function.  

Here is an example value built using \texttt{vecc} and
\texttt{vecn}:

\begin{verbatim}
(vecc nat (S Z) three (vecc nat Z four (vecn nat)))
\end{verbatim}

\noindent This value has type \texttt{<vec nat (S (S Z))>}.  This is a
vector of length two (the ``\texttt{(S (S Z))}'' in this type).  The
data stored in this vector are \texttt{three} and \texttt{four} (so
the list looks like ``3,4'').  We have a type annotation \texttt{nat}
in three places.  We also have annotations \texttt{Z} and \texttt{(S
Z)} for the lengths of sublists.  These are given as the second
argument to \texttt{vecc} in each case.  

\section{Programming with Indexed Types}

Let us now see how to write the append function on vectors.  As mentioned above,
we wish to write this function so that it has the following type:

\begin{verbatim}
Fun(A:type)(n m:nat)(l1 : <vec A n>)(l2 : <vec A m>).<vec A (plus n m)>
\end{verbatim}

\noindent We will take in \texttt{A} that is the type of elements in
the vectors, ``\texttt{n}'' and ``\texttt{m}'' that are the lengths of
the vectors, and then the vectors themselves.  We will return a vector
of length \texttt{(plus n m)}.  This function will behave very
similarly to append on \texttt{list}s, except for the presence of the
indices to \texttt{vec} for the lengths of the lists.  It is these
which require some extra work for dependently typed programs.  

Just like \texttt{list} append, \texttt{vec} append will use the first
list as its parameter of recursion.  Let us think for a moment about
the base case, when this vector \texttt{l1} is the empty vector.  In
this case, we wish just to return \texttt{l2}.  This is exactly what
\texttt{list} append does.  Our only difficulty is with the types.
Our ``\texttt{l2}'' has type \texttt{<vec A m>}, but we are supposed
to return (from \texttt{vec} append) a value of type \texttt{<vec A
(plus n m)>}.  Of course, we are in the case where \texttt{l1} is
empty, so its length ``\texttt{n}'' is equal to zero.  That means
that the type \texttt{<vec A (plus n m)>} is actually equal to \texttt{<vec A m>},
since in this case:

\begin{verbatim}
(plus n m)  =  (plus Z m)  =  m
\end{verbatim}

\noindent We just need to prove that type equality to \guru.  This can be
done by standard \guru equational reasoning with \texttt{cong}, \texttt{join},
and the rest, as long as we can get that proof that \texttt{\{ n = Z\}}.  How
do we do that?  

\subsection{The assumption variable for types}
\label{ch7:assumpvar}

We have seen how all the constructs in \guru that have clauses --
\texttt{match}-terms, \texttt{case}-proofs, and
\texttt{induction}-proofs -- make available an assumption variable
in each clause that says that the scrutinee is equal to the pattern.
For example, in Section~\ref{ch3:case}, we saw this simple \texttt{case}-proof:

\begin{verbatim}
Define not_not : Forall(b:bool). { (not (not b)) = b } :=
  foralli(b:bool).
    case b with
      ff => trans cong (not (not *)) b_eq
            trans join (not (not ff)) ff
                  symm b_eq
    | tt => trans cong (not (not *)) b_eq
            trans join (not (not tt)) tt
                  symm b_eq           
    end.
\end{verbatim}

\noindent In each clause, the assumption variable \texttt{b\_eq} is
automatically declared.  In the \texttt{ff}-clause its classifier is
\texttt{\{ b = ff \}}, while in the \texttt{tt}-clause its classifier
is \texttt{\{ b = tt \}}.  So \texttt{b\_eq} serves as a proof of the
assumption that the scrutinee matches the pattern in each clause.

For dependently typed programs, we need to reason about indices to
types.  For this purpose, clausal constructs in \guru provide a second
assumption variable.  Where the first assumption variable proves, in
each clause, that the scrutinee is equal to the pattern of the clause,
the second assumption variable proves that the scrutinee's type is
equal to the pattern's type.  Where the first assumption variable is
automatically named \texttt{x\_eq} for scrutinee ``\texttt{x}'', the
second is automatically named \texttt{x\_Eq}.  

For monomorphic code, this assumption is never interesting, since the
types involved do not have any structure.  For example, in the
\texttt{not\_not} proof above, the second assumption variable, whic is
automatically named \texttt{b\_Eq}, proves \texttt{\{ bool = bool\}}.
This is because the type of the scrutinee ``\texttt{b}'' is
\texttt{bool}, and the type of the patterns (\texttt{ff} and
\texttt{tt}) is \texttt{bool}.  Let us return to the code for
\texttt{vec} append to see a more interesting example.

\subsection{Starting the base case of vector append}

Here is the code for vector append (found in
\texttt{guru-lang/lib/vec.g}), not including the clause for
\texttt{vecc}:

\begin{verbatim}
fun vec_append(A:type)(n m:nat)(l1 : <vec A n>)(l2 : <vec A m>):
              <vec A (plus n m)>.
    match l1 with
      vecn _ => cast l2 by
                cong <vec A *>
                 symm trans cong (plus * m)
                              inj <vec ** *> l1_Eq
                            join (plus Z m) m
   | vecc _ n' x l1' => ...
   end.
\end{verbatim}

\noindent The function begins as we would expect based on the type it
is supposed to have.  It does a \texttt{match} on \texttt{l1}.  As for
polymorphic \texttt{match}-terms, \guru makes the connection between
\texttt{\_} and \texttt{A}, and declares them definitionally equal in
the bodies of the clauses (see Section~\ref{ch6:func}).  We then see a
\texttt{cast}-term.  The syntax of such terms is \texttt{cast t by P},
where ``\texttt{t}'' is a term and \texttt{P} is a proof.  If
``\texttt{t}'' has type \texttt{T}, and \texttt{P} proves \texttt{\{T
= T'\}}, then the whole \texttt{cast}-term has type \texttt{T'}.  In
other words, a \texttt{cast}-term is used to change the type of
\texttt{t} from \texttt{T} to \texttt{T'}, where \texttt{P} proves
these types are equal.  In our case here, the goal is to change the
type of \texttt{l2} from \texttt{<vec A m>} to \texttt{<vec A (plus n
m)>}.  Let us walk through the proof to see how this is done.

First, if we use \texttt{show} on the \texttt{trans}-proof, we will
see it proves these equational steps:

\begin{verbatim}
1. (plus n m) =

2. (plus Z m) =

3. m
\end{verbatim}

\noindent The only new part of the \texttt{trans}-proof is how we obtain
the fact that \texttt{\{n = Z\}}.  This is done with an \texttt{inj}-proof,
\texttt{inj <vec ** *> l1\_Eq}, which we explain next.

\subsection{Injectivity reasoning}

Suppose we have a proof \texttt{P} that \texttt{\{(S x) = (S y)\}}.
This should mean that \texttt{\{x = y\}}, but up until now, we have
not seen how to conclude this in \guru.  The way to do so is to use
\emph{injectivity} reasoning.  Term and type constructors are
injective.  A function $f$ is injective iff $f(x) = f(y)$ implies $x =
y$.  In other words, the only way $f$ can map $x$ and $y$ to the same
output is if $x$ and $y$ are the same input.  If $x \neq y$, then
$f(x) \neq f(y)$.

In \guru, injectivity reasoning is done with \texttt{inj}-proofs.  The
general syntax is slightly complicated, so let us start with our
example using successor.  If \texttt{P} proves \texttt{\{(S x) = (S
y)\}}, the \texttt{inj (S *) P} proves \texttt{\{x = y\}}.  We use a
context here to indicate which position is of interest to us (marked
with $*$, as for congruence).

The general syntax of an \texttt{inj}-proof is \texttt{inj C P}, where
\texttt{C} is an \emph{injectivity context} and \texttt{P} is a proof.
An injectivity context is a constructor term or a type with a hole $*$
in it, indicating a position of interest.  In addition, a second hole
$**$ is used to indicate positions we wish to ignore.  The use of the
injectivity context is as follows.  We check that the proof \texttt{P}
proves a formula of the form \texttt{\{C[e,e1,\ldots,en] =
C[e',e1',\ldots,en']\}}, where \texttt{C[e,e1,\ldots,en]} means the
expression obtained by substituting \texttt{e} for the first hole and
\texttt{ei} for the $i$'th occurrence of the second hole in
\texttt{C}.  In other words, the left and right hand sides of the
equation proved by \texttt{P} share a common top-level structure
described by \texttt{C}, differing in one place we care about
(indicated with $*$) and several places we do not (indicated by $**$).
Then the \texttt{inj}-proof proves \texttt{\{e = e'\}}.

\subsection{Finishing the base case of vector append}

Now we may return to the base case of vector append, to understand the
proof used to cast \texttt{l2} from type \texttt{<vec A m>} to
\texttt{<vec A (plus n m)>}:

\begin{verbatim}
cong <vec A *>
  symm trans cong (plus * m)
               inj <vec ** *> l1_Eq
             join (plus Z m) m
\end{verbatim}

\noindent The \texttt{inj}-proof here uses the second assumption
variable \texttt{l1\_Eq} (see Section~\ref{ch7:assumpvar}).  This
variable has the following classifier:

\begin{verbatim}
{ <vec A n> = <vec _ Z> }
\end{verbatim}

\noindent The left hand side is the type of the scrutinee
``\texttt{l1}'', while the right hand side is the type of the pattern
\texttt{(vecn \_)}.  From this we wish to conclude that \texttt{\{n =
Z\}}.  We must tell \texttt{inj} to disregard the difference between
\texttt{A} and \texttt{\_} in the first argument position of the two
expressions.  For that we use \texttt{**}, so we have \texttt{<vec **
*>} as our context.  The only other point to note in our proof is that
we use \texttt{cong} with a type context \texttt{<vec A *>}.  This
works exactly as \texttt{cong} with a term context.  Here, the
\texttt{cong}-proof goes from a proof that \texttt{\{m = (plus n m)\}}
(note the use of \texttt{symm} to get this from the
\texttt{trans}-proof) to a proof that:

\begin{verbatim}
<vec A m> = <vec A (plus n m)>
\end{verbatim}

\noindent This is what we need to cast \texttt{l2} to be able to
return it in the base case.

\subsection{Finishing vector append}
\label{ch7:vec_append}

The full code for vector append is:

\begin{verbatim}
fun vec_append(A:type)(n m:nat)(l1 : <vec A n>)(l2 : <vec A m>):
              <vec A (plus n m)>.
  match l1 with
    vecn _ => cast l2 by
              cong <vec A *>
                symm trans cong (plus * m)
                             inj <vec ** *> l1_Eq
                           join (plus Z m) m
  | vecc _ n' x l1' => 
     cast
        (vecc A (plus n' m) x (vec_append A n' m l1' l2)) 
     by cong <vec A *>
           trans symm join (plus (S n') m)
                           (S (plus n' m))
                 cong (plus * m)
                   symm inj <vec ** *> l1_Eq
    end.
\end{verbatim}

\noindent Let us look now at the \texttt{vecc}-clause.  In this case,
\texttt{l1} is a \texttt{vecc}-term, where the subvector is
\texttt{l1'}, of type \texttt{<vec \_ n'>}.  The data at the front of
the vector is \texttt{x} of type \texttt{\_}.  The type of this pattern
is then

\begin{verbatim}
<vec _ (S n')>
\end{verbatim}

\noindent As remarked for the base case, \guru makes the connection
between \texttt{\_} and \texttt{A}.  But we need to help \guru make
the connection between the length \texttt{n} of \texttt{l1} and
\texttt{(S n')}.  This is again done by injectivity reasoning: at
the very end of the body of this clause, we have again \texttt{inj <vec ** *> l1\_Eq},
proving in this case that

\begin{verbatim}
{ n = (S n') }
\end{verbatim}

\noindent Let us see what the \texttt{cast} is doing.  First, we
should figure out what type the term has which is being cast.  The term is

\begin{verbatim}
(vecc A (plus n' m) x (vec_append A n' m l1' l2)) 
\end{verbatim}

\noindent From the type of \texttt{vec\_append} specified at the very
start of the recursive \texttt{fun}-term, we can compute that the term
\texttt{(vec\_append A n' m l1' l2)} has type \texttt{<vec A (plus n'
m)>}.  Notice how, in this term, the indices \texttt{n'} and
\texttt{m} have to relate to the types of \texttt{l1'} and
\texttt{l2}.  Once we have specified to \texttt{vec\_append} that the
lengths of the vectors are \texttt{n'} and \texttt{m}, then we really
need to give vectors whose types say they have those lengths.  Turning
now to the entire \texttt{vecc}-term, we can compute that it has this
type:

\begin{verbatim}
<vec A (S (plus n' m))>
\end{verbatim}

\noindent This is because we are adding an element \texttt{x} to the
front of the vector built by the recursive call to
\texttt{vec\_append}.  We have already seen that that vector has type
\texttt{<vec A (plus n' m)>}.  Adding one to that length leads to the
type \texttt{<vec A (S (plus n' m))>}.

So the \texttt{cast}-term is changing the type of this \texttt{vecc}-term
from 

\begin{verbatim}
<vec A (S (plus n' m))>
\end{verbatim}

\noindent to

\begin{verbatim}
<vec A (plus n m)>
\end{verbatim}

\noindent The critical part of this, of course, is changing from
\texttt{(S (plus n' m))} to \texttt{(plus n m)}, which we well know
how to do at this point, using equational reasoning.

\section{Binary Search Trees}

As another example, we will define an indexed datatype for binary
search trees in such a way that any value of that datatype truly
satisfies the binary search tree property: if we go left from a node
with data $x$ in the tree, we will only ever see data less than or
equal to $x$; and if we go right, we will see data greater than or
equal to $x$.  To enforce these invariants, the solution here is to
index the type of binary search trees by lower and upper bounds on the
data stored in the tree.  To do this in a generic way, we do not build
in the comparison, \texttt{le}, but allow it to be specified by users
of our datatype.  So our type for binary search trees is:

\begin{verbatim}
<bst A le l u>
\end{verbatim}

\noindent Here, \texttt{A} is the type for data stored in the tree,
\texttt{le} is the comparator, and \texttt{l} and \texttt{u} are
the lower and upper bounds, respectively.  Here is the declaration
for this datatype:

\begin{verbatim}
Inductive bst : Fun(A:type)(le:Fun(a b:A).bool)(l u : A).type :=
  leaf : Fun(A:type)(le:Fun(a b:A).bool)(a:A).
            <bst A le a a>
| node : Fun(A:type)(le:Fun(a b:A).bool)
            (a l1 u1 l2 u2:A)
            (t1 : <bst A le l1 u1>)
            (t2 : <bst A le l2 u2>)
            (q1:{ (le u1 a) = tt})
            (q2:{ (le a l2) = tt}).
            <bst A le l1 u2>.
\end{verbatim}

\noindent We are supposing here that we always have two children, and
that leaves store data.  In the next chapter, we will revisit these
assumptions.  Let us walk through this declaration.  First, the kind
for \texttt{bst} is declared to be:

\begin{verbatim}
Fun(A:type)(le:Fun(a b:A).bool)(l u : A).type
\end{verbatim}

\noindent This means that for \texttt{<bst A le l u>} to be a type, we
must have \texttt{le} be a function that takes two \texttt{A}s as
inputs, and produces a \texttt{bool} telling whether or not the first
is less than the second.  The lower and upper bounds (\texttt{l} and
\texttt{u}) must have type \texttt{A}, naturally.  The type for
\texttt{leaf} says that a leaf storing data ``\texttt{a}'' has lower
and upper bounds \texttt{a}: the return type for \texttt{leaf} is
\texttt{<bst A le \framebox{a} \framebox{a}>}.  

The type for \texttt{node} is more complicated.  The basic idea is
that we want to make a new tree with left and right subtrees
\texttt{t1} and \texttt{t2}, respectively, where the new tree stores
data ``\texttt{a}'' (at the top of the tree).  Here is where we
enforce our invariants that going left should give you data less than
or equal to ``\texttt{a}'', while going right should give you greater
than or equal data.  Let \texttt{l1} and \texttt{u1} be the lower and
upper bounds on the data in \texttt{t1}.  Then \texttt{u1} should be
less than or equal to ``\texttt{a}''.  Similarly, if \texttt{l2} and
\texttt{u2} are lower and upper bounds on the data in \texttt{t2}, we
should have ``\texttt{a}'' less than or equal to \texttt{l2}.  When
\texttt{node} is applied, proofs of these facts must be given, for the
parameters \texttt{q1} and \texttt{q2}.  We then get a new tree with
lower bound \texttt{l1} and upper bound \texttt{u2}.

Programming with datatypes like \texttt{bst} that have such strong
invariants is not easy.  For example, we might wish to write a
function \texttt{insert}, to insert a piece of data in the
\texttt{bst}.  If we were using external verification, we would have
one modestly tricky piece of code to write, and one more complicated
theorem proving that the tree produced by inserting a piece of data
into a binary search tree is again a binary search tree.  With our
indexed \texttt{bst} datatype, the proof and the program have to be
combined, resulting in a single, more compact artifact that the
separate proof and program, but one that is more complicated, perhaps,
than either of them separately would be.

\section{Summary}

We have seen how to design indexed datatypes for internal
verification.  In some cases, our indices simply provide information
about the data, as the length index for vectors does, without
constraining the data at all.  Such information can be used for
internal verification of functions operating on the data, such as
verifying the relationship between input and output lengths to the
vector append function.  In other cases, like the binary search tree
example, indices are actually used to help state constraints on the
data.  We have seen how to use injectivity and casts to work with
indexed data in \guru programs.  In the next chapter, we will see how
to prove properties of dependently typed functions.

\section{Exercises}

\begin{enumerate}

\item Declare an indexed datatype \texttt{slist} for sorted lists of
\texttt{nat}s.  Your declaration should make \texttt{<slist n>} a type
for any \texttt{nat} \texttt{n}.  Your datatype should be designed in
such a way that if \texttt{L} is of type \texttt{<slist n>}, then
either \texttt{L} is empty and \texttt{n} is zero (``\texttt{Z}''), or
else \texttt{n} is the head of the list.

\item Define a function \texttt{insert} which takes a \texttt{nat} \texttt{x} and
a sorted list, and returns a new sorted list where \texttt{x} has been inserted.
In more detail, your function's type should begin like this:

\begin{verbatim}
Fun(x n:nat)(l:<slist n>).
\end{verbatim}

\noindent It should return a sorted list.  The first question you
should try to answer is, what index to \texttt{slist} will be used in
the return type?  Mine uses a certain arithmetic function applied to
\texttt{x} and \texttt{n}.  Writing \texttt{insert} then requires
several lemmas about this arithmetic function, which you can find
proved already in one of the files in the standard library
(\texttt{guru-lang/lib/*g}).

\item Explain in English what the type of \texttt{vec\_cat}, defined
in \texttt{lib/vec.g}, is saying about what that function does.
Similarly, explain what the type of \texttt{vec\_get}, also defined in
\texttt{lib/vec.g}, says about what that function does.

\end{enumerate}

\chapter{Specificationality and Dependently Typed Proving}

In this chapter, we discuss an important feature of \guru for
dependently typed programming, which is \emph{specificationality}.
Arguments to term constructors and to recursive functions can be
designated as specificational.  This means that they are only to be
used when type checking code, and they will disappear, just like type
annotations, when reasoning about code.  Indices to indexed types are
very often specificational.  For example, code working with vectors
typically does not need the length of the vector to compute a desired
output value.  The length is really just specificational, allowing us
to state properties about operations on vectors by relating indices of
input and output vectors (as we did in the type of vector append).
The one rule about specificational data, naturally enough, is that
non-specificational data cannot be computed from specificational data.
\guru enforces this be disallowing pattern matching (in code) on
specificational data, and by requiring that specificational data can
be passed to term constructors or to recursive functions only in
positions which have been designated (by the term constructor or the
function) as specificational.  It is fine, however, to use
non-specificational data in a specificational argument position.
Specificationality makes external verification of dependently typed
code easier, since specificational data are dropped during equational
reasoning.  We will see examples of that in this chapter, as we
consider proving properties of dependently typed functions.

\section{Preview}

\begin{itemize}

\item We will see how to mark arguments as specificational using the
\texttt{spec} keyword, and how this feature is used with vectors and
binary search trees.

\item Specificationality is also useful for a rather rarely used
feature of \guru, which is \texttt{existse\_term}.  This is like
\texttt{existse}, but is a term construct, rather than a proof
construct.  The name we introduce for the value which has been proven
to exist must be marked as specificational, since we must prohibit
non-specificational values from being computed from it.

\item We will see examples of proving properties of dependently typed
code.  The main differences to note are that specificational data are
considered annotations, similar to type annotations, and are dropped
during equational reasoning; and that the form of
\texttt{induction}-proofs is generalized to allow quantification over
indices used by the type of the parameter of induction.  So to induct
over a vector, we will start with ``\texttt{induction(n:nat)(l:<vector
A n>)}''.  Without this extra generality, we would typically not be
able to apply the induction hypothesis, for typing reasons.

\item We will also introduce \texttt{hypjoin}, which tries to join
terms (similarly to \texttt{join}), except that it also performs
substitutions using a given set of proven equations.

\end{itemize}

\section{Specificationality for Datatypes}

The vector datatype we saw in the last chapter is indexed by the
length of the vector.  The types of functions can then state
non-trivial semantic properties via relationships between indices to
input and output vectors.  For example, the type of vector append
state a non-trivial property of the input and output vectors by
stating that the length index of the output vector is the sum of the
length indices of the input vectors.  In this example and many others,
we can regard the index as just being part of the specification of the
function.  The function itself does not pattern match on indices, or
perform other operations with them that would affect the output value
computed.  Hence, these indices are typically computationally
irrelevant, just like type annotations.  So we should be able to drop
them during compilation and during theorem proving, if we wish.  Of
course, to do this we need a way to distinguish between arguments (to
recursive functions and term constructors) that are only
specificational, like the length of a vector, and arguments that are
computational, in the sense that the final output value may depend on
them.  \guru provides a mechanism for distinguishing computational
arguments and specificational arguments, using the \texttt{spec}
keyword.  

\subsection{Specificationality for vectors}

Let us look at the declaration of \texttt{vec} as it actually appears
in \texttt{lib/vec.g}:

\begin{verbatim}
Inductive vec : Fun(A:type)(n:nat).type :=
  vecn : Fun(A:type).<vec A Z>
| vecc : Fun(A:type)(spec n:nat)(a:A)(l:<vec A n>).
              <vec A (S n)>.
\end{verbatim}

\noindent The argument \texttt{n} to \texttt{vecc} is labeled
specificational with the \texttt{spec} keyword.  This keyword is
itself an annotation that will be dropped during theorem proving by
definitional equality.  It just indicates that arguments given for
\texttt{n} are specificational, and computational values should not
depend on them.  

For an example of how this works, consider a vector storing just the
natural number \texttt{two}.  With its type annotations, this is
written just as it would be without the \texttt{spec} annotation:

\begin{verbatim}
(vecc nat Z two (vecn nat))
\end{verbatim}

\noindent If we had not marked the length argument to \texttt{vecc} as
specificational, then dropping annotations would result in this term,
where the length \texttt{Z} still remains in the term:

\begin{verbatim}
(vecc Z two (vecn nat))
\end{verbatim}

\noindent But with the \texttt{spec} keyword in our declaration of
\texttt{vec}, the length is considered an annotation, and dropping
annotations actually yields the pleasantly simplified:

\begin{verbatim}
(vecc two vecn)
\end{verbatim}

The vector append function may now also mark the lengths of its input
vectors as specificational.  From \texttt{lib/vec.g}, we have the
following, where \texttt{P1} and \texttt{P2} are standing in for the
same two proofs we had in the previous chapter for
\texttt{vec\_append} (see Section~\ref{ch7:vec_append}):

\begin{verbatim}
Define vec_append :=
fun vec_append(A:type)(spec n m:nat)(l1 : <vec A n>)(l2 : <vec A m>):
              <vec A (plus n m)>.
    match l1 with
      vecn _ => cast l2 by P1
    | vecc _ n' x l1' => 
       cast
          (vecc A (plus n' m) x (vec_append A n' m l1' l2)) 
       by P2
    end.
\end{verbatim}

\noindent Note the use of the \texttt{spec} keyword where \texttt{n}
and \texttt{m} are declared.  When \guru type checks this
\texttt{fun}-term, it will make sure that \texttt{n} and \texttt{m}
are only used in specificational argument positions of applications.
We can confirm by eye that indeed they are: \texttt{n} is not used
anywhere.  For \texttt{m}, it is used as the third argument, which is
specificational, to the recursive call to \texttt{vec\_append}; and
also in the application of \texttt{plus}.  But that application is
itself used in a specificational position, and hence satisfies the
criteria on use of specificational data: they may only appear in
specificational argument positions.  The length \texttt{n'} of
\texttt{l1'} in the \texttt{vecc}-clause is also specificational
(since the declaration of \texttt{vecc} says it is), but it is also
used only in specificational positions.

When the code for \texttt{vec\_append} is compiled, all data in
specificational argument positions are dropped.  So the term
\texttt{(plus n' m)} will not be evaluated at run-time, since it is
used (only) in a specificational argument position to \texttt{vecc}.
It is important that \texttt{(plus n' m)} will be dropped in this
case, since otherwise \texttt{vec\_append} would run in time quadratic
in the length of the first input list: we would execute an addition
that takes time linear in this length for each recursive call.  With
\texttt{(plus n' m)} dropped, however, the function runs in time
linear in the length of the first input list.

Similarly, when it is time to reason externally about
\texttt{vec\_append}, we will do so using its unannotated version,
which it definitionally equals:

\begin{verbatim}
fun vec_append(l1 l2).
    match l1 with
      vecn => l2 
    | vecc x l1' => (vecc x (vec_append l1' l2)) 
    end.
\end{verbatim}

\noindent Notice that terms of the form \texttt{cast t by P} are
replaced by just \texttt{t} when we drop annotations.  Specificational
input variables have been dropped from the \texttt{fun}-term, and
similarly from patterns in \texttt{match}-terms.  Again, this code is
clearly much more succinct and easier to manage, for external
reasoning, than the annotated version, and we might wish we could
write only this.  Annotations are the price of internal reasoning.

\subsection{Specificationality for binary search trees}

At the end of the previous chapter, we considered a polymorphic
datatype of binary search trees.  Here, we will work with the
following monomorphic datatype of binary search trees of
\texttt{nat}s:

\begin{verbatim}
Inductive bst : Fun(l u : nat).type :=
  leaf : Fun(a:nat).<bst a a>
| node : Fun(a l1 u1 l2 u2:nat)
            (t1 : <bst l1 u1>)
            (t2 : <bst l2 u2>)
            (q1:{ (le u1 a) = tt})
            (q2:{ (le a l2) = tt}).
            <bst l1 u2>.
\end{verbatim}

\noindent Similarly to what we had before, the type \texttt{<bst l u>}
is for binary search trees whose data are bounded between \texttt{l}
and \texttt{u}.  The \texttt{node} constructor takes a piece of data
``\texttt{a}'' to store at the root of the new tree, and then subtrees
\texttt{t1} and \texttt{t2}.  Those have their own lower and upper
bounds, namely \texttt{l1} and \texttt{u1}, \texttt{l2} and
\texttt{u2}.  

One problem with this design arises because data are stored at the
leaves, and nodes must have exactly two subtrees.  So we cannot have,
for instance, a tree with just two pieces of data in it.  We can have
a leaf, which has one piece of data, or a node built from two leaves,
which has three; but nothing in between.  Using specificationality, we
can solve this problem.  Let us make our lower and upper bounds
specificational data.  This is surely sensible, since the bounds
themselves are not intended to have any computational role: they are
just used to help enforce (at compile time) the binary search tree
property.  What will our datatype look like then?  Clearly the
arguments \texttt{l1},\texttt{u1},\texttt{l2}, and \texttt{u2} to
\texttt{node} should be specificational.  The interesting question is,
what about the argument to \texttt{leaf}?  If we make it
specificational, then computationally speaking, leaves do not store
any data.  The argument to \texttt{leaf} is specificational,
indicating which lower and upper bounds the leaf should be viewed as
having.  (Indeed, we could imagine a different definition where
\texttt{leaf} takes possibly distinct specificational lower and upper
bounds as arguments, instead of just the single argument \texttt{a}.)
The definition with \texttt{spec} annotations is:

\begin{verbatim}
Inductive bst : Fun(l u : nat).type :=
  leaf : Fun(spec a:nat).<bst a a>
| node : Fun(a:nat)(spec l1 u1 l2 u2:nat)
            (t1 : <bst l1 u1>)
            (t2 : <bst l2 u2>)
            (q1:{ (le u1 a) = tt})
            (q2:{ (le a l2) = tt}).
            <bst l1 u2>.
\end{verbatim}

\noindent To build a tree storing just \texttt{two}, say, we could
write:

\begin{verbatim}
(node two two two two two (leaf two) (leaf two) 
      [x_le_x two] [x_le_x two])
\end{verbatim}

\noindent This is definitionally equal (dropping annotations) to just:

\begin{verbatim}
(node two leaf leaf)
\end{verbatim}

\noindent The type annotation and the lower and upper bounds have all
dropped away, since the corresponding argument positions of
\texttt{leaf} and \texttt{node} are specificational.  Proofs (using
the \texttt{x\_le\_x} lemma from \texttt{lib/nat.g}, which says that
any \texttt{x} is less than or equal to itself) are considered
annotations, too, so they have also disappeared.  Of course, we could
wish to write just the simple unannotated term instead of the much
more verbose annotated one, but the annotations are the cost of our
static guarantee that the node satisfies the binary search tree
property.  Finally, to build a tree storing just \texttt{one} and
\texttt{two}, which was not possible to do with the previous design
for \texttt{bst}, without specificationality; we can write:

\begin{verbatim}
(node one one one two two (leaf one)
  (node two two two two two (leaf two) (leaf two) 
      [x_le_x two] [x_le_x two])
  [x_le_x one]
  join (le one two) tt)
\end{verbatim}

\section{Existential Elimination in Terms}

Specificationality is useful for accomodating a rarely used feature of
\guru, the \texttt{existse\_term} construct.  This allows us to do an
existential elimination inside a term.  Our interest here is not so
much in \texttt{existse\_term}, as in the utility of
specificationality in bridging between proofs and terms in dependently
typed code.  

Recall the \texttt{existe} proof construct (Section~\ref{ch5:existse},
where the syntax is \texttt{existse P1 P2}, with:

\begin{itemize}
\item \texttt{P1 : Exists(x:A).F1}
\item \texttt{P2 : Forall(x : A)(u:F1).F2}
\end{itemize}

\noindent The whole \texttt{existse}-expression is then a proof of
\texttt{F2}.  In contrast, the \texttt{existse\_term P t} is a term
(not a proof), of type \texttt{B}, when:

\begin{itemize}
\item \texttt{P : Exists(x:A).F}
\item \texttt{t : Fun(spec x : A)(u:F).B}
\end{itemize}

\noindent The two constructs are clearly based on the same idea of a
universal hypothetical interpretation of existentials.  In the case of
\texttt{existse\_term}, the subterm \texttt{t} takes in the value
proven to exist, together with a proof that that value has the
property described by \texttt{F}.  Here, when we introduce the name
\texttt{x} for that value, the \texttt{existse\_term}-construct
requires that we mark \texttt{x} as specificational.  This ensures
that our computational results cannot depend on the witness to the
existential.  So \texttt{existse\_term P t} can be treated as
definitionally equal to just \texttt{t}, similarly to the way
\texttt{cast t by P} is definitionally equal to just \texttt{t}: the
witness introduced by \texttt{P} is computationally irrelevant, and
hence \texttt{P} can be treated as computationally irrelevant, too.
This is consistent with the view of proofs as computationally
irrelevant where they are used in other places in terms.

\section{Induction Over Indexed Datatypes}
\label{ch8:bst_bounds}

Proving properties about values of indexed datatypes and about
dependently typed code is similar to the proving we have done up to
now, with two new points to note.  First, the form of
\texttt{induction}-proofs is generalized just slightly, so that we may
quantify over not just the parameter of induction, but also over
indices mentioned in its type.  This gives us extra generality in our
induction hypothesis, without which we would not be able to apply it,
in many cases. Second, proofs and specificational data occurring in
terms are computationally irrelevant, and hence drop out during
external reasoning, just like type annotations do when reasoning about
polymorphic programs.

For an example, let us prove a property of our \texttt{bst} datatype,
which partially shows that we have designed it correctly.  The
property is that if we have a \texttt{bst} with lower bound \texttt{l}
and upper bound \texttt{u}, then \texttt{l} is really less than or
equal to \texttt{u}.  Stated in \guru, the property is:

\begin{verbatim}
Forall(l u:nat)(b:<bst l u>). { (le l u) = tt}
\end{verbatim}

\noindent Unfortunately, this is a sad case where
Hint~\ref{hint:indrec} misleads us.  The only universal variable used
as a parameter of recursion in a function mentioned in our theorem is
\texttt{l}, as the first argument to \texttt{le}.  But in fact, we
would get nowhere doing induction on \texttt{l} in this case.  This is
an easy lemma, if we prove it by induction on \texttt{b}.  I cannot
think of a good rule of thumb to help guide us here, except to observe
that this is really a property of our binary search trees, not of
their lower and upper bounds.  But how we know this, or what it means
for this to be ``really'' a property of \texttt{b} rather than
\texttt{l} or \texttt{u} is something I do not know.

Leaving aside these difficulties, let us try the proof by induction on
\texttt{b}.  Suppose we begin the following way, which will turn out
not to work:

\begin{verbatim}
  foralli(l u:nat).
  induction(b:<bst l u>) return { (le l u) = tt}
\end{verbatim}

\noindent All will be well in the base case.  But in the step case,
for when \texttt{b} is a \texttt{node}-value, we will run into difficulty
applying our induction hypothesis.  There, we will have \texttt{b} of
the form \texttt{(node a l1 u1 l2 u2 t1 t2 q1 q2)}, where

\begin{itemize}
\item \texttt{t1 : <bst l1 u1>}
\item \texttt{t2 : <bst l2 u2>}
\end{itemize}

\noindent Since \texttt{t1} and \texttt{t2} are subtrees of \texttt{b}, the requirement
that the induction hypothesis be used only for structurally smaller trees is fulfilled.
But we have a problem with typing.  The induction hypothesis for the proof as we have
begun it is:

\begin{verbatim}
Forall(b:<bst l u>). { (le l u) = tt }
\end{verbatim}

\noindent We may only instantiate this with a subtree of type
\texttt{<bst l u>}.  But our subtrees \texttt{t1} and \texttt{t2} have
different types (e.g., \texttt{<bst l1 u1>} for \texttt{t1}).  So typing
constraints will not be satisfied if we try to instantiate the induction
hypothesis with a proof-level application like \texttt{[b\_IH t1]}, and
we will not be able to complete our proof.

The induction hypothesis we need to avoid this problem is one which includes
the lower and upper bounds:

\begin{verbatim}
Forall(l u:nat)(b:<bst l u>). { (le l u) = tt }
\end{verbatim}

\noindent Since the lower and upper bounds are now included in the
quantification, a proof like \texttt{[b\_IH l1 u1 t1]} will now pass
the proof checker: we have instantiated the bounds in a way that
allows us to instantiate the tree with \texttt{t1}.  \guru's
\texttt{induction} proof construct allows us to write this
\texttt{induction}-proof in such a way that we get this more general
induction hypothesis.  The straightforward syntax is demonstrated
below, as well as the easy bodies of the clauses (note that
\texttt{le\_trans} is for transitivity of \texttt{le}, from
\texttt{lib/nat.g}):

\begin{verbatim}
  induction(l u:nat)(b:<bst l u>) return { (le l u) = tt}
    with
    leaf _ => trans cong (le l *) inj <bst ** *> b_Eq
                    [le_refl l] 
  | node a _ u1 l2 _ t1 t2 q1 q2 => 
    [le_trans l a u
       [le_trans l u1 a [b_IH l u1 t1] q1]
       [le_trans a l2 u q2 [b_IH l2 u t2]]]
  end.
\end{verbatim}

\noindent This proof is called \texttt{bst\_bounds} in \texttt{lib/bst.g}.

\section{Dependently Typed Proving}

As mentioned, proofs and specificational data drop out of terms during
external reasoning about them.  Consider the following code for testing
whether or not a piece of data is in a \texttt{bst}:

\begin{verbatim}
Define bst_in : Fun(x:nat)(spec l u:nat)(t:<bst l u>). bool :=
  fun bst_in(x:nat)(spec l u:nat)(t:<bst l u>): bool.
    match t with
      leaf _ => ff
    | node a l1 u1 l2 u2 t1 t2 q1 q2 =>
      match (eqnat x a) with
        ff => 
          match (le x a) with
            ff => (bst_in x l2 u2 t2)
          | tt => (bst_in x l1 u1 t1)
          end
      | tt => tt
      end
    end.
\end{verbatim}

\noindent Let us prove the following theorem about this piece of code:

\begin{verbatim}
Forall(x l u:nat)(t:<bst l u>)(u:{(bst_in x t) = tt}). { (le l x) = tt }
\end{verbatim}

\noindent That is, if \texttt{x} is in \texttt{bst} \texttt{t} with
lower bound \texttt{l} and upper bound \texttt{u}, then \texttt{l}
must be less than or equal to \texttt{x} (of course, \texttt{x} must
be also less than or equal to \texttt{u}, but we do not prove that
here for simplicity).  Let us write our proof using refinement.  You
can find this proof in \texttt{lib/bst-spec.g}, as
\texttt{bst\_in\_le1} (\texttt{bst-spec.g} is just temporary, to avoid
confusion with \texttt{bst.g} as it is being used by homework 3
currently).  Our starting point is just to write down the initial
\texttt{foralli} and \texttt{induction} parts:

\begin{verbatim}
 foralli(x:nat).
 induction(l u:nat)(t:<bst l u>) return
   Forall(u:{(bst_in x t) = tt}). { (le l x) = tt } with
   leaf _ => truei
 | node a l1 u1 l2 u2 t1 t2 q1 q2 => truei
end.
\end{verbatim}

\subsection{The base case}

Let us fill in the base case of this proof.  There, we have that
\texttt{t} is a leaf, but our assumption \texttt{u} tells us that
\texttt{x} is in \texttt{t}.  This will give us a contradiction, since
our code for \texttt{bst\_in} says that no data is stored in a leaf.
We prove this using unannotated terms, as we do for all theorem
proving.  The proof looks like this (with the equational steps to be
shown just below):

\begin{verbatim}
 foralli(x:nat).
 induction(l u:nat)(t:<bst l u>) return
   Forall(u:{(bst_in x t) = tt}). { (le l x) = tt } with
   leaf _ => 
     foralli(u:{(bst_in x t) = tt}).
     contra
       trans symm u
       trans cong (bst_in x *) t_eq
       trans join (bst_in x leaf) ff
             clash ff tt
     { (le l x) = tt }
 | node a l1 u1 l2 u2 t1 t2 q1 q2 => truei
end.
\end{verbatim}

\noindent The equational steps are:

\begin{verbatim}
1. tt =

2. (bst_in x t) =

3. (bst_in x leaf) =

4. ff !=

5. tt
\end{verbatim}

\noindent Here we can clearly see that all the specificational data --
in this case, the lower and upper bounds -- have been dropped from the
\texttt{bst\_in}-terms.

\subsection{\texttt{Case}-proofs in the step case}

For the step case, where the tree \texttt{t} is a \texttt{node}-value,
we will do case splits following the pattern matches in
\texttt{bst\_in}, and then fill in the proofs in each case.  Putting
in just the case splits to begin with, we can write the following,
where \texttt{P1} is the proof of the base case considered above:

\begin{verbatim}
 induction(l u:nat)(t:<bst l u>) return
   Forall(u:{(bst_in x t) = tt}). { (le l x) = tt } with
   leaf _ => P1
 | node a l1 u1 l2 u2 t1 t2 q1 q2 => 
     foralli(u:{(bst_in x t) = tt}).
     case (eqnat x a) by v1 _ with
       ff =>
       case (le x a) by v2 _ with
         ff => truei
       | tt => truei
       end
     | tt => truei
     end
  end.
\end{verbatim}

\noindent Notice that in our two \texttt{case}-proofs, we use
\texttt{by}-clauses to introduce names -- \texttt{v1} for the first
\texttt{case}-proof, \texttt{v2} for the second -- for the assumptions
that the scrutinee equals the pattern in each clause (see
Section~\ref{ch5:case} for more on \texttt{by}-clauses).  So for example,
at the point where the first \texttt{truei} is, we have:

\begin{itemize}
\item \texttt{v1 : \{(eqnat x a) = ff\}}
\item \texttt{v2 : \{(le x a) = ff\}}
\end{itemize}

\noindent It is burdensome to have to pick and remember the names
\texttt{v1} and \texttt{v2}, which is why \guru assigns the standard
names ending with ``\texttt{\_eq}'' (and ``\texttt{\_Eq}'' for the
equality between the type of the scrutinee and the type of the
pattern) when it is reasonable to do so (when the scutinee is a
symbol).  

\subsection{The first subcase}

The reasoning for the situation of the first \texttt{truei} is as
follows (using conventional mathematical notation for
less-than-or-equal-to).  We need to show $\texttt{l} \le \texttt{x}$.
We first observe that it suffices to show $\texttt{l1} \le
\texttt{x}$.  This is because \guru considers \texttt{l1}
definitionally equal to \texttt{l} in the \texttt{node}-clause, after
applying the algorithm of Section~\ref{ch6:func}.  In more detail, the
type of the scrutinee (here, the parameter of induction) is
\texttt{<bst l u>}.  The type of the pattern is \texttt{<bst l1 u1>}.
The algorithm of Section~\ref{ch6:func} tries to pattern match the
latter against the former, where pattern variables may be instantiated
by the pattern matching.  Here the pattern variables are \texttt{l1}
and \texttt{u1}.  We can indeed make the \texttt{bst}-types identical
by mapping \texttt{l1} to \texttt{l} and \texttt{u1} to \texttt{u}.

Continuing now with the inequality reasoning: we wish to show
$\texttt{l1} \le \texttt{x}$.  Since $x \le a$ is false, we can
conclude, using a lemma somewhat verbosely called
\texttt{le\_ff\_implies\_le} in \texttt{lib/nat.g}, that $a \le x$ is
true.  We have $\texttt{u1} \le a$ by the assumption \texttt{q1},
since our \texttt{node} constructor (which introduces \texttt{q1} as a
pattern variable here) requires a proof that the upper bound of the
left subtree is less than or equal to the data \texttt{a} stored by
the node.  Also, by the \texttt{bst\_bounds} lemma which we proved in
Section~\ref{ch8:bst_bounds}, we have that $\texttt{l1} \le
\texttt{u1}$.  So we have this chain of inequalities, which we can
glue together with \texttt{le\_trans}:

\[ \texttt{l1} \ \ \le\ \ \texttt{u1} \ \ \le \ \ \texttt{a} \ \ \le \ \ \texttt{x} \]

\noindent The proof in \guru syntax is:

\begin{verbatim}
[le_trans l1 a x 
   [le_trans l1 u1 a [bst_bounds l1 u1 t1] q1]
   [le_ff_implies_le x a v2]]
\end{verbatim}

\noindent We have nested (proof-level) applications of
\texttt{le\_trans}.  The outer application goes from \texttt{l1} to
\texttt{a} to \texttt{x}.  The inner one goes from \texttt{l1} to
\texttt{u1} to \texttt{a}.  This corresponds to grouping our
inequalities above like this:

\[ (\texttt{l1} \ \ \le\ \ \texttt{u1} \ \ \le \ \ \texttt{a}) \ \ \le \ \ \texttt{x} \]

\noindent That is, we first (corresponding to the inner
\texttt{le\_trans}) go from \texttt{l1} to \texttt{a}, and then to
\texttt{x}.

\subsection{The third subcase}

Our proof currently looks like this:

\begin{verbatim}
 induction(l u:nat)(t:<bst l u>) return
   Forall(u:{(bst_in x t) = tt}). { (le l x) = tt } with
   leaf _ => 
     foralli(u:{(bst_in x t) = tt}).
     contra
       trans symm u
       trans cong (bst_in x *) t_eq
       trans join (bst_in x leaf) ff
             clash ff tt
     { (le l x) = tt }
 | node a l1 u1 l2 u2 t1 t2 q1 q2 => 
     foralli(u:{(bst_in x t) = tt}).
     case (eqnat x a) by v1 _ with
       ff =>
       case (le x a) by v2 _ with
         ff => [le_trans l1 a x 
                  [le_trans l1 u1 a [bst_bounds l1 u1 t1] q1]
                  [le_ff_implies_le x a v2]]
       | tt => truei
       end
     | tt => truei
     end
  end
\end{verbatim}

\noindent Let us fill in the third subcase, where we have the second
\texttt{truei} in the proof just listed.  We will come back to the
second subcase after that.  In the third case, we are in a situation
where \texttt{(eqnat x a)} has returned \texttt{tt}.  From this, we
should be able to conclude that \texttt{\{x = a\}}, and indeed, there
is a lemma in \texttt{lib/nat.g} to that effect:

\begin{verbatim}
eqnatEq : Forall(n m:nat)(u:{(eqnat n m) = tt}). { n = m } 
\end{verbatim}

\noindent We have $\texttt{l1} \le \texttt{u1} \le \texttt{a}$ using
\texttt{bst\_bounds} and \texttt{q1}, so we just need to use
\texttt{le\_trans} and then congruence to change ``\texttt{a}'' to
\texttt{x}.  The proof in \guru is:

\begin{verbatim}
trans cong (le l *) [eqnatEq x a v1]
      [le_trans l1 u1 a
         [bst_bounds l1 u1 t1]
             q1]
\end{verbatim}

\subsection{The second subcase}
\label{ch8:longpf}

Our proof now looks like this:

\begin{verbatim}
 induction(l u:nat)(t:<bst l u>) return
   Forall(u:{(bst_in x t) = tt}). { (le l x) = tt } with
   leaf _ => 
     foralli(u:{(bst_in x t) = tt}).
     contra
       trans symm u
       trans cong (bst_in x *) t_eq
       trans join (bst_in x leaf) ff
             clash ff tt
     { (le l x) = tt }
 | node a l1 u1 l2 u2 t1 t2 q1 q2 => 
     foralli(u:{(bst_in x t) = tt}).
     case (eqnat x a) by v1 _ with
       ff =>
       case (le x a) by v2 _ with
         ff => [le_trans l1 a x 
                  [le_trans l1 u1 a [bst_bounds l1 u1 t1] q1]
                  [le_ff_implies_le x a v2]]
*      | tt => truei
       end
     | tt => 
       trans cong (le l *) [eqnatEq x a v1]
             [le_trans l1 u1 a
                [bst_bounds l1 u1 t1]
                q1]
     end
  end
\end{verbatim}

\noindent We have one \texttt{truei} left to fill in, on the line
marked (not \guru syntax) with a $*$.  I have saved this subcase
for last, because to prove it, we will make use of a new proof method
in \guru called \texttt{hypjoin}.  Let us try to do the proof with
the methods we know, and see where we run into trouble.  In this 
subcase, we have the following assumptions:

\begin{itemize}
\item \texttt{u: \{(bst\_in x t) = tt\}}
\item \texttt{v1 : \{(eqnat x a) = ff\}}
\item \texttt{v2 : \{(le x a) = tt\}}
\end{itemize}

\noindent This corresponds to the case in our \texttt{bst\_in} code
where we look for \texttt{x} in the left subtree \texttt{t1}, since
\texttt{x} is less than or equal to the data \texttt{a} stored at the
root of the tree \texttt{t}.  So \texttt{(bst\_in x t)} is equal to
\texttt{(bst\_in x t1)} in this case.  Our assumption \texttt{u} tells
us that \texttt{(bst\_in x t)} equals \texttt{tt}, so we can use
\texttt{trans} (and \texttt{symm}) to conclude \texttt{\{(bst\_in x
t1) = tt\}}.  At that point, we may apply our induction hypothesis to
conclude that $\texttt{l1} \le \texttt{x}$.

This informal reasoning is easily formalized in \guru, except for the
step where we prove

\begin{verbatim}
{ (bst_in x t) = (bst_in x t1) }
\end{verbatim}

\noindent Let us try to prove that in \guru using our assumptions
\texttt{u},\texttt{v1}, and \texttt{v2} listed above, and see what
goes wrong.  Certainly our first step is to change \texttt{t} to
\texttt{(node a t1 t2)}, with this proof:

\begin{verbatim}
cong (bst_in x *) t_eq
\end{verbatim}

\noindent Now we have \texttt{(bst\_in x (node a t1 t2))}, and we would
like to prove this equals \texttt{(bst\_in x t1)}.  That is only true,
of course, because of the way the pattern matches go when evaluating
\texttt{(bst\_in x (node a t1 t2))}, as described by our assumptions
\texttt{v1} and \texttt{v2}.  The proof is intolerably verbose:

{\small
\begin{verbatim}
trans join (bst_in x (node a t1 t2)) 
           match (eqnat x a) with
              ff => match (le x a) with
                      ff => (bst_in x t2)
                    | tt => (bst_in x t1)
                    end
           | tt => tt
           end
trans cong match * with
              ff => match (le x a) with
                      ff => (bst_in x t2)
                    | tt => (bst_in x t1)
                    end
           | tt => tt
           end
        v1
trans join match ff with
              ff => match (le x a) with
                      ff => (bst_in x t2)
                    | tt => (bst_in x t1)
                    end
           | tt => tt
           end
      match (le x a) with
        ff => (bst_in x t2)
      | tt => (bst_in x t1)
      end
trans cong match * with
             ff => (bst_in x t2)
           | tt => (bst_in x t1)
           end
        v2
      join match tt with
             ff => (bst_in x t2)
           | tt => (bst_in x t1)
           end
      (bst_in x t1)         
\end{verbatim}
}

\noindent The problem here is we have had to repeat parts of the full
code for \texttt{bst\_in} several times, as we alternate partial
evaluation (via \texttt{join}) and congruence reasoning to take into
account how \texttt{(eqnat x a)} and \texttt{(le x a)} are assumed in
this case to have evaluated.  This is clearly unacceptable, as it
results in a large proof which is dependent on the exact details of
the way \texttt{bst\_in} is written.  Any change to \texttt{bst\_in},
even one which does not change its observable pattern of recursive
calls, will break this proof.  Fortunately, there is a better way.

\section{\texttt{Hypjoin}}

As you have no doubt observed, proof in \guru is largely a very manual
process.  True, \texttt{join} allows us to take fairly large
equational steps all at once, but other than that, we have so far seen
no automation to help us prove theorems, until now.  \guru implements
one fairly powerful automated theorem proving method, called
\texttt{hypjoin}.  The theory and implementation of \texttt{hypjoin}
are due to Adam Petcher~\cite{petcher08}.  The syntax is:

\begin{verbatim}
hypjoin t1 t2 by P1 ... Pn end
\end{verbatim}

\noindent In other words, we give \texttt{hypjoin} two terms,
\texttt{t1} and \texttt{t2}, and as many proofs \texttt{P1} through
\texttt{Pn} as we like, between the \texttt{by} and \texttt{end}
keywords.  Then \texttt{hypjoin} will try to prove that \texttt{t1}
equals \texttt{t2}, using the formulas proved by \texttt{P1} through
\texttt{Pn}.  Those formulas are required to be equations.  The
remarkable property of \texttt{hypjoin} is that, under some natural
assumptions about termination of recursive functions used in
\texttt{t1}, \texttt{t2} and the equations; and assuming the equations
are consistent (a contradiction cannot be derived); then
\texttt{hypjoin} will succeed if and only if there is a proof that
\texttt{t1} equals \texttt{t2} which uses just equational reasoning
(including \texttt{cong}), \texttt{join}, and the given equations.  In
other words, \texttt{hypjoin} is \emph{sound} -- if it claims
\texttt{\{t1 = t2\}} is provable, then it really is -- and also
complete -- if they are provably equal in the way described, then
\texttt{hypjoin} will indeed report that they are.

Here is a very simple example demonstrating the use of \texttt{hypjoin}.
Consider the following theorem about \texttt{le}, called \texttt{leZ} in
\texttt{lib/nat.g}:

\begin{verbatim}
Forall(a:nat). { (le Z a) = tt }
\end{verbatim}

\noindent We can easily prove this by case-splitting on \texttt{a}, and then
using equational reasoning:

\begin{verbatim}
foralli(a:nat). 
  case a with
    Z => trans cong (le Z *) a_eq
               join (le Z Z) tt
  | S a' => trans cong (le Z *) a_eq
                  join (le Z (S a')) tt
  end
\end{verbatim}

\noindent Since the subproofs in the two clauses are both the kind
that \texttt{hypjoin} is supposed to be able to find automatically, we
can use \texttt{hypjoin} to simplify this proof:

\begin{verbatim}
foralli(a:nat). 
  case a with
    Z => hypjoin (le Z a) tt by a_eq end
  | S a' => hypjoin (le Z a) tt by a_eq end
  end.
\end{verbatim}

\noindent In each case, we are instructing \texttt{hypjoin} to try to
join \texttt{(le Z a)} and \texttt{tt}, using the equation proved by
\texttt{a\_eq}.  Essentially, \texttt{hypjoin} evaluates the two terms
just the way \texttt{join} would, but where \texttt{join} would get
stuck pattern-matching on a variable (or other non-value),
\texttt{hypjoin} tries to keep going by replacing the scrutinee of the
pattern-match using one of the equations.  In this example, in the
first case, \texttt{a\_eq} proves \texttt{\{a = Z\}}.  To see how this
works in detail, we need to recall that the definition of \texttt{le} in
\texttt{lib/nat.g} is:

\begin{verbatim}
Define le : Fun(a b:nat).bool :=
   fun (a b: nat). (or (lt a b) (eqnat a b)).
\end{verbatim}

\noindent So \texttt{hypjoin} will evaluate \texttt{(le Z a)} first
like this (writing \texttt{-->*} for evaluation):

\begin{verbatim}
1. (le Z a)}                  -->* 
2. (or (lt Z a) (eqnat Z a))  -->*
3. (or match a with
          Z => ff
       | S a' => tt
       end
       match a with
          Z => tt
       | S a' => ff
       end)                  
\end{verbatim}
          
\noindent The \texttt{match}-terms come from the definitions of
\texttt{lt} and \texttt{eqnat}.  At this point, regular evaluation is
stuck, since we are matching in both cases on a variable, namely
``\texttt{a}''.  But where \texttt{join} would stop here,
\texttt{hypjoin} continues by substituting \texttt{Z} for \texttt{a},
since the proof \texttt{a\_eq} given to \texttt{hypjoin} proves
\texttt{\{a = Z\}}.  So we continue with:
                
\begin{verbatim}
4. (or match Z with
          Z => ff
       | S a' => tt
       end
       match Z with
          Z => tt
       | S a' => ff
       end)                   -->*
5. (or ff tt)                 -->*
6. tt
\end{verbatim}

\noindent The evaluation performed by \texttt{hypjoin} in the other
case is similar, except we end up substituting \texttt{(S a')} for
\texttt{a}.

\subsection{Default clauses}

As a final finishing touch, since the subproofs (of our original proof
for \texttt{leZ}) in the case where \texttt{a} is \texttt{Z} and where
\texttt{a} is \texttt{(S a')} are syntactically identical, we can use
a \texttt{default} clause for the \texttt{case}-proof to write the
subproof just once.  The syntax is that you can begin a
\texttt{case}-proof (or \texttt{match}-term, or
\texttt{induction}-proof) with a clause whose pattern is just
``\texttt{default}''.  The body of the clause will be repeated for all
constructors which do not have a subsequent pattern in the
\texttt{case}-proof.  If the \texttt{default} clause is the only one
given (as it will be in our case here), you must write
``\texttt{default c}'' for the pattern, where \texttt{c} is the type
constructor for the type of the scrutinee.  In this case, \texttt{c} is
just \texttt{nat}, and our proof looks like this:

\begin{verbatim}
  foralli(a:nat).
  case a with
    default nat => hypjoin (le Z a) tt by a_eq end
  end.
\end{verbatim}

\subsection{Finishing the \texttt{bst} proof}

To return to the final missing subcase of our \texttt{bst} proof, we
can replace the page-long proof listed in Section~\ref{ch8:longpf}
with just one call to \texttt{hypjoin}, resulting in this short proof
(invoking the induction hypothesis) for the missing case of our
theorem:

\begin{verbatim}
[t_IH l1 u1 t1 
   symm
   trans symm u
         hypjoin (bst_in x t) (bst_in x t1)
         by v1 v2 t_eq end]
\end{verbatim}

\section{Summary}

We have seen how the \texttt{spec} keyword may be used in \guru to
designate certain argument positions of term constructors or recursive
functions as specificational.  Specificational data and proofs are
treated as annotations (like type annotations from polymorphic
programming), and are dropped during compilation and during theorem
proving.  This greatly reduces clutter when reasoning externally about
dependently typed code.  We have seen how a more general form of
\texttt{induction}-proof is used when doing induction over an indexed
datatype.  We have also seen a rather complex theorem about the
dependently typed function \texttt{bst\_in} for checking if a piece of
data is in a \texttt{bst}.  During the course of our proof, we saw the
\texttt{hypjoin} proof construct, which extends the reach of partial
evaluation as provided by \texttt{join}, to make use of equational
hypotheses proven by a set of proofs given to \texttt{hypjoin}.

\chapter{Resource Management with \carraway}

In the previous chapters, we have seen how to write pure functional
programs and prove properties about them.  Starting with this chapter,
we will consider how to write more realistic programs in \guru than
just pure functional ones.  We will see how to do basic input/output,
and how to implement mutable data structures including arrays.  The
single core issue that it turns out we must address to do this while
retaining the ability to prove properties about \guru code is the
issue of resource management.  Input/output channels, mutable data
structure, and other computational resources can be accomodated in our
functional setting by viewing them as resources to be managed.  In
this chapter, we study resource management in \guru.  Recently, I have
factored out the resource management subsystem of \guru into a
stand-alone tool called \carraway.  \carraway has its own input
language, which is like a simplified version of \guru's, without
proofs, indexed types, and nested functions.  In addition, \carraway
has features which make it possible to describe, as part of the input
to \carraway, a variety of resource management policies.  \guru
programs will be compiled to \carraway programs, which can then be
compiled to C code by the \carraway compiler.

\section{What is a Resource?}

Let us see why the idea of a resource is crucial to implementing
features like mutable state in \guru.  Certain resource management
policies enable us to take a pure functional view of operations on
resources.  The operations as we desire to implement them are not
functional, because they destructively modify the program's state in
some way (as when we update the value in an array) or do not depend
functionally on that state as we normally think of it (as when we get
the time of day, for example).  But if we manage them carefully, their
behavior will be indistinguishable from a different set of operations
which are purely functional.  For efficient execution -- for example,
when we compile code -- we will use the non-functional implementation.
For formal reasoning, however, we can use the functional model.

A simple example, which we will consider in more detail in a later
chapter, is that of mutable arrays.  Suppose there is at most one
reference to a given array at a given point during execution.  In our
functional model, updating a value in the array is done by creating a
new array that is just like the old one, except where it holds the new
value.  In our non-functional implementation, we destructively modify
the array.  If there were a second reference to the array, the value
of that reference would have to change when the array is updated via
the first reference.  Such a change would be a non-local effect:
variable \texttt{x} magically takes on a different value based on
something we have done via variable \texttt{y}.  But if there is only
one reference to the array, our functional and non-functional models
are operationally indistinguishable, since then there is no need for
non-local communication of the fact that the array has changed.

In this array example, it is crucial to ensure that there is at most
one reference to the array.  This property turns out to be crucial to
management of other resources, too.  We will consider a resource to be
something that only one entity can make use of at a time.  This is
true of real-world resources.  For example, consider a bicycle.  We
can view it as a resource, if we consider that only one person can
ride it at a time.  But, you might ask, what if someone sits on the
seat and someone else on the handlebars?  Or what if it is a tandem
bicycle, with two seats?  In that case the bicycle is not a monolithic
resource, but rather consists of several resources: the handlebars and
the seat would each be a resource, and similarly for each of the two
seats of the tandem.  

By viewing a resource as something that only one entity can use at a
time, we get a simple fundamental idea that can form the basis for
managing program resources.  We need one more idea, however, as shown
perhaps a bit more naturally via another example.  Consider a box set
of the Harry Potter books.  We could view each book as a resource, if
we consider that only one person can read it at a time.  (In this case
that is clearly a bit crude, since two people could certainly read
through it together simultaneously, but never mind.)  If you want to
read ``The Sorcerer's Stone'' and I want to read ``The Goblet of
Fire'', there is no problem, since each is a separate resource.  But
what if our friend wants to borrow the whole box set?  That is fine,
as long as all the books are free at the moment.  So in a sense, the
box set is a single resource, consisting of the individual books as
resources.  To use the box set, no one can be using any of the
individual books.  In the general situation, we have one main resource
which consists of several subsidiary ones.  To use the main resource,
none of the subsidiary ones can be in use.  If someone is using one of
the subsidiary resources, we will say the subsidiary resource is
\emph{pinning} the main resource, and that the main resource is
\emph{pinned} by that subsidiary one.  A pinned resource cannot be
used until all the resources pinning it have been returned.

This serves as our basic foundation for resource management in the
\carraway language: resources which can only be used by one entity at
a time, and which can be pinned by other resources.

\section{\carraway Overview}
\label{ch9:overview}

This section gives an overview of the basic concepts in \carraway.
Subsequent sections will go through the syntax and semantics in
detail, via examples.  \carraway input files consist of commands,
similarly to \guru input files.  \carraway commands support three main
activities:

\begin{itemize}
\item Declaring resource types and primitive operations for
manipulating resources of those types (commands \texttt{ResourceType},
\texttt{Primitive}, \texttt{Init}).
\item Declaring datatypes, which may be either inductive datatypes,
for which pattern-matching and the creation of values using the type's
term constructors is allowed; or else unspecified datatypes, which can
then only be created by primitives (command \texttt{Datatype}).
\item Defining functions and global variables (commands \texttt{Function} and \texttt{Global}).
\end{itemize}

\noindent \carraway reads input files ending in ``.w'' and translates
them to C files with the same name except ending instead in ``.c''.
\carraway checks that resources are used properly by functions and
globals, according to the declared resource-managing primitives.  It
emits code to allocate memory cells appropriately when term
constructors are applied.  Cells store a numeric tag identifying which
constructor of the datatype they belong to.  Pattern-matching terms
are translated to C \texttt{switch} statements that switch on that
tag.  Primitives are basic resource-manipulating operations.  A
primitive is specified by giving a \carraway type that shows how it
affects the resources it is given as arguments, along with a piece of
C code that actually implements the primitive.

\carraway's algorithm for checking that resources are used properly is
based on tracking resources to check that there is at most one
reference to a resource at any given time, and that pinned resources
are not used until the resources pinning them have been returned.  To
return a resource, we just \emph{consume} it, which we can think of as
returning it to the underlying runtime system.  To consume a resource,
we either:

\begin{itemize}
\item pattern-match on it (if it is an element of an inductive
datatype), 
\item pass it as an argument to a function whose type declares that it
consumes the resource, or else
\item return it from the function
\end{itemize}

\noindent User-defined functions and primitives have some flexibility
to declare that they do or do not consume certain arguments.
Constructors do not, however: they are considered to consume all their
arguments.  Arguments to functions and primitives may be designated as
treating the resource in one of the following three ways.

\begin{itemize}
\item consuming the resource, including possibly returning it directly
or inside a data structure built with term constructors.  This is the
default.
\item consuming the resource, but not returning it, neither directly
nor inside a data structure.  The annotation for this is a caret (\^{}).
\item not consuming the resource.  The annotation for this is an exclamation
point (!).
\end{itemize}

There is a built-in resource type called \texttt{untracked} for things
that are not resources, and do not need to be tracked.  Additionally,
types are runtime data in \carraway, and values whose classifier is
\texttt{type} are also considered untracked data, not resources.
Functions are not considered resources, and are not tracked if they
are passed to constructors or other functions.

Pattern-matching terms, whose syntax is similar to
\texttt{match}-terms in \guru, consume the scrutinee, unless it has
type \texttt{untracked} or else comes from an input that was marked as
not consumed.  Except in those cases, the pattern-match consumes the
scrutinee either at the end of each case, which is the default; or
else at the start of each case, for which a \$ annotation is used
(between the \texttt{match} keyword and the scrutinee).  \carraway
uses user-specified initialization functions to initialize subdata
extracted in the clauses of a pattern-match.  This allows different
resource management policies to initialize extracted subdata in
different ways.

\textbf{Running \carraway:} The \carraway program is
\texttt{guru-lang/bin/carraway}, which works very similarly to
\texttt{guru-lang/bin/guru}.

\section{Reference Counting for Inductive Data}

The simplest resource management policy implemented in \carraway is
one for managing the memory allocated for elements of inductive types.
Unlike in other functional programming languages, \guru (also
\carraway) does not rely on garbage collection to manage memory
safely.  The reason for avoiding garbage collection is that it can
severely impact performance in memory-pressured situations
(see~\cite{xian08,hertz+05}).  In \guru, all our data are inductive
data.  Since bigger data are built from strictly smaller data, there
can be no cycles in our data.  Define the reference graph of the
program at a particular point in execution as follows.  We will
allocate a cell (piece of memory) for each application of a
constructor.  The set of cells which are reachable from a program
variable is the set of nodes of the reference graph.  There is an edge
from one cell to another if the piece of data corresponding to the
first cell has the piece of data corresponding to the second as one of
its subdata.  So immediately after executing $(S\ Z)$, our reference
graph will have two cells: one for the application of $S$, and the
other for the use of $Z$ (which we should think of here as a
degenerate application of $Z$ to $0$ arguments).  There is a single
edge in the graph, pointing from the cell for the application of $S$
to the cell for the (degenerate) application of $Z$.  With this
definition of reference graph, all executions of all programs have
acyclic reference graphs at all points in time.

Whenever one is guaranteed to have only acyclic reference graphs,
reference counting can be used to manage memory.  In each cell we keep
an integer value, called the \emph{refcount}, which tells how many
references there are to this cell from other cells or from program
variables.  Whenever a new reference is added, we increment the
refcount.  When a reference is dropped -- for example, when the scope
of a local variable referring to the cell ends -- then the refcount is
decremented.  If the refcount falls to $0$, that means the cell is
garbage, since no one is referring to it.  The cell can be recycled in
that case, either by returning it to the runtime system (e.g., by
calling \texttt{free()}), or used for another constructor application.
If the refcount overflows, indicating more than the maximum number of
references we can store with the bits set aside in the cell for that
purpose, then we will treat the cell as \emph{immortal}, and never
recycle it.  This may leak memory, since all those references may
eventually be dropped and we will still not be able to recycle the
cell.  But it will not corrupt memory by recycling a cell that is
really still in use.

A compiler can easily insert code to increment and decrement reference
counts for us.  But executing these increments and decrements at
runtime adds overhead to the execution, which can be avoided in many
cases, as we will discuss.  So \guru and \carraway provide
\texttt{inc} and \texttt{dec} functions, which we programmers use
explicitly to indicate when the reference count should change.  To
make sure that we perform \texttt{inc} and \texttt{dec} operations
correctly, we treat reference counted data as a resource, and track it
with \carraway's reference tracking system, as described next.

\section{Reference Counting in \carraway}
\label{ch9:rc}

In this section, we will see how to describe reference counted data as
a \carraway resource type, and \texttt{inc} and \texttt{dec} as
primitives operating on that type.  The code to do this may currently
be found in \texttt{guru-lang/tests/carraway/unowned.w}.  This file
begins with a declaration of the \texttt{unowned} resource type, for
reference counted data:

\begin{verbatim}
ResourceType unowned with consume_unowned : Fun(A:type)(^ r:unowned).void <<END
  void gconsume_unowned(int A, void *r) {
    dec(r);
    if (op(r) < 256)
      release(A,r);
  }
END
\end{verbatim}

\noindent Here we see an example of the \texttt{ResourceType} command.
We have the name of the resource type, which is \texttt{unowned} in
this case.  Then the \texttt{with} keyword, and then the declaration
of a primitive function for consuming resources of this resource type.
That function must be named ``\texttt{gconsume\_T}'', where \texttt{T}
is the name of the resource type.  The type of that function comes
next, which must be exactly the one given here.  That type says that
\texttt{gconsume\_unowned} is a function that takes in a type as its
first argument, and then an \texttt{unowned} \texttt{r} as its second.
The caret annotation means that \texttt{r} will not be returned by
this function.  The function returns \texttt{void}, which means that
it does not return a value at all.  Finally, there is the punctuation
``\texttt{<<}'' followed immediately by a word (here ``\texttt{END}'')
which will mark the end of the raw C code portion which follows.  This
C code defines how the \texttt{unowned} resource is consumed.  In our
case, we use functions specially provided by \carraway to decrement
\texttt{r}'s refcount.  The refcount is stored in the high 24 bits of
the first word (given by \texttt{op(r)}) of \texttt{r}'s memory cell.
So to check if the refcount falls to $0$, we check whether that first
word falls below 256.  If so, we call another function provided by
\carraway, to return the memory associated with this cell to the
runtime system.  The raw C code, here and for all primitives, is
expected to have the same name as the \carraway one, except with a
``g'' prefixing it.

Next, in \texttt{unowned.w}, we have declarations of primitive
functions for incrementing and decrementing reference counts.  From a
resource tracking perspective, incrementing a reference count creates
a new resource, without consuming the original one; and decrementing
consumes a resource.  This is indicated by the types of the primitives.
The \texttt{inc} function states, using the ! annotation, that it does
not consume its input, but it does produce a new output.  The \texttt{dec}
function states, via the caret annotation (\^{}), that it consumes and
does not return its input.

\begin{verbatim}
Primitive inc : Fun(!y:unowned).unowned <<END
  void *ginc(void *y) {
    inc(y);
    return y;
  }
END

Primitive dec : Fun(A:type)(^y:unowned).void <<END
  #define gdec(A,y) gconsume_unowned(A,y)
END
\end{verbatim}

\noindent Finally, in \texttt{unowned.w}, there is an \texttt{Init}-command
to declare an initialization function for \texttt{unowned} resources.  

\begin{verbatim}
Init ginit_unowned_unowned : Fun(A:type)(! x:unowned)(y:unowned).unowned <<END
  void *ginit_unowned_unowned(int A,void *x,void *y) {
    ginc(y);
    return y;
  }
END
\end{verbatim}

\noindent This function will be automatically used by \carraway to
initialize \texttt{unowned} subdata \texttt{y} when pattern matching
on an \texttt{unowned} scrutinee \texttt{x}.  Since the scrutinee will
be consumed in that case, initialization needs to increment the
subdatum's refcount, since otherwise consumption of the scrutinee
could cause the subdatum also to be consumed.

\section{Programming with Reference-Counted Data}
\label{ch9:prog}

The file \texttt{nat.w} in \texttt{guru-lang/tests/carraway/} gives an
example of a datatype declaration and \carraway programs for
reference-counted unary natural numbers.  The datatype declaration
is somewhat similar to what we have in \guru:

\begin{verbatim}
Datatype nat := Z : unowned | S : Fun(x:unowned & nat).unowned.
\end{verbatim}

\noindent The difference is in the input and output types we give for
the constructors.  Since this is returning reference counted data, the
input and output types are \texttt{unowned} in all cases.  The
notation ``\texttt{unowned\ \& nat}'' indicates that the resource type is
\texttt{unowned} and the datatype is \texttt{nat}.  All
constructors must list datatypes for their input arguments, each
of which (as mentioned above) is considered consumed and possibly
returned by the constructor.  The datatypes are used when we
recycle a cell.

Now, let us finally see some examples of programming with
reference-counted data.  The definitions of \texttt{plus} and
\texttt{mult} are typical.  The code for \texttt{plus} requires
no uses of \texttt{inc} and \texttt{dec} at all:

\begin{verbatim}
Function plus(x:unowned)(y:unowned).unowned :=
  match x with
    Z => y
  | S x' => (S (plus x' y))
  end.
\end{verbatim}

\noindent Let us think about why this code uses resources correctly,
even though it contains no \texttt{inc}s or \texttt{dec}s.  The inputs
\texttt{x} and \texttt{y} are marked as ones that are consumed by
\texttt{plus}, and possibly returned (either directly or in a data
structure).  The pattern match on \texttt{x} consumes it at the end of
each case (as mentioned in Section~\ref{ch9:overview}).  So we are
sure that \texttt{x} is going to be consumed by the time the function
returns.  In the \texttt{Z}-clause, we return \texttt{y}, which as
mentioned in Section~\ref{ch9:overview} is considered a way of
consuming it.  So \texttt{x} and \texttt{y} are consumed in that case.
In the \texttt{S}-clause, we produce a new reference \texttt{x'}.
This is initialized by incrementing its reference count, since this is
what the code given in the \texttt{Init}-command from
\texttt{unowned.w} does (see the previous section).  This reference,
and \texttt{y}, are consumed by the recursive call to \texttt{plus}.
That call produces a new reference, which is consumed by the call to
\texttt{S}, which in turn produces a new reference, which is consumed
by returning it from the function.

Now let us look at the code for \texttt{mult}, where we do need
to use \texttt{inc} and \texttt{dec}:

\begin{verbatim}
Function mult(x:unowned)(y:unowned).unowned :=
  match x with
    Z => do (dec nat y) Z end
  | S x' => (plus (inc y) (mult x' y))
  end.
\end{verbatim}

\noindent In the \texttt{Z}-clause, we need to consume \texttt{y},
because unlike in the \texttt{Z}-clause for \texttt{plus}, we here
return just \texttt{Z}, and drop \texttt{y}.  We use our \texttt{dec}
function from above, in a \texttt{do}-term.  The syntax for those is
just $\texttt{do}\ t_1\ \cdots\ t_n\ \texttt{end}$ (where $n$ is at
least $2$).  This just executes $t_1$ through $t_n$ in order,
returning the value returned by $t_n$.  In the \texttt{S}-clause,
we must call \texttt{inc} on \texttt{y}, since it is used twice.

Let us see what kind of error messages we would get from \carraway if
we left off either of these.  First, suppose we leave off the
\texttt{dec} of \texttt{y} in the \texttt{Z}-clause:

\begin{verbatim}
Function mult(x:unowned)(y:unowned).unowned :=
  match x with
    Z => Z
  | S x' => (plus (inc y) (mult x' y))
  end.
\end{verbatim}

\noindent The error message from \carraway is:

{\small
\begin{verbatim}
"/home/stump/guru-lang/tests/carraway/nat.w", line 20, column 3: simulation error.

Two match-cases consume different sets of earlier references.

1. the first case: gZ

2. the second case: gS

3. a reference created at: "/home/stump/guru-lang/tests/carraway/nat.w", line 17, column 25

4. the first case does not consume it.

5. the second case consumes it at: "/home/stump/guru-lang/tests/carraway/nat.w", line 20, column 27
\end{verbatim}
}

\noindent This message is telling us that the two clauses of the match
have different behavior with regard to references that exist before
the match begins.  \carraway requires that behavior to be the same in
all clauses.  The line and column number mentioned in (3) is (in my
modified \texttt{nat.w} containing this code) is for input variable
\texttt{y}.  The first case does not consume \texttt{y}, as (4)
states; and the second does, as (5) states.  Suppose instead we leave
off the \texttt{inc} of \texttt{y} in the \texttt{S}-clause:

\begin{verbatim}
Function mult(x:unowned)(y:unowned).unowned :=
  match x with
    Z => do (dec nat y) Z end
  | S x' => (plus y (mult x' y))
  end.
\end{verbatim}

\noindent Then the error message from \carraway is the following, which just notes that
we are consuming a resource twice:

{\small
\begin{verbatim}

"/home/stump/guru-lang/tests/carraway/nat.w", line 20, column 13: simulation error.

A reference that was already consumed is being consumed again.

1. the reference created at: "/home/stump/guru-lang/tests/carraway/nat.w", line 17, column 25

2. first consumed at: "/home/stump/guru-lang/tests/carraway/nat.w", line 20, column 21
\end{verbatim}
}

\section{Pinning References and \texttt{owned}}
\label{ch9:pin}

In order to avoid incrementing and decrementing reference counts,
\texttt{owned.w} in \texttt{guru-lang/tests/carraway} defines a
resource type \texttt{owned}, for references which are owned by
another entity, which is thus pinned.  Since they are owned by another
entity, we do not need to decrement their reference counts: the owning
entity cannot be consumed until the owned one is, since the owned one
pins the owning one.  Thus, we cannot get into the situation where the
reference count of the owning entity falls to zero while we are using
the owned entity.  That situation, of course, would jeopardize memory
safety, since recycling the owning cell might cause the owned cell to
be reclaimed as well, while we still have a reference to it.  By
insisting that the owned cell is consumed before the owning cell is,
we ensure this cannot happen.

Here are the \carraway commands defining the \texttt{owned} resource
type and giving the central primitive, \texttt{inspect}, which
operates on \texttt{owned} data:

\begin{verbatim}
ResourceType owned with consume_owned : Fun(A:type)(^x:owned).void <<END
  #define gconsume_owned(A,x) 
END

Primitive inspect : Fun(!x:unowned).<owned x> <<END
  void *ginspect(void *x) {
    return x;
  }
END
\end{verbatim}

\noindent Consuming an owned resource does nothing, as the C code
given for \texttt{consume\_owned} shows (that code is a C macro
definition, defining ``\texttt{gconsume\_owned(A,x)}'' to be nothing,
so such expressions just disappear).  Inspecting an \texttt{unowned}
resource does not consume it: the ! annotation given with the input
\texttt{x} in the \texttt{Fun}-type for \texttt{inspect} shows that.
But the result of \texttt{inspect} is a pinning \texttt{owned}
reference, as indicated by the return type \texttt{<owned x>}.  The
notation for a pinning type is \texttt{<T x1 ... xn>}, where
\texttt{T} is a resource type and \texttt{x1} through \texttt{xn} are
symbols for pinned entities.  Additional primitives for \texttt{owned}
data allow us to pass back to an \texttt{unowned} reference by
incrementing the refcount of the \texttt{owned} data.  This is done
consuming the owned reference with the primitive
\texttt{owned\_to\_unowned}, and not consuming the owned reference
with the primitive \texttt{inc\_owned}.  


\begin{verbatim}
Primitive inc_owned : Fun(!y:owned).unowned <<END
  void *ginc_owned(void *y) {
    inc(y);
    return y;
  }
END

Primitive owned_to_unowned : Fun(^y:owned).unowned <<END
  void *gowned_to_unowned(void *y) {
    inc(y);
    return y;
  }
END

Primitive clone_owned : Fun(! y:owned).<owned y> <<END
  void *gclone_owned(void *y) {
    return y;
  }
END
\end{verbatim}

\noindent 
We can additionally clone an owned reference with
\texttt{clone\_owned}.  Notice that the result of this primitive is a
new \texttt{owned} reference which pins the \texttt{owned} reference
\texttt{y} given to the primitive.  Thus, we can build up chains of
ownership: an unowned \texttt{x} may be pinned by an \texttt{owned}
\texttt{y}, which in turn (thanks to \texttt{clone\_owned}) may be
pinned by an \texttt{owned} \texttt{z}.  \carraway provides the \@
construct to collapse two links in such a chain into one.  In the
situation just described, ``@ \texttt{z}'' will cause \texttt{z} to
pin \texttt{x} directly, and no longer pin \texttt{y}.

The files \texttt{test.w} and \texttt{test2.w} in
\texttt{guru-lang/tests/carraway} give several examples of programming
with \texttt{owned} data.  For example, here is an alternative
definition of \texttt{plus} on unary natural numbers, which manages to
do no decrementing of refcounts at all (in contrast, the code for
\texttt{plus} given in Section~\ref{ch9:prog} will decrement one
refcount for each \texttt{S}-cell of the first argument):

\begin{verbatim}
Function plus2(^ x:owned)(^ y:owned).unowned :=
  match x with
    Z => (owned_to_unowned y)
  | S x' => (S (plus2 x' y))
  end.
\end{verbatim}

\noindent The \texttt{owned} reference \texttt{x} is still consumed by
the \texttt{match}, but consuming an \texttt{owned} reference does not
cause the refcount to be decremented.  When we return \texttt{y} in
the \texttt{Z}-clause, we have to increment \texttt{y}'s refcount,
since it is being consumed, and we have marked \texttt{x} and
\texttt{y} as consumed but not returned (with the caret annotation).
The advantage of marking these as not returned is that when
\texttt{plus2} is called, \carraway's resource tracking algorithm
knows that since these references are definitely gone by the time this
function exits, at that point they will no longer pin any references
they were pinning at the start of the function call.  Notice that if
we returned \texttt{x} or \texttt{y}, it would not be safe to drop
their pins of those other references: \texttt{x} (say) would still
exist in the system, and could still be used to access the pinned
reference.  So it must remain pinned.

Finally, in \texttt{owned.w} there are several \texttt{Init}-commands
for initializing subdata at the start of match cases:

{\small
\begin{verbatim}
Init ginit_unowned_owned : Fun(A:type)(! x:unowned)(y:owned).owned <<END
  #define ginit_unowned_owned(A,x,y) y
END

Init ginit_owned_owned : Fun(A:type)(! x:owned)(y:owned).owned <<END
  #define ginit_unowned_owned(A,x,y) y
END

Init ginit_owned_unowned : Fun(A:type)(! x:owned)(y:unowned).<owned x> <<END
  #define ginit_owned_unowned(A,x,y) y
END
\end{verbatim}
}

\noindent The argument \texttt{x} is always the scrutinee, and the
argument \texttt{y} the subdatum.  The first \texttt{Init} says that
if the scrutinee is \texttt{unowned} and the subdatum is
\texttt{owned}, then the subdatum is still \texttt{owned} following
initialization.  Similarly if the scrutinee is \texttt{owned} instead
of \texttt{unowned} (the second \texttt{Init}).  But if the scrutinee
is \texttt{owned} and the subdatum is \texttt{unowned}, then we
initialize the subdatum to an \texttt{unowned} piece of data which
pins the scrutinee.  So in this case, we propagate the property of
being \texttt{owned} from scrutinee to subdata.

\section{Standard Input}

The file \texttt{stdin.w} in \texttt{guru-lang/tests/carraway/} gives
a simple interface to a textual standard input channel based on the
our resource management ideas.  The file begins by declaring two
opaque datatypes, \texttt{stdin\_t} and \texttt{char}.  These are
opaque in the sense that they are not inductively defined.  We do not
have constructors for them.  The \carraway code is:

\begin{verbatim}
Datatype stdin_t with gdelete_stdin_t : Fun(^x:stdin_t).void <<END
  #define gdelete_stdin_t(x) fclose(x)
END

Datatype char with gdelete_char : Fun(^c:char).void <<END
  #define gdelete_char(c) 
END
\end{verbatim}

\noindent When an opaque datatype is defined, a primitive function to
recycle the memory for elements of that datatype must also be defined.
The datatype \texttt{stdin\_t} is the type for the standard input
channel.  We recycle an element of this type by calling the C library
function ``\texttt{fclose}'' to close the channel.  C programs usually
do not close standard input when they are done with it, but this
example shows how we can use the delete function to return a resource
to the runtime system.  Deleting a character does nothing, since
characters do not occupy heap-allocated memory.

Next in \texttt{stdin.w}, we have a primitive declaration for
\texttt{stdin} itself.  We declare this to be \texttt{unique}, which
is a resource type with no primitives (except to consume the
resource).  This resource type is defined in \texttt{unique.w}, and
can be used for resources where we really require strict unique usage,
without any additional management features like increment and
decrementing refcounts.

\begin{verbatim}
Primitive stdin : unique <<END
  #include <stdio.h>

  #define gstdin stdin
END
\end{verbatim}

\noindent Next, we have primitives to get the current character from
\texttt{stdin}, and to advance to the next character.  Characters,
which have \emph{datatype} \texttt{char}, have resource type
\texttt{untracked}, because they do not require heap-allocated memory.
Hence, they are not really a resource, and we do not need to track
them.  We could, of course, if we needed to do so, but in this case,
it is more convenient not to track them.  To get the current
character, we use \texttt{curc}, which does not consume the
\texttt{stdin} resource.  The C code for \texttt{curc} uses a global
variable called \texttt{curc} to keep track if we have a current
character from \texttt{stdin}, or else need to call the C library
function \texttt{fgetc} to get the next character.  To advance to the
next character, the primitive \texttt{nextc} just clears this global
variable, signaling that the \texttt{curc} primitive should indeed
call \texttt{fgetc}.

\begin{verbatim}
Primitive curc : Fun(!x:unique).untracked <<END

  void *curc = 0;

  int gcurc(void *s) {
     if (curc == 0) {
	int tmp = fgetc((FILE *)s);
	curc = (tmp == -1 ? 0 : tmp);
     }
     return curc;
  }
END

Primitive nextc : Fun(^x:unique).unique <<END
  void *gnextc(void *x) {
    curc = 0;
    return x;
  }
END
\end{verbatim}

\noindent Finally, additional primitives are included to check if a
character marks the end of the file (\texttt{eof}), print a character
(\texttt{printc}) and close standard input (\texttt{close}).  The file
\texttt{stdin.w} then defines functions \texttt{read\_all} to read all
the characters possible from \texttt{stdin} and return them in a
\texttt{ulist} (discussed in a moment), and \texttt{print\_list} to print
all the characters in such a list using \texttt{printc}.

\begin{verbatim}
Primitive eof : Fun(c:untracked).untracked <<END
  int geof(int x) {
    return x == 0;
  }
END

Primitive printc : Fun(c:untracked).void <<END
  void gprintc(int c) {
    putchar(c);
    fflush(stdout);
  }
END

Primitive close : Fun(^x:unique).void <<END
  void gclose(void *s) {
    fclose(s);
  }
END
\end{verbatim}

\section{Lists and Polymorphism}

The file \texttt{list.w} in \texttt{guru-lang/tests/carraway/} defines
two inductive datatypes for lists.  One if for lists of
\texttt{unowned} elements, and the other is for lists of
\texttt{untracked} elements.  While these types are polymorphic in the
\emph{datatype} of the data stored in the list, they are monomorphic
in the resource type of that data.  \carraway does not support
resource type polymorphism at the moment.  Such polymorphism appears
challenging to support, since functions may need to take different
actions depending on the resource types of data, and it is not clear
how to write such functions in a uniform way.  The datatype
definitions for \texttt{list} (\texttt{unowned} elements) and
\texttt{ulist} (\texttt{untracked} elements) are:

\begin{verbatim}
Datatype list := nil : unowned 
               | cons : Fun(A:type)(x:unowned & A)(l:unowned & list).unowned.

Datatype ulist := unil : unowned
                | ucons : Fun(x:untracked)(l:unowned & ulist).unowned.
\end{verbatim}

\noindent These are similar to the datatype definition of \texttt{nat}
(Section~\ref{ch9:prog}), except that the datatype listed for
\texttt{x} in the \texttt{cons} constructor for \texttt{list} is
\texttt{A}, which is the first argument of \texttt{cons}.  When
\texttt{cons} is applied, we must supply an inductive datatype for the
first argument.  That argument will not be thrown away during
compilation, but really used at runtime, so that where we need to
recycle the memory of a \texttt{cons}-cell, we know which function
should be used to consume the resource \texttt{x} (which might require
its memory to get recycled, at which point the datatype it belongs to
must be known).  The \texttt{list.w} file defines \texttt{append} and
\texttt{length} functions for \texttt{list}s.

\section{Exercises}

Note that the \carraway program is \texttt{guru-lang/bin/carraway},
which runs similarly to \texttt{guru-lang/bin/guru}.  If you put your code in \texttt{hw4.w}, you
can process the file with \carraway by running:

\begin{verbatim}
guru-lang/bin/carraway hw4.w
\end{verbatim}

\noindent 
This will create a file call \texttt{hw4.c}.  You can compile that
file using \texttt{gcc} (the Gnu C Compiler) like this:

\begin{verbatim}
gcc -o hw4 -O4 hw4.c
\end{verbatim}

\noindent The ``\texttt{-o hw4}'' part instructs \texttt{gcc} to name
the binary executable it is producing ``\texttt{hw4}''.  The
``\texttt{-O4}'' option tells it to use optimization level 4.

\begin{enumerate}
\item Define a function \texttt{length} computes the length of a \texttt{ulist} (not a \texttt{list}).
Critically, your function definition should begin this way (indicating the input and output resource types):

\begin{verbatim}
Function length(l1:unowned).unowned :=
\end{verbatim}

\item Define an \texttt{append} function on \texttt{ulist}s (again, not \texttt{list}s), beginning like this:

\begin{verbatim}
Function append(l1:unowned)(l2:unowned).unowned :=
\end{verbatim}

\item To test your functions, use a \texttt{Global}-command to write a
piece of code which calls \texttt{read\_all} (from \texttt{list.w}) to
read all the characters from \texttt{stdin} into a \texttt{ulist},
then append that \texttt{ulist} to itself, and finally compute its
length.  A good starting point for this can be found in
\texttt{guru-lang/tests/carraway/test3.w}.

\ 

A few more steps will result in an interesting test.  First, type
\texttt{limit stacksize unlimited} into your shell (if you are using
the default shell, which is \texttt{tcsh}; if you are using
\texttt{bash}, type \texttt{ulimit -s unlimited}).  This raises the
amount of stack memory your program is allowed to consume, which is
necessary in this case.  Run your compiled \texttt{hw4} executable like
this: \texttt{time ./hw4 < shared196/labs/wrnpc11.txt}.  This will cause the
contents of the file \texttt{shared196/labs/wrnpc11.txt} to be sent to
\texttt{stdin} of your \texttt{hw4} program.  Placing \texttt{time} at
the beginning will just cause the running time used to be printed when
the program terminates.

\item Define a \texttt{length} function which instead begins like this:

\begin{verbatim}
Function length(^l1:owned).unowned :=
\end{verbatim}

\item Define an \texttt{append} function which instead begins like this:

\begin{verbatim}
Function append(^l1:owned)(^l2:owned).unowned :=
\end{verbatim}

\item Use a \texttt{Global}-command to write a similar test as the one
of problem (3) for these new functions.  You may wish to put the new
functions and the new test in a separate file.  Test the resulting
executable as for problem (3).  Compare the running time of this
executable with the version from problem (3).

\item Write a function \texttt{sublist}, which takes a \texttt{nat}
\texttt{n} and a \texttt{list} \texttt{l}, and returns the sublist of
\texttt{l} which starts \texttt{n} levels deep in \texttt{l}.  So
\texttt{(sublist (S Z) (cons nat Z (cons nat (S (S Z)) nil)))} should
return \texttt{(cons nat (S (S Z)) nil)}.  Your function should start
this way:

\begin{verbatim}
Function sublist(^n:owned)(!l:owned).<owned l> :=
\end{verbatim}

\noindent Recall that matching on a resource which is marked not to be
consumed will not consume it.  So matching on \texttt{l} will not
consume \texttt{l}.  But the subdata of \texttt{l} will be initialized
according to the initialization rules for \texttt{owned} scrutinees
(see Section~\ref{ch9:pin}).

\item Extra Credit: include the command \texttt{Set "use\_malloc"} at
the top of your test files for problems (3) and (6).  This instructs
\carraway to use the standard C library functions \texttt{malloc} and
\texttt{free} to allocate and deallocate memory (more about this in
Section~\ref{ch10:ind} below).  Again compare the running times of your
programs.  I found that something strange happened for the program for
part (3) when I did this, which I was able to understand by running:

\begin{verbatim}
valgrind hw4 < shared196/labs/wrnpc11.txt
\end{verbatim}

\noindent This command uses the \texttt{valgrind} tool to watch for
memory errors while running the program \texttt{hw4}.  Assuming
you observe the same strange behavior: what is going on?  Is it
a bug in \carraway?

\end{enumerate}

\chapter{Compiling \carraway}

We continue to explore practical programming in \guru by looking at
how to compile the \carraway language, which we are using as an
intermediate language for compilation from \guru to C.  Compilation of
\carraway demonstrates a number of basic ideas in compilation of
functional programming languages, as well as some optimizations
appropriate to our reference-counting approach to memory management
for inductive data.  In the sections below, we describe the
compilation process in \carraway, as it occurs after \carraway's type
checking and resource tracking algorithms have run.  Type checking
inserts calls to the initialization functions for pattern variables in
\texttt{match}-clauses (see Section~\ref{ch9:rc}), and also calls to
\texttt{consume} functions for the scrutinees of \texttt{match}-terms,
as appropriate.  We will not present the type checking and resource
tracking algorithms formally, but assume they have completed
successfully in the subsequent compilation steps.

\section{A Restriction on Functions}

Before we begin describing the compilation process from \carraway to
C, we note one restriction on the use of functions in \carraway.  We
have already mentioned that \carraway disallows the definition of
functions inside other code.  This will have to be enforced by
compilations steps from \guru to \carraway.  But \carraway's type
checker also requires that in every application $(f\ a_1\ \cdots
a_n)$, $f$ is a (declared or defined) constant or variable whose type
explicitly lists that it takes $n$ arguments as inputs.  We will call
this the \emph{argument requirement} on applications.  This simple
property can fail for applications in \guru.  For example, suppose we
are using the type \texttt{<list Fun(x:nat).nat>} of lists of unary
operations on \texttt{nat}s.  That is, the elements of the list are
all functions.  Now if \texttt{l} is such a list, and \texttt{head}
gets the first element if there is one, we can easily write an
application like \texttt{(head Fun(x:nat).nat l one)}, which violates
the restriction just mentioned.  For the type of \texttt{head} states
that it takes two arguments: the type of the list's elements, and the
list.  But here we have applied it to three.

The simple solution to this problem available in \carraway is based on
introducing new names, using \texttt{let}, for terms like
\texttt{(head Fun(x:nat).nat l)} that \carraway's type system cannot
tell are functional.  So we would first transform the offending
application into

\begin{verbatim}
let f = (head Fun(x:nat).nat l) in
  (f one)
\end{verbatim}

\noindent This is not yet enough, since if we proceed with
compilation, \texttt{f} still will not have functional type in
\carraway.  \carraway provides explicit unsafe casts to coerce
\texttt{f} to functional type.  Passing from \guru to \carraway,
we will get:

\begin{verbatim}
let f = cast Fun(x:unowned).unowned
          (head l) in
  (f one)
\end{verbatim}

\noindent We have dropped the type argument to \texttt{head}, since a
list of functions is treated, from the perspective of resource
management, as a list of \texttt{untracked} data.  So the type of
\texttt{(head l)} is just \texttt{untracked}.  We then use a
\texttt{cast} to change the type of \texttt{(head l)} to the
appropriate functional type.  The syntax of \texttt{cast} in \carraway
is \texttt{cast T t}, where \texttt{T} is a type and \texttt{t} is a
term.  Now \texttt{f} does have the proper functional type to be
applied to \texttt{one}.

We will assume below that all applications in our \carraway input
already satisfy the argument requirement, which will thus have to be
imposed during initial compilation steps from \guru to \carraway.

\section{Linearization}

The first step of compilation in \carraway after the type checking and
resource tracking steps is linearization.  This process takes nested
\texttt{let}- and \texttt{match}-terms, which cannot be represented
directly in C code, and flattens them out so that they can be.  For
example, in \carraway (or other functional programming languages), the
following term is syntactically perfectly legal:

\begin{verbatim}
let x = let y = Z in (plus y y) in
  (plus x x)
\end{verbatim}

\noindent But in C code, it is not, if we are translating
\texttt{let}-terms to assignments.  That is, suppose we wish to turn
\texttt{let x = t in t'} into (where we use the C type ``\texttt{void
*}'' as a catchall type for any reference-counted data):

\begin{verbatim}
void *x = t;
t';
\end{verbatim}

\noindent Then we cannot handle nested \texttt{let}-terms directly,
since we cannot generally nest assignments in C in the way that would
be required.  So before generating C code, we must first perform a
transformation that flattens out nested \texttt{let}-terms.  This
transformation should turn a term like the one above containing
\texttt{plus} into something like:

\begin{verbatim}
let y = Z in in
let x = (plus y y) in
  (plus x x)
\end{verbatim}

\noindent We have pulled out the \texttt{let}-term defining \texttt{y}
from the definition of \texttt{x}.  Of course, it needs to come before
the new definition of \texttt{x}, since that definition references
\texttt{y} in \texttt{(plus y y)}.  

A similar problem arises for \texttt{match}-terms.  We would like to
translate these to \texttt{switch}-statements in C, where we switch on
the integer tag (mentioned in Section~\ref{ch9:overview}) stored in
the cell for a piece of inductive data.  That tag tells which
constructor of a given type the cell was built for.  In \guru and
\carraway, it is syntactically legal for one \texttt{match}-term to
appear as the scrutinee of another, as in this example:

\begin{verbatim}
match match w with Z => ff | S x' => tt with
  ff => tt
| tt => ff
end
\end{verbatim}

\noindent But in C, we cannot \texttt{switch} on another
\texttt{switch}-statement.  So we must pull out \texttt{match}-terms
from the scrutinee positions of other \texttt{match}-terms.  We do
this by creating a new C variable to hold the result of the nested
\texttt{match}-term, and then \texttt{match}ing on that new variable

In general, certain constructs cannot appear nested in C, where a
nested position includes the right hand side of an assignment, the
scrutinee of a \texttt{switch} statement, and argument positions of an
application.  Here, the non-nestable constructs we are considering are
just assignments (to which we translate \texttt{let}-terms) and
\texttt{switch}-statements (to which we translate
\texttt{match}-terms).  Wherever these occur in a nested position in a
\carraway term, they must be pulled out to the top-level for
translation to C.

Finally, as mentioned at the very start of the chapter, \carraway's
type checking process inserts calls to the user-specified
initialization functions (Section~\ref{ch9:rc}) for pattern variables
$x$.  Those calls are inserted in the following form, where
\texttt{arg-type} is the run-time type of the argument,
\texttt{scrutinee} holds the value of the scrutinee, and
\texttt{arg-name} is a name used to refer to the argument position
corresponding to the pattern variable $x$, for the given constructor:

\begin{verbatim}
let x = (init_func arg-type scrutinee arg-name) in
\end{verbatim}

\noindent We will assume this insertion has already been done.  This
initialization will subsequently be compiled to access the field
corresponding to \texttt{arg-name} for the memory cell pointed to by
\texttt{scrutinee}.

\subsection{The linearization algorithm}

This section presents \carraway's linearization algorithm \texttt{lin}
as a set of rules.  The rules introduce terms using several
\textbf{intermediate term constructs.} To represent assignments to
variables, we introduce a new term form \texttt{x := t}, where
\texttt{x} is a variable and \texttt{t} is a term.  When executed,
this will store the value computed for \texttt{t} into variable
\texttt{x}.  We temporarily treat \texttt{return} as a function symbol
in linearized output, so that we can write $(\texttt{return}\ x)$ for
the command to return the value of \texttt{x} from a function call.
Also, variable declarations will be represented using a new term form
$\texttt{declare} x$.  

The linearization rules define \texttt{lin} by constraining the form
of calls to \texttt{lin}.  A starting call to \texttt{lin}, with its
result, has this general form:


\[ \texttt{lin}(t,\theta) = t' \]

\noindent The meaning of such a call is that we are linearizing the
\carraway term $t$, and producing the resulting flattened term $t'$.
The argument $\theta$ is used to specify an action to be performed
with the value computed by the term $t$, when it is actually executed
(after compilation).  The options for this action are:

\begin{itemize}
\item Leave the result of computation available for use in a
surrounding C code expression.  For this, we use $\cdot$ as the value
for $\theta$.  We will use this action for $t$ occurring in a nested
position.

\item Store the result of computation in a specified variable, for
which we write $x$ (or $y$) for $\theta$.  We will not use this action
unless the caller of \texttt{lin} will use $t'$ at the top-level (not
in a nested position).

\item Return the value from the function in which $t$ occurs.  For this
we write \texttt{return} for $\theta$.  As for the previous action, we
will ensure that the caller of \texttt{lin} will use $t'$ only at the
top-level, and not in a nested position.

\end{itemize}

\noindent In one situation, where a \texttt{match}-term has type
\texttt{void}, we allow returning $\cdot$ for $t'$, when we know that
will be discarded.

The definition of \texttt{lin} relies on a different, intermediate
form of call to \texttt{lin}:

\[ \texttt{lin}(t,\theta,C,D) = (t',C',D') \]

\noindent
Here, we use $C$ as a list of variable declarations that need to
appear in code before $t'$, and $D$ as a list of extra top-level
commands that need to be executed before $t'$.  When pulling a
\texttt{match}-term out of a nested positions, for example, we need to
introduce a new variable for the result of the \texttt{match}; a
declaration of this variable would be added to the end of $C$.  Also,
we may need to add the \texttt{match}-term itself (modified to write
its value to that new variable) to $D$, since it must be computed
before the value it stores in the new variable is used (by accessing
that variable).  The versions $C$ and $D$ in the call are for those
lists as they exist before the call, and the versions $C'$ and $D'$
are those that have been updated by linearization of $t$.  Adding a
term $t$ to the end of $C$ will be denoted $C,t$, and the empty list
will be denoted $\cdot$.  

The crucial properties of an intermediate call to \texttt{lin} are the
following.  First, executing the concatenation of the declarations in
$C$, then the extra top-level commands in $D$, and then $t$ will have
the same effect as executing the concatenation of the declarations in
$C'$, then the commands in $D'$, and then $t'$.  Furthermore, the
latter concatenation is a linear expression: no nested position
contains a construct which C disallows fromoccurring in such a
positions.  Finally, the value computed by $t$ will be handled by $t'$
as specified by the action $\theta$.

The rules for the algorithm may seem a bit daunting at first.  They
are given in Figure~\ref{fig:lin} for the central \carraway constructs
(a few omitted ones are handled similarly).  We will see examples in
the next section which should help understand how they work.  If calls
to \texttt{lin} above the line (the \emph{premises} of the rule)
return as stated, then the call to \texttt{lin} given below the line
(the \emph{conclusion} of the rule) should also return as stated.  The
rules determine an algorithm by matching the conclusions of the rules
with a given call to \texttt{lin} which is to be executed, and then
executing the calls to \texttt{lin} in the premises of the matching
rule as recursive calls.  At most one rule applies (by matching its
conclusion) to any call to \texttt{lin}, so the algorithm is
deterministic.  In Figure~\ref{fig:lin}, we write $x$ for the base
case of a variable and also a term constructor taking no arguments.
Note that in translating a \texttt{match}-clause (in the second to
last rule of the figure), we do not add declarations for the pattern
variables, since they are \texttt{let}-declared to equal the results
of initialization calls, as explained just before the start of this
section.  Linearizing the \texttt{let}-term will ensure the pattern
variables are indeed declared with \texttt{declare}.

\begin{figure}
\begin{tabular}{l}
\framebox{Rules for the intermediate form of calls:}
\\ \\

\infer{\texttt{lin}(x,\cdot,C,D) = (x,C,D)}{\ }

\\ \\

\infer{\texttt{lin}(x,y,C,D) = (y := x,C,D)}{\ }

\\ \\

\infer{\texttt{lin}(x,\texttt{return},C,D) = ((\texttt{return}\ x),C,D)}{\ }

\\ \\

\infer{\texttt{lin}((f\ a_1\ \cdots\ a_n),\cdot,C_1,D_1) = ((f\ a'_1\ \cdots\ a'_n),C_{n+1},D_{n+1})}
      {\forall i\in\{1,\ldots,n\}, \texttt{lin}(a_i,\cdot,C_i,D_i) = (a'_i,C_{i+1},D_{i+1}) }
\\ \\
\infer{\texttt{lin}((f\ a_1\ \cdots\ a_n),y,C_1,D_1) = (y := (f\ a'_1\ \cdots\ a'_n),C_{n+1},D_{n+1})}
      {\forall i\in\{1,\ldots,n\}, \texttt{lin}(a_i,\cdot,C_i,D_i) = (a'_i,C_{i+1},D_{i+1}) }
\\ \\
\infer{\texttt{lin}((f\ a_1\ \cdots\ a_n),\texttt{return},C_1,D_1) = ((\texttt{return}\ (f\ a'_1\ \cdots\ a'_n)),C_{n+1},D_{n+1})}
      {\forall i\in\{1,\ldots,n\}, \texttt{lin}(a_i,\cdot,C_i,D_i) = (a'_i,C_{i+1},D_{i+1}) }
\\ \\
\infer{\texttt{lin}(\texttt{do}\ t_1\ \cdots\ t_n\ \texttt{end},\theta,C_1,D_1) = (t'_n,C_{n+1},D_{n+1})}
      {\begin{array}{l}
       \forall i\in\{1,\ldots,n-1\},\ \  \texttt{lin}(t_i,\cdot,C_i,D_i) = (t'_i,C_{i+1},D'_i), \ \ \  \ \ D_{i+1} = (D'_i, t'_i) \\
       \texttt{lin}(t_n,\theta,C_n,D_n) = (t'_n,C_{n+1},D_{n+1})
       \end{array}}
\\ \\
\infer{\texttt{lin}(\texttt{let}\ x = t_1\ \texttt{in}\ t_2,\theta,C_1,D_1) = (t'_2,C_3,D_3)}
      {\texttt{lin}(t_1,x,(C_1,\texttt{declare}\ x),D_1) = (t'_1,C_2,D_2) & \texttt{lin}(t_2,\theta,C_2,(D_2,t'_1)) = (t'_2,C_3,D_3)}

\\ \\
\infer{\texttt{lin}(\texttt{match}\ t\ \texttt{with}\ G_1\ |\ \cdots\ |\ G_n\ \texttt{end},\cdot,C_1,D_1) = (y,C_2,(D_2,t'_1,\texttt{match}\ x\ \texttt{with}\ G'_1\ |\ \cdots\ |\ G'_n\ \texttt{end}))}
      {\begin{array}{l}
       \texttt{x}\textnormal{ is a new variable} \\
       \texttt{y}\textnormal{ is a new variable, if the type of the \texttt{match} is not \texttt{void};} \\
       \textnormal{\ \ \ \ and }\cdot\textnormal{ otherwise.} \\
       \texttt{lin}(t,x,(C_1,\texttt{declare}\ x),D_1) = (t'_1,C_2,D_2) \\
       \forall i \in \{1,\ldots,n\}, \ \ \texttt{lin}(G_i,y) = G'_i
       \end{array}}
\\ \\
\infer{\texttt{lin}(\texttt{match}\ t\ \texttt{with}\ G_1\ |\ \cdots\ |\ G_n\ \texttt{end},\theta,C_1,D_1) = (\texttt{match}\ x\ \texttt{with}\ G'_1\ |\ \cdots\ |\ G'_n\ \texttt{end},C_2,(D_2,t'_1))}
      {\begin{array}{l}
       \texttt{x}\textnormal{ is a new variable} \\
       \theta\textnormal{ is not }\cdot \\
       \texttt{lin}(t,x,(C_1,\texttt{declare}\ x),D_1) = (t'_1,C_2,D_2) \\
       \forall i \in \{1,\ldots,n\}, \ \ \texttt{lin}(G_i,\theta) = G'_i
       \end{array}}
\\ \\ \\ \\
\framebox{Rules for the starting form of calls:}
\\ \\
\infer{\texttt{lin}(c\ x_1\ \cdots\ x_n\ \texttt{=>}\ t,\theta) = c\ x_1\ \cdots\ x_n\ \texttt{=>}\ t'}
      {\texttt{lin}(t,\theta) = t'}
\\ \\
\infer{\texttt{lin}(t,\theta) = \texttt{do}\ C\ D\ t'\ \texttt{end}}
      {\texttt{lin}(t,\theta,\cdot,\cdot) = (t',C,D)}
\end{tabular}
\caption{\label{fig:lin}Rules for Linearizing \carraway Terms}
\end{figure}

\subsection{An example execution of the linearization algorithm}
\label{ch10:ex}

Let us see how the linearization algorithm works on an artificial but
representatively tricky example.  The code we wish to linearize is the
following, where for simplicity, I have elided the initialization
terms and the consume terms automatically added to the
\texttt{match}-clauses during type checking:

\begin{verbatim}
Global G = let x = match (plus Z Z) with 
                     Z => Z
                   | S x' => x'
                   end in
             (S x).
\end{verbatim}

\noindent As we discussed above, the \texttt{match}-term nested in the
\texttt{let}-term will not translate directly to legal C code, so we
will rely on linearization to pull it out of this nested position.

We can display a run of the linearization algorithm with a nested
itemized list of calls to \texttt{lin}, where recursive calls (coming
from the premises of rules) issued to compute another call are listed
in the sublist beneath that call.  We will build up such a list
gradually, so we can explain how the rules are applied one at a time.
To begin with, we have our outermost call to linearize the
\texttt{let}-term.  The action we want to use is \texttt{G}: that is, we want
our linearized version of the \texttt{let}-term to write the value of
that term into \texttt{G}.

{\small
\begin{enumerate}
\item \texttt{lin(let x = match (plus Z Z) with Z => Z | S x' => x' end in (S x), G)}
\end{enumerate}
}

\noindent The only rule that can be applied -- i.e., whose conclusion
could match this expression -- is the last rule.  So we get:

{\small
\begin{enumerate}
\item \texttt{lin(let x = match (plus Z Z) with Z => Z | S x' => x' end in (S x), G)}
\begin{enumerate}
\item \texttt{lin(let x = match (plus Z Z) with Z => Z | S x' => x' end in (S x), G,}$\cdot$\texttt{, }$\cdot$\texttt{)}
\end{enumerate}
\end{enumerate}
}

\noindent Now the only rule that could apply is the \texttt{let}-rule.
The first premise of that rule is shown next.  To write the second
premise, we need information computed from the evaluation of the
first, so we defer writing the second premise for a moment:

{\small
\begin{enumerate}
\item \texttt{lin(let x = match (plus Z Z) with Z => Z | S x' => x' end in (S x), G)}
\begin{enumerate}
\item \texttt{lin(let x = match (plus Z Z) with Z => Z | S x' => x' end in (S x), G,}$\cdot$\texttt{, }$\cdot$\texttt{)}
\begin{enumerate}
\item \texttt{lin(match (plus Z Z) with Z => Z | S x' => x' end, x, (}$\cdot$\texttt{,declare x), }$\cdot$\texttt{)}
\end{enumerate}
\end{enumerate}
\end{enumerate}
}

\noindent Now let us separately compute the result for this most
recently introduced call to \texttt{lin}, on the \texttt{match}-term.  Naturally, the only rule
which could apply is the one for \texttt{match}:

{\small
\begin{enumerate}
\item \texttt{lin(match (plus Z Z) with Z => Z | S x' => x' end, x, (}$\cdot$\texttt{,declare x), }$\cdot$\texttt{)}
\begin{enumerate}
\item \texttt{lin((plus Z Z), y, (}$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)}
\end{enumerate}
\end{enumerate}
}

\noindent We will not work through the premises for the rule for applications, but just show the result:

{\small
\begin{enumerate}
\item \texttt{lin(match (plus Z Z) with Z => Z | S x' => x' end, x, (}$\cdot$\texttt{,declare x), }$\cdot$\texttt{)}
\begin{enumerate}
\item \texttt{lin((plus Z Z), y, (}$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)}

\texttt{ = (y := (plus Z Z), }$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)} 
\end{enumerate}
\end{enumerate}
}

\noindent Then here are the other premises for the
\texttt{match}-term, corresponding to the \texttt{match}-clauses.
Notice here how the destination variable \texttt{x} is propagated to
the calls for those clauses, and also how we do not pass the lists of
declarations and extra top-level terms in to those calls:

{\small
\begin{enumerate}
\item \texttt{lin(match (plus Z Z) with Z => Z | S x' => x' end, x, (}$\cdot$\texttt{,declare x), }$\cdot$\texttt{)}
\begin{enumerate}
\item \texttt{lin((plus Z Z), y, (}$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)}

\texttt{ = (y := (plus Z Z), }$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)} 
\item \texttt{lin(Z => Z, x)}
\item \texttt{lin(S x' => x', x)}
\end{enumerate}
\end{enumerate}
}

\noindent We will continue to elide the calls to initialization
functions and consume functions, and just show the results for the
\texttt{match}-clauses:

{\small
\begin{enumerate}
\item \texttt{lin(match (plus Z Z) with Z => Z | S x' => x' end, x, (}$\cdot$\texttt{,declare x), }$\cdot$\texttt{)}
\begin{enumerate}
\item \texttt{lin((plus Z Z), y, (}$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)}

\texttt{ = (y := (plus Z Z), }$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)} 
\item \texttt{lin(Z => Z, x) = \ \   Z => x := Z}
\item \texttt{lin(S x' => x', x) = \ \  S x' => x := x'}
\end{enumerate}
\end{enumerate}
}

\noindent Finally we can finish computing the result for linearization of the entire \texttt{match}-term:


{\small
\begin{enumerate}
\item \texttt{lin(match (plus Z Z) with Z => Z | S x' => x' end, x, (}$\cdot$\texttt{,declare x), }$\cdot$\texttt{)}

\texttt{ = (match y with Z => x := Z | S x' => x := x' end, (}$\cdot$\texttt{,declare x,declare y), (}$\cdot$\texttt{y := (plus Z Z)))}
\end{enumerate}
}

\noindent Note that this result conforms to the properties we
expressed above for intermediate calls to \texttt{lin}, in the sense
that if we do our declarations (of \texttt{x} and \texttt{y}) and then
our extra top-level commands (\texttt{y := (plus Z Z)}), and then the
\texttt{match}-term we have produced; then this will have the same
effect as the original \texttt{match}-term (preceded by its
declarations and extra commands), and also store the result produced
by the \texttt{match}-term in the variable \texttt{x}.

We can now return to finish off the linearization of the
\texttt{let}-term.  We show next the second premise to the
\texttt{let}-rule:

{\small
\begin{enumerate}
\item \texttt{lin(let x = match (plus Z Z) with Z => Z | S x' => x' end in (S x), G)}
\begin{enumerate}
\item \texttt{lin(let x = match (plus Z Z) with Z => Z | S x' => x' end in (S x), G,}$\cdot$\texttt{, }$\cdot$\texttt{)}
\begin{enumerate}
\item \texttt{lin(match (plus Z Z) with Z => Z | S x' => x' end, x, (}$\cdot$\texttt{,declare x,declare y), }$\cdot$\texttt{)}

\texttt{ = (match y with Z => x := Z | S x' => x := x' end, (}$\cdot$\texttt{,declare x,declare y), (}$\cdot$\texttt{y := (plus Z Z)))}
\item \texttt{lin((S x), G, (}$\cdot$\texttt{,declare x,declare y), (}$\cdot$\texttt{y := (plus Z Z),match y with Z => x := Z | S x' => x := x' end))}
\end{enumerate}
\end{enumerate}
\end{enumerate}
}

\noindent The result for this call (to linearize \texttt{(S x)}) is
then \texttt{G := (S x)}, with the same list of declarations, and the
same list of extra commands.  This is returned for item (a).  Finally,
for item (1), we get this final result, which combines the
declarations, extra commands, and the linearized term \texttt{G := (S
x)}:

\begin{verbatim}
do 
  declare x
  declare y
  y := (plus Z Z)
  match y with Z => x := Z | S x' => x := x'
  G := (S x)
end
\end{verbatim}

\section{Compiling Inductive Datatypes}
\label{ch10:ind}

Following linearization, \carraway must also flatten nested function
types, by introducing new type definitions.  We will not discuss this
transformation, but turn to the final major step of compilation, which
is the emission of C code for basic operations on inductive data.
The basic operations are:

\begin{itemize}
\item the allocation of a new cell when a term constructor is applied to its arguments.
\item the reclaiming of the memory for that cell when the cell is no
longer referenced.  We call this operation \emph{deleting}.
\item pattern matching on cells.
\end{itemize}

\noindent All cells that are created during execution of the C code
emitted for a \carraway program will occupy a contiguous chunk of
memory.  The first word of each cell has a special format.  The first
byte (the low 8 bits) holds an integer tag telling which constructor
built the cell.  This tag only needs to differentiate among
constructors for the same datatype, so the restriction to 256
constructors is only a restriction on the number of constructors for
any given datatype.  The total allowed number of constructors for all
datatypes is much larger than this.  The remaining bytes of the first
word of the cell are reserved for resource management.  We will use
them to hold the reference count of the cell.

After this first word of the cell, there is an additional word for
each argument that the constructor takes.  For arguments which are
other reference-tracked data, for example, we will store pointers to
their cells in these fields.  For untracked data such as types or
functions, we will store their values.  In the case of a function,
this is the address of the function, and in the case of a type this is
a distinct integer associated with the type.

For the datatype of unary natural numbers, \carraway will generate
the following C code based on these ideas.  That is, if we run it on
the file \texttt{nat.w} in \texttt{tests/carraway/}, it will produce
a C file called \texttt{nat.c} containing this code:

\begin{verbatim}
#define gnat 2

#define op_gZ 0

#define op_gS 1

typedef struct {
  int opval;
} gnat_gZ;

typedef struct {
  int opval;
  void *gx_12;
} gnat_gS;
\end{verbatim}

\noindent This associates the integer $2$ with the type \texttt{nat},
and then integers $0$ and $1$ with the constructors \texttt{Z} and
\texttt{S}, respectively.  The code then defines C types
\texttt{gnat\_gZ} and \texttt{gnat\_gS}.  These are the types for
cells for uses of \texttt{Z} and applications of \texttt{S},
respectively.  The first word of each cell type is called
\texttt{opval}.  This is the word which holds the constructor tag and
the reference count for the cell.  The field \texttt{gx\_12} in
\texttt{gnat\_gS} corresponds to the single input expected by
\texttt{S}.  The name ``\texttt{gx\_12}'' is derived from the name
\texttt{x} given for that input in the type given for \texttt{S}.

Pattern matching is easily compiled making use of a macro
\texttt{ctor} to extract the low 8 bits of the first word of each
cell, and then \texttt{switch}ing on that value.

\subsection{Allocating, clearing, and deleting with \texttt{malloc}}

The emitted code to allocate a cell for a use of \texttt{Z} and an
application of \texttt{S} respectively, using the C standard library
function \texttt{malloc}, is the following:

\begin{verbatim}
void *gZ() {
  gnat_gZ *x;
  x = (gnat_gZ *)malloc(sizeof(void *)*1);
  x->opval = 256 + op_gZ;
  return x;
}

void *gS(void *gx_12) {
  gnat_gS *x;
  x = (gnat_gS *)malloc(sizeof(void *)*2);
  x->opval = 256 + op_gS;
  x->gx_12 = gx_12;
  return x;
}
\end{verbatim}

\noindent These functions call \texttt{malloc} to request (exactly)
enough memory to hold the cell, and then cast that memory to the
appropriate type (this type cast is done where it says, for example,
\texttt{x = (gnat\_gZ *)...}'').  Finally, the fields of the cell are
filled in.  We add $256$ to the constructor tag, because $256$ puts a
$1$ in the bit $9$ of the first word of the cell.  The refcount starts
(low bits) at bit $9$, so this represents initializing with a refcount
of $1$.

When it is time to reclaim (\emph{delete}) the memory associated with
the cell, the code emitted by \carraway will call a function
\texttt{delete\_gnat}.  This function \emph{clears} the fields of the
cell by consuming their resources as appropriate.  Then it returns the
memory to the operating system (in principle) by calling the C
standard library function \texttt{free}.  Clearing is broken out
separately, because when we manage memory with free lists instead of
\texttt{malloc}/\texttt{free}, we still need to clear cells.  Note
that since there are no fields of a \texttt{Z} cell, clearing such a
cell does nothing, and hence can be macro-defined away.  

\begin{verbatim}
#define clear_gnat_gZ(x) 

void clear_gnat_gS(void *_x) {
  gnat_gS *x = (gnat_gS *)_x;
  gconsume_unowned(gnat, x->gx_12);
}

void delete_gnat(void *x) {
  switch ctor(x) {
  case op_gZ: 
    clear_gnat_gZ(x);
    free(x);
    break;

  case op_gS: 
    clear_gnat_gS(x);
    free(x);
    break;

}
}
\end{verbatim}

\subsection{Allocating, clearing, and deleting with free lists}

One can often obtain significant performance improvements in low-level
code by managing memory directly, without using \texttt{malloc} and
\texttt{free}.  In this section, we describe one example of this
technique, for managing memory for inductive data using our own free
lists.  The idea is that for each constructor, we will keep a list of
cells for that constructor which have been previously freed.  Such a
list is called a \emph{free list}.  When it is time to allocate a new
cell for a use of a constructor, we will first check the constructor's
free list.  If there is a cell available on the free list, we will
remove that cell from the free list, and use it instead of allocating
more memory for the new cell.

There are several subtleties to the implementation of this basic idea
in \carraway.  First, we have the question of how to implement the
free list of cells.  We do not need to waste memory on a list data
structure to hold cells.  We can instead just set pointers from one
cell on the free list to the next, by abusing fields of the cells.
All cells have at least one word, so we will just use word 0 of each
cell as this free list pointer. 

The second subtlety is that we may wish to defer clearing the contents
of the freed cell until it is removed from the free list in response
to an allocation request (let us call this ``reallocation'').  The
reason for wishing to clear cells only when they are reallocated is
for real-time performance.  If we clear cells immediately when they
are deleted, we may cause a large cascade of work, since clearing the
contents of a cell may cause the data pointed to by that cell also to
be deleted.  For example, if those data are reference counted data and
consuming them causes their reference counts to fall to $0$, then they
will be deleted.  So we will not have any upper bound on the amount of
time that a delete operation will take, if we clear cell contents
eagerly, right when the cell is deleted.

In contrast, if we clear cell contents lazily, when the cell is
reallocated from the free list, then we will get an upper bound on the
amount of work needed for all our memory allocation operations.
Deletion is constant time, since we must just place the newly deleted
cell on the appropriate free list.  Allocation is now bounded by the
amount of time needed to clear a single cell, which will in general be
$O(k)$, where $k$ is the number of words in the cell.  

The emitted C code for managing free lists of cells for the \texttt{S}
constructor of the \texttt{nat} datatype is:

\begin{verbatim}
void *free_gnat_gS = (void *)0;

void delete_gnat_gS(void *_x) {
  void **x = (void **)_x;
  x[0] = free_gnat_gS;
  free_gnat_gS = x;
}
\end{verbatim}

\noindent The first line declares the free list
\texttt{free\_gnat\_gS} for cells associated with the constructor
\texttt{S}, and initializes this to $0$, which in C is often used to
represent the empty list.  Then the \texttt{delete} function uses the
statement \texttt{x[0] = free\_gnat\_gS} to abuse word 0 of the cell
\texttt{x} to point to the current start of the free list.  The free
list pointer is then modified to point to \texttt{x}, making
\texttt{x} the new head of the list.  

The delete function for the \texttt{gnat} type is similar to the one
shown before, except now we dispatch to the proper \texttt{delete}
function for the cell's constructor:

\begin{verbatim}
void delete_gnat(void *x) {
  switch ctor(x) {
  case op_gZ: 
    delete_gnat_gZ(x);
    break;

  case op_gS: 
    delete_gnat_gS(x);
    break;

}
}
\end{verbatim}

Finally, we have allocation, which is a little more complex, because
we have to see if our free list has a cell we can reallocate (we
consider here just the code for \texttt{S}, since the code for
\texttt{Z} is similar).  If our free list is indeed non-empty, then we
pull a cell off, and call the global \texttt{clear} function.  Then we
can initialize the cell as before.  If the free list is empty, we must
request memory, ultimately from the operating system, for the new
cell.  This is done using \texttt{carraway\_alloc}, which is a small
and simple wrapper around the standard C function \texttt{brk} for
requesting memory from the operating system.

\begin{verbatim}
void *gS(void *gx_12) {
  gnat_gS *x;
  if (free_gnat_gS) {
    x = (gnat_gS *)free_gnat_gS;
    free_gnat_gS = ((void **)x)[0];
    clear_gnat_gS(x);
  }
  else
    x = (gnat_gS *)carraway_alloc(sizeof(void *)*2);
  x->opval = 256 + op_gS;
  x->gx_12 = gx_12;
  return x;
}
\end{verbatim}

\section{Watching C Code Execute with \texttt{gdb}}

To watch our compiled programs execute, (on linux) we can use the Gnu
debugger \texttt{gdb}.  To use the debugger effectively, we need to
compile the emitted C source file (for example, \texttt{test3.c}
produced by \carraway from the file
\texttt{guru-lang/tests/carraway/test3.w}) like this:

\begin{verbatim}
% gcc -o test3 -O0 -ggdb test3.c
\end{verbatim}

\noindent I recommend running all these commands with the shell's
current directory set (by \texttt{cd}) to the
\texttt{guru-lang/tests/carraway} directory. To start \texttt{gdb} to
debug the \texttt{test3} executable (for example), run the following
from the shell:

\begin{verbatim}
% gdb test3
\end{verbatim}

\noindent This will put you into shell-like interaction with
\texttt{gdb}.  Here is a quick summary of the \texttt{gdb} commands I
think you will need (for example, for the homework):

\begin{itemize}
\item \texttt{run} (this can be abbreviated \texttt{r}): start the program running.
The program will execute as normal, unless you have set a breakpoint, as explained
next.

\item \texttt{break main} (can be abbreviated \texttt{b main}): set a
breakpoint at the start of the \texttt{main} function, which will put
you right at the beginning of execution of the program.  You can use a
similar command with another function besides \texttt{main}
(e.g. \texttt{break ginc}).

\item \texttt{where}: print the file name and line number where the
current point of execution is (assuming the program is running and has
stopped at a breakpoint).

\item \texttt{list} (can be abbreviated \texttt{l}): show a few lines
of source code around the current point of execution.

\item \texttt{next} (can be abbreviated \texttt{n}): take a single step
forward of execution, but do not enter function calls if the current point
of execution is at the start of one.

\item \texttt{step} (can be abbreviated \texttt{s}): like
\texttt{next}, except we will enter a function call if the current
point of execution is at the start of one.

\item \texttt{print x} (can be abbreviated \texttt{p x}): print the current
value of C code expression \texttt{x}.  

\item \texttt{continue} (can be abbreviated \texttt{c}): resume execution.

\end{itemize}

\noindent The keystroke sequence ``Control-p'' will, just as in the
shell, print the previous command from the list of previous
\texttt{gdb} commands (and if entered again, print previous commands
before that one); and ``Control-n'' will print a subsequent command
from the current point in the list of previous \texttt{gdb} commands.

You can also use a graphical debugger like \texttt{kdbg}, which is
just a wrapper around \texttt{gdb}.  One note about \texttt{kdbg}: the
window labeled ``program output'' also accepts program input.

\section{Exercises}

Most of the exercises below are designed to get you familiar with the
\carraway compilation by having you explore the C code emitted for
compilation of \texttt{guru-lang/tests/carraway/test3.w}.  You are
free to use any means necessary to answer the following questions,
including modifying the generated C code by hand, or running
\texttt{gdb}.  Another useful tool, at least when the emitted code is
using \texttt{malloc}/\texttt{free} instead of free lists, is
\texttt{valgrind}, which runs a program and monitors its memory usage.
You can run \texttt{valgrind} on \texttt{test3}, for example, like
this:

\begin{verbatim}
% echo "hi" | valgrind ./test3
\end{verbatim}

\noindent As a final note, if you give the \texttt{gcc} compiler the
``\texttt{-w}'' command-line option, it will not print any warning
messages.

\begin{enumerate}

\item At the top of \texttt{test3.w} is a \texttt{Set}-command, to set
the compiler flag \texttt{use\_malloc}.  First, make sure this command is
uncommented (so it will actually be executed).  Then compile \texttt{test3.w},
and run it like this:

\begin{verbatim}
% echo "hi" | ./test3
\end{verbatim}

\begin{enumerate}

\item Using \texttt{gdb}, print the contents of the cell corresponding
to \texttt{s} from the definition of \texttt{main} in
\texttt{test3.w}, right after the call to \texttt{read\_all}.  To do this,
you can use the command:

\begin{verbatim}
(gdb) p *(the_type *)gs
\end{verbatim}

\noindent where you must fill in \texttt{the\_type} with the
appropriate C type describing the cell.  The notation
``\texttt{(the\_type *)gs}'' is C notation for type-casting
\texttt{gs} to have the type ``\texttt{the\_type *}''.  The star in
front of that (just after the ``\texttt{p}'') then shows the contents
of the cell.  Explain why the values you see for the fields of this
cell make sense, given the explanation of Section~\ref{ch10:ind}
above.

\item How many times is a reference count incremented by this run?
How many times is a reference count decremented?  Explain why it makes
sense that you see those numbers.

\item How many bytes of memory are allocated per character in the input string?  Justify
your answer experimentally, and explain why it makes sense.

\end{enumerate}

\item This problem concerns a file \texttt{test3a.w}, which is very
similar to \texttt{test3.w}, except that it has commented out the
\texttt{Set}-command at the top, so that the compiler flag
\texttt{use\_malloc} will not be exectued.  Also, it has an extra
allocation it does in \texttt{main}.  Compile \texttt{test3a.w}, and
run it as before, by \texttt{echo}ing into it the input string "hi".
Note that using \texttt{echo} will ensure that there is no newline
character included in the input; including such would change the
answers to the questions below.  An alternative would be to put "hi"
into a test file \texttt{data}, and then run

\begin{verbatim}
% cat data | ./test3a
\end{verbatim}

\noindent An advantage of that approach is that within \texttt{gdb}, you
can run the program being debugged on the \texttt{data} input file with
this command:

\begin{verbatim}
(gdb) r < data
\end{verbatim}

\begin{enumerate}

\item Draw a boxes-and-pointers diagram of the free list
\texttt{free\_gulist\_gucons} as it exist immediately after the call to
\texttt{(dec ulist s)} in \texttt{test3a.w}.  A box is drawn for a
cell, and a pointer is drawn between cells if the first cell
references the second.  Show any cells reachable from other pointers
(besides the free list pointers) from the cells in the free lists.
Associate a unique number with your boxes (e.g., their address in
memory), that you can refer to in the next part.

\item Show the state of memory, including free lists and the list
produced by the call to \texttt{(ucons tt unil)}, right after that
call to \texttt{ucons} (and before the next call to \texttt{dec}).

\end{enumerate}

\item Show, in step by step fashion as in Section~\ref{ch10:ex}, how this call to \texttt{lin} is
computed, including (of course) the final linearized term it produces:
\[
\texttt{lin(let x = let y = Z in (S y) in (S x), }\cdot\texttt{)}
\]

\end{enumerate}

\bibliographystyle{plain} \bibliography{the-bib}

\end{document}
