\documentclass[12pt,a4paper]{article}

\usepackage{verbatim}
\usepackage{alltt}

\ifx\pdfoutput\undefined
\usepackage[a4paper,ps2pdf,hypertex,pagebackref]{hyperref}
\usepackage{epsfig}
\else
\usepackage[pdftex]{graphicx}
\DeclareGraphicsExtensions{.pdf}
\usepackage{epsfig}
\usepackage{thumbpdf}
\usepackage[a4paper,pdftex,pagebackref]{hyperref}
\pdfadjustspacing=1 
\fi

\makeatletter
\def\magcommand#1{%
   \@ifnextchar[{\longmagcommand{#1}}{\shortmagcommand{#1}}}

\def\longmagcommand#1[#2]#3{%
   \subsection{\texttt{#1}}
   \begin{itemize}
   \item
   Syntax: \texttt{#1} {\em #3}
   \item
   Command line option: \texttt{--#2} {\em #3}
   \end{itemize}
}

\def\shortmagcommand#1#2{%
   \subsection{\texttt{#1}}
   \begin{itemize}
   \item
   Syntax: \texttt{#1} {\em #2}
   \end{itemize}
}

\input{version.tex}

\bibliographystyle{plain}

\begin{document}
\title{MAG version \magversion : User Manual}
\author{Ganesh Sittampalam and Oege de Moor}

\maketitle

\tableofcontents

\section{About this document}
This manual is intended to provide up-to-date 
usage instructions and a syntax description of the syntax for MAG 
version~\magversion,
but is not intended to serve as a tutorial in writing MAG programs. See 
section~\ref{otherinfo} for a description of other documents that may help
with this. Some familiarity with Haskell is recommended before using MAG.

MAG is a joint work by Ganesh Sittampalam and Oege de Moor, but all blame
for the brevity of this manual should be directed at Ganesh, who will try
to respond to requests for additional help: \texttt{ganesh@comlab.ox.ac.uk}.

\section{Introduction}
\label{introduction}
MAG is a program transformation system for a small functional language
similar to Haskell. The main features it provides are:
\begin{itemize}
\item
The ability to write {\em active source}: source code that actively takes part 
in the compilation process by providing instructions to the compiler on how to
optimise it.
\item
An implementation of {\em higher-order conditional rewriting} which makes
use of certain {\em higher-order matching} algorithms developed by the 
authors.
\end{itemize}
In particular, MAG is able to automate {\em fusion} (sometimes also known as 
{\em promotion}) transformations, which provide a framework for safely
transforming certain kinds of recursive programs. For example, the well-known
{\em fast reverse} transformation can be expressed by the following MAG 
source code:

\small\verbatiminput{../examples/reverse.p}

Essentially, this source file provides the slow program for \texttt{reverse} 
together with instructions for mechanising the fast reverse optimisation. 
The syntax used is explained in section~\ref{syntax}.

\section{Compiling}
Binary distributions of MAG are available for Linux/x86, Cygwin/x86,
FreeBSD/x86, Solaris/Sparc. If you use one of these distributions, you
can ignore the rest of this section.

MAG is entirely Haskell '98 code. The recommended environment for using MAG
is GHC, for performance reasons, but it can also be used under Hugs. 
It should also build with NHC, but this has not been tested recently.
Whichever environment is used, a reasonably recent version of GHC is required
for dependency calculation.

MAG compiles successfully with either GHC 5.02.2 or GHC 4.08.2 
on all platforms it has been tried with, which are the same platforms for 
which binary distributions are provided.
It also works with the February 2001 release of Hugs.

\section{Installing}

If MAG is being used by a single user, it is recommended to run it from the
directory it is untarred into. If being installed by the system administrator
for multiple users, the \texttt{mag} script and \texttt{magdcalc} binaries from
the \texttt{bin} directory should be placed in \texttt{/usr/local/bin} or 
\texttt{/usr/bin}, and the \texttt{.p} files from the \texttt{examples} 
directory
should be placed in \texttt{/usr/local/share/mag} or \texttt{/usr/share/mag}.
Appropriate files from the \texttt{doc} directory should go into whatever
directory is mandated by local policy -- often 
\texttt{/usr/local/doc/mag-\magversion} or 
\mbox{\texttt{/usr/share/doc/mag-\magversion}{.}}

\section{Quick usage guide}
\label{quickstart}

The above example \texttt{reverse.p} can be run by changing to the 
\texttt{bin} directory and running the following command (change the paths
appropriately if the installation is system-wide):
\begin{alltt}
./mag --program ../examples/reverse --transform fastrev showprogram
\end{alltt}


\section{Syntax of MAG programs}
\label{syntax}

A MAG program consists of a list of {\em definitions} and 
{\em transformations}. A definition can be a (possibly partial) function
declaration, such as:
\begin{alltt}
reverse [] = [];
\end{alltt}
It can also be a data declaration, for example:
\begin{alltt}
data Tree a = Leaf a | Node (Tree a) (Tree a);
\end{alltt}
There is no ``layout'' rule, so all definitions and transformations must
be terminated with a semicolon.

The left-hand side of a function declaration is a name followed by a list
of arguments, some or all of which may be patterns (such as \texttt{[]}).
The right-hand side is an expression built up from variables, constants,
$\lambda$-abstractions, applications and \texttt{let} expressions, which have
the same syntax as in Haskell.

A transformation is introduced by the keyword \texttt{TRANSFORM}, together
with a name for the transformation. This name can optionally be followed by
a colon together with a comma-separated 
list of transformations on which this transformation depends.

Then next element of a transformation is the keyword \texttt{REDEFINE},
followed by a semicolon-separated list of definitions, and then the keyword
\texttt{SPECIFYING} and another semicolon-separated list of definitions. The
final part is the keyword \texttt{USING} and a semicolon-separated 
list of {\em rewrite rules},
and the transformation is terminated by the keyword \texttt{END} (and a 
final semicolon).

A rewrite rule is either the keyword \texttt{DEFINITION} followed by a 
comma-separated list of function names, or
a name, a colon, an expression denoting the left-hand
side of the rule, an equals sign, and an expression denoting the right-hand 
side. In the latter case it can optionally be followed by a comma, the 
keyword \texttt{if},
and a comma-separated list of {\em side-conditions}, enclosed in curly braces.
Each side-condition consists of two expressions separated by an equals sign.

See section~\ref{introduction} for an example of a transformation.

\section{Using MAG}
To run MAG in interactive mode, 
execute the \texttt{mag} script from the \texttt{bin} directory.
You will see the following banner:
\begin{alltt}
MAG version \magversion (built on \magdate)
\end{alltt}
This will be followed by the MAG command prompt:
\begin{alltt}
Mag>
\end{alltt}
A number of commands can be executed from this prompt. After each command 
completes, MAG returns to this prompt. Some commands can also be specified
from the command-line, in one of two ways:
\begin{itemize}
\item
Some commands have command-line versions. Any number of these commands
can be specified, and they will be executed in the order they occur.
\item
The final element of the command line can be any MAG command except 
\texttt{quit}. If a command is specified in this way MAG will execute any 
commands specified by \texttt{--} options, then this command, and then exit
without offering a command prompt.
\end{itemize}

\magcommand{loadprogram}[program]{filename}

Loads, parses and type-checks {\em filename}\texttt{.p}.

\magcommand{applytransform}[transform]{transformation}

Applies {\em transformation} to the currently loaded program, and leaves
the transformed program loaded.

\magcommand{showprogram}{}

Prints out the currently loaded program.

\magcommand{setwidth}[width]{width}
Set the output width (in characters) for calculations and programs.
If you set this too low some output may be replaced by \texttt{*}s if it cannot
be formatted to fit. The initial value for this setting is 80.

\magcommand{setpath}[path]{path}
Set the base path from which programs, theory files and scripts are loaded.
The path should be enclosed in quotes. The initial value is the empty string.

\magcommand{runscript}[run]{filename}
Load and run the specified script. The filename should be enclosed in quotes.

\magcommand{skip}{}
Do nothing. Intended for scripts, etc.

\magcommand{quit}{}
Exit the interactive loop or the current script. An EOF will have the 
same effect, so there is no need to end scripts with this command, and 
\texttt{\^{}D} can be used to exit the interactive loop.

%\magcommand{debugfile}[debug]{htmlfile}
%Set a file for HTML debugging output of the rewriting process to be sent to.



%\magcommand{simplematch}{pattern term}

%\magcommand{onestepmatch}{pattern term}

%\magcommand{twostepmatch}{pattern term}

%\magcommand{setmatcher}{matcher}

%\magcommand{loadtheory}[theory]{filename}

%\magcommand{showtheory}{}

%\magcommand{choosetheory}{transformation}

%\magcommand{rewrite}{expression}

\section{Known Bugs}
\begin{itemize}
\item
Many error conditions cause MAG to exit, often with a cryptic error message,
instead of catching it and returning to the command prompt.
\item
The \texttt{mag} script in the \texttt{bin} directory does not work when 
accessing a cygwin machine via ssh.
\end{itemize}

\section{Other information}
\label{otherinfo}
The most up-to-date account of the ideas underlying MAG can be found in~\cite{demoorags03fop}.
A more detailed account of the underlying theory can be found in~\cite{sittampalam01thesis}.
Other descriptions, which have in the main been superseded by these documents, can be found
in~\cite{demoorags98,demoorags99,demoorags01pado}.

\bibliography{mag}
\end{document}
