\documentstyle[11pt]{article}
\begin{document}
\parskip = 4pt
\sloppy

\begin{center}
{\Large \bf
Macaulay Release Notes \\
11 September 1994
}\end{center}

\newcommand{\mac}{{\it Macaulay\,}}
\newcommand{\std}{Gr\"obner}

{\bf [1 October 93]}
Section 1 describes recent improvements to \mac. Section 2 describes
a new stand-alone version for the Macintosh; the Macintosh {\tt MPW}
tool (which requires the {\tt MPW} shell) remains available. Section 3
describes an experimental command processor which can be accessed
within \mac, the ``dot mode''. We do not guarantee that
its definition in future versions will be backward-compatible with this
version, but we welcome all comments from people who decide to use
it anyways.

{\bf [Added 12 March 94]}
A bug has been fixed in the {\tt hilb\_numer} command. {\tt row\_deg}
and {\tt col\_deg} have temporarily been added as abbreviations for
{\tt row\_degree} and {\tt col\_degree}. The relevant paragraphs are
marked like this paragraph. There may be a bug in the {\tt hilb}
command on DECstations when \mac\ is compiled using the native C
compiler; the work-around for now is to use {\tt gcc} instead.

{\bf [Added 11 Sep 94]}
Three new commands have been added: {\tt monoms}, {\tt binoms}, and
{\tt monprimes}. They are described below. The temporary commands {\tt
row\_deg} and {\tt col\_deg} have been removed, and are no longer
needed for scripts distributed with \mac.

\section{Changes}

\subsection{Command names}

The preferred form for multiword command names (such as {\tt
ring\_sum}) is now to use {\tt \_} instead of {\tt -} to connect words;
the old forms (e.g. {\tt ring-sum}) are still supported, except with the
new dot command processor described in Section 3. The Macintosh {\tt
MPW} shell script {\tt Replace\_Dashes} can be used to automatically
update scripts.

Command abbreviations must now match a unique command to stand
for that command. Otherwise, a list of possible continuations is given:

\begin{verbatim}
% rin
ring
ring_from_cols
ring_from_rows
ring_sum

; ambiguous command: rin
\end{verbatim}

This can be useful as an alternative to the {\tt commands} command,
for groping for a particular command name. The error messages for
ambiguous and not found commands now give the command name, to
ease debugging silent scripts.

{\bf [Added 12 March 94]} Script writers may find that the previous
code for handling command abbreviations made arbitrary choices in
their favor. The current code refuses to make arbitrary choices. This
broke many scripts which used {\tt col\_deg} or {\tt row\_deg} when {\tt
col\_degree} (not {\tt col\_degs}) and {\tt row\_degree} (not {\tt
row\_degs}) was intended. For now, {\tt col\_deg} and {\tt row\_deg} have
been added as official abbreviations for {\tt col\_degree} and {\tt
row\_degree}, respectively. At some point in the future {\it all\,}
abbreviations in scripts will be disallowed, to guarantee room for
ongoing expansion of the name space.

{\bf [Added 11 Sep 94]} {\tt col\_deg} and {\tt row\_deg} have been
removed as official abbreviations; they are no longer needed for
scripts distributed with \mac. Abbreviations in scripts are still
allowed, but are a terrible idea, and will probably inhibit
portability to new platforms such as DOS.

\subsection{Optional script arguments}

Scripts can now refer to arguments not provided by the caller; such
references are replaced by a null string. This was not made a user
option, so script writers could depend on this as a feature. This eases
coding of optional arguments in scripts, such as providing an optional
characteristic to {\tt <ring}. See the new version of {\tt <ring}:

\begin{verbatim}
% <ring 3 a-z r
% <ring 3 a-z r 2 ; sets characteristic to 2
\end{verbatim}

\subsection{Logical operators}

{\tt ||} and {\tt \&\&} are now allowed in integer expressions,
representing logical {\bf or} and {\bf and}. They associate left to right,
with precedence below equality testing. This eases coding of optional
arguments in scripts, as in

\begin{verbatim}
		if #0==3||#0==4 START
\end{verbatim}

{\tt ==} can now be used interchangeably with {\tt=} for equality
testing. {\tt ==} is preferred, and will be the only form allowed in the
dot command processor when logical operators are added there,
because {\tt =} is used for assignment. ({\tt \%} cannot replace {\tt \&}
for modulo, because it is handled specially as \mac's prompt
character.)
 
The complete set of operators for integer expressions are now:
\begin{verbatim}
* ** / | || & && ^ ( ) + - > >= < <= = == ! !=
\end{verbatim}

\subsection{The {\tt spare} command}

The {\tt spare} command has been added as an alternative to the
{\tt kill} command in scripts. {\tt spare} kills all {\tt @} variables at
the current level except those given as arguments:

\begin{verbatim}
spare @a @b
\end{verbatim}

The {\tt spare} command ignors {\tt 'zero} variables (don't ask!). The
{\tt listvars} command no longer lists {\tt 'zero} variables when
called with no arguments. (We still need to take care of killing {\tt
'zero} variables when they have outlived their purpose.)

\subsection{The {\tt binoms} command [Added 11 Sep 94]}

The {\tt binoms} command produces binomials from the columns
of a matrix. In its simplest form the matrix consists of constants,
and the positive constants in each column yield the exponents of one
monomial, while the negative constants yield the exponents of the
other, difference monomial. More generally, the matrix may consist of
polynomials, and the sum of the coefficients of each entry are used to
produce an exponent.

This command may produce surprising results in small characteristics.
Nevertheless, one shouldn't cringe at using an integer mod $p$ as an
exponent; {\it all} integers inside a computer are represented mod
some number, and this is at least a number we can control.

\begin{verbatim}
% binoms
binoms <matrix> <ideal> <result>
% type a
0 1 2 3 
1 1 1 1 
% type r
a b c d 
% binoms a r b
% type b
b-1 ab-1 a2b-1 a3b-1 
% homog b c b
% res b c 2
0.1.2..3..4..
computation complete after degree 4
% type c.2
-ab+c2 ac   a2c+ac2   
b-c    -a-c -a2-ac-c2 
0      1    0         
0      0    1         
% binoms c.2 r d
% type d
0 -b2+ac -b3+a2d 
\end{verbatim}

This example is meant to be a tease. Try varying the order, and
using an entire \std\ basis of syzygies.

\subsection{The {\tt monoms} command [Added 11 Sep 94]}

The {\tt monoms} command is identical to the {\tt binoms} command,
except that it creates monomials from the positive sums
of coefficients, ignoring the negative sums of coefficients.

\begin{verbatim}
% monoms
monoms <matrix> <ideal> <result>
% type a
0 1 2 3 
1 1 1 1 
% type r
a b
% monoms a r b
% type b
b ab a2b a3b 
\end{verbatim}

\subsection{The {\tt monprimes} command [Added 11 Sep 94]}

The {\tt monprimes} command creates a 0-1 matrix whose columns
correspond to the isolated primes of the initial monomial ideal of its
argument. Each 1 indicates that the corresponding variable is a
generator of the prime ideal given by that column.

{\tt monprimes} uses the lead terms of a \std\ basis if available.
Otherwise, it uses the lead terms of the generating set without
protest, to facilitate decompositions of arbitrary monomial ideals.

 \begin{verbatim}
% monprimes
monprimes <standard basis> <result>
% <ideal a ab ac ad bd cd
% monprimes a b
% type b
1 0 1 
0 1 1 
0 1 1 
1 1 0 
\end{verbatim}

\subsection{The {\tt hilb\_numer} command}

The new {\tt hilb\_numer} command takes a \std\ basis and a ring
map from the variables of its base ring to a target ring. It creates the
numerator of the Hilbert series generating function, in the target ring.
This can be used to get at the full $n$-variable generating
function, to work with bigradings, and so forth.

\begin{verbatim}
% hilb_numer
hilb_numer <standard basis> <ideal> <result>
% <ring 3 abt r
% <ideal i a2 ab b2
% <ideal f t t t
% std i j
23.
computation complete after degree 3
% hilb_numer j f k
% type k
2t3-3t2+1
% hilb_numer j r k
% type k
a2b+ab2-a2-ab-b2+1 
\end{verbatim}

This numerator makes sense in characteristic zero, over a
polynomial ring. Computing it in low characteristics, or over a {\tt
qring}, may lead to absurd results. 

Providing a map to {\tt hilb\_numer} is more efficient than collecting
the raw multivariate numerator, and applying a map to it afterwards.
This code maps to the target ring term by term as each term
is created, adding or subtracting in the target ring.

{\bf [Added 12 March 94]}
An earlier bug has been fixed, which sometimes crashed \mac\ when the
target ring was different from the base ring of the \std\ basis.

\subsection{Out-of-memory handling}

\mac\ now runs out of memory more gracefully. It saves roughly
12K of memory for coming back up for air the first time, and can
process subsequent lines of an input file successfully, such as a {\tt
betti} command following a {\tt res} command that runs out of memory.
The {\tt abort} set variable now increments on each out of memory, so
infinite loops are no longer possible. (In the past, \mac\ could fill a
hard disk with an infinite loop of useless output after running
out of memory, wearing out its welcome on various departmental
facilities! This can no longer happen.) ``{\tt grep -i rainy}'' to see source
code changes.

A {\tt cache\_mem} command has been added, to allow user control of
this reserve memory. It can be used to save more than the default
choice, to provide for recursive out-of-memory rescues, and to
provide for subsequent calculations. This command recycles any
current holdings, if any, then caches the requested amount for the next
out-of-memory. {\tt cache\_mem} takes two arguments,
representing two kinds of memory. Intelligent use will require
experimentation. {\tt cache\_mem} with no arguments gives help and
current holdings (an allocator block is 4400 bytes):

\begin{verbatim}
% cache_mem
cache_mem <internal allocator blocks> <K's for malloc>
(currently reserving 2 blocks, and 4K for malloc)
\end{verbatim}

\subsection{Ring characteristics}

The {\tt ring} command now translates characteristics of -1 to -20 to
the first 20 primes less than $2^{15}$. (The default 31991 doesn't even
come close to making this list!) It also checks any characteristic
between 1 and 101 against another list to see if it is actually prime.

\subsection{Verbose mode}

\mac\ now buffers output in verbose mode, in an attempt to
speed up verbose mode, which is still roughly 10\% to 20\%
slower than non-verbose mode, depending on the system. The new set
variable {\tt iodelay} maintains the value in system ticks (usually
60th's of a second) used to determine the minimum period between
verbose calles to {\tt fflush()}. Its default value is 60.

\subsection{Output handling}

The {\tt shout} command now calls {\tt fflush()}, so output can serve
real-time diagnostic purposes such as indicating the progress of a
script. This makes a difference only when output is not line-buffered,
as on a Macintosh.

All warnings now call {\tt print()},  not {\tt prerror()}, so they stay
silent in scripts. (The only warnings needing this change were those
warning of inhomogeneity.)

\subsection{Path handling}

Setting \mac's file search path has been made more flexible, in part to
support the stand-alone Macintosh version described in Section 2. The
search path can be bootstrapped in a number of optional steps
described  below, or all but any one method can safely be ignored.

The search path is used to open files for reading, unless the file name
contains a {\tt /} character (Unix), or a {\tt :} character (on the
Macintosh), in which case the file name is used verbatim. The file name
is always used verbatim when opening files for writing, unless the
current directory mechanism (described later) is used.

 Recall that a typical search path for Unix looks like
\begin{verbatim}
.:/usr/local/math/Macaulay/bin
\end{verbatim}
where {\tt :} separates
directories, and {\tt .} indicates the current directory. Directories must
be specified without a trailing {\tt /}.

A typical search path for the Macintosh looks like
\begin{verbatim}
:,A:user:Macaulay:bin:
\end{verbatim}
where {\tt ,} separates directories, and {\tt :} indicates
the current directory. All directories must be specified with a trailing
{\tt :}.

The search path is stored in the internal variable {\tt MclyPath},
which is initialized in the file {\tt mac.c}. This definition can be
modified at a local installation to include (for example) the locations of
standard script libraries, so individual users can run \mac\ with no
additional preparation.

At startup, \mac\ reads the environment variable {\tt MacaulayPath},
which either replaces or appends to the existing path. If
{\tt MacaulayPath} is defined, it appends to the existing path if it
begins with a system-dependent separator character ({\tt ,} or {\tt :}),
and it replaces the existing path otherwise.

\mac\ next tries to find and open a file called {\tt Macaulay.path},
searching for it using the search path constructed so far. If this file is
found, it again replaces or appends to the existing search path, depending
on whether or not it begins with a separator. A return character in {\tt
Macaulay.path} counts as a separator (so this file can list
directories line by line), and trailing and redundant separators
are ignored.

Later during startup, \mac\ tries to find and open a file called {\tt
Macaulay.init}, again searching for it using the search path constructed
so far. If this file is found, \mac's greeting is shortened to a tolerable
single line. This file can contain any commands that the user wants run
every time at startup, such as the new {\tt path} command. The {\tt path}
command can also be used interactively to add to the search path for the
duration of a single \mac\ session.

If you rely on the environment variable {\tt MacaulayPath} to set a
particularly long path, you may wish to create empty files {\tt
Macaulay.path} and {\tt Macaulay.cdir} (see the {\tt cdir} command
below) in the same directory as {Macaulay.init}, to avoid fruitless
lengthy searches for these files at startup.

\subsection{The {\tt path} command}

The {\tt path} command with no arguments gives help and the current
path (Macintosh version shown):

\begin{verbatim}
% path
path <path> (to replace)
path <,path> (to append)

:
A:user:Macaulay:bin:
\end{verbatim}

With an argument, it either appends to or replaces  the existing path,
depending on whether or not the argument begins with a separator;
see the preceding discussion on path handling.

\subsection{The current directory, and the {\tt cdir} command}

This section can safely be ignored, unless you are using the stand-alone
Macintosh version, or you need better control of the directory to which
which files are written by \mac.

Analogous to the internal variable {\tt MclyPath} for path
handling is another internal variable {\tt MclyCdir} for setting the
current directory. It starts out {\tt NULL}, and can be controlled by
a set of methods parallel to those that control {\tt MclyPath}: the source
file {\tt mac.c}, the environment variable {\tt MacaulayCdir}, the
file {\tt Macaulay.cdir}, and the command {\tt cdir}. If used, this
variable must specify a single directory, without a trailing {\tt /} on
Unix systems, and with a trailing {\tt :} on the Macintosh.

If the current directory is not set, then the search path is used to open
files for reading, and file names are used verbatim to open files for
writing. If the current directory is set, then the first attempt to open a
file within \mac\ for reading or writing is made using this prefix. If
this attempt fails for reading, then the search path is used. If the current
directory is set by the source file {\tt mac.c} or the environment
variable {\tt MacaulayCdir}, then this strategy will already be in effect
for the searches for the files {\tt Macaulay.path} and {\tt Macaulay.cdir}.

Bear in mind that this current directory facility is simply a means of
automatically prefixing file names; it doesn't interact with the operating
system to change the operating system's notion of the default directory. In
particular, the system-dependent character {\tt .} or {\tt :} in the
search path refers by itself to the operating system's notion of the
default directory, bypassing this facility.

 The {\tt
cdir} command with no arguments gives help, and the current directory
if it is defined (Macintosh version shown):

\begin{verbatim}
% cdir
cdir <prefix>  (to set)
cdir :         (to clear)
\end{verbatim}

With an argument, it sets or clears the current directory.

\subsection{The {\tt args} command}

The {\tt args} command is used to inspect and modify the preferred
argument counts for \mac\ commands. These counts control command
argument handling in dot mode (described in Section 3), and are not
used outside of dot mode.

{\tt args} with no arguments gives help. With one
argument it displays the current preferred argument count for a
command, and with two arguments it sets this count:

\begin{verbatim}
% args
args <command name>        (to inspect)
args <command name> <int>  (to modify)
% args dsum
3
% args dsum 4
\end{verbatim}

 \section{The stand-alone Macintosh application}

A stand-alone version of \mac\ for the Macintosh now exists, as an
alternative to the  {\tt MPW} \mac\ tool, which requires the {\tt MPW
Shell} (We are working on getting a license allowing the distribution of
the {\tt MPW Shell} to \mac\ users). The stand-alone version can be
found as a bin-hexed self-extracting archive under the name {\tt
MacintoshSIOW.hqx}. It has been compiled using {\tt MPW}'s Standard
Input-Output Window package ({\tt SIOW}), with a few minor
modifications made to the source code for the {\tt MPW} tool version of
\mac. The {\tt MPW SIOW} package comes with scant documentation,
hence the speculative tone that follows. Nevertheless, this version is
snappy and fun to use, even if one is used to the {\tt MPW} tool.

The options for setting the search path and the current directory are
discussed in full in Section 1; only the environment variables {\tt
MacaulayPath} and {\tt MacaulayCdir} cannot be used with this
application, because the Macintosh Finder doesn't support Unix-style
environment variables. The easiest way to set the search path and
current directory for this application is to place files called {\tt
Macaulay.path} and {\tt Macaulay.cdir} in the same directory as the
application. This is also the most convenient place to put the file {\tt
Macaulay.init}.

An alias to \mac\ can then be placed anywhere. However, the directory
containing the actual application will still become the default directory.
For this reason, you will want to use the current directory mechanism,
which most users of other versions of \mac\ are likely to ignor. 

Apparently, any editor (TeachText, Textures, Word, ...) can be used to
modify and save scripts to be read by this version of \mac; it doesn't
complain when a file is already open.

The menus can be used to save or print the window at any time. The
application appears to run OK in 32-bin mode, despite {\tt
SIOW} documentation to the contrary. It also appears to be cooperative
with multifinder.

The interrupt mechanism for this application is the ancient
Macintosh \mac\ protocol of a mouse click in the application window
while the application window is in the foreground.

If you instead try to interrupt a calculation using {\tt command-.} (the
method for interrupting the {\tt MPW} tool), then {\tt stdin} will get
destroyed without interrupting the calculation, because {\tt SIOW}
doesn't support Unix-style interrupt handling. When \mac\ finally
comes up for air on its own, it will immediately quit. This can be
upsetting.

After \mac\ quits, this application sticks around as a menu-driven shell
so its window can be saved, edited, or printed. After the message {\tt
[Macaulay has quit]} appears, there is no way to restart \mac. To exit the
application, use the menu, or type {\tt command-q} followed by {\tt n}
to decline file-saving. ({\tt command-.} is easier to reach, but a
dangerous habit.)

\section{Dot Mode}

Dot mode is an experimental command processor to
supplement the standard interface to \mac. It is in the early stages of
development; a stable version may eventually replace the current
interface for those who choose to move on. Meanwhile, it should only
be used at your own peril; we reserve the right to change it in ways
that will break scripts that worked on earlier incarnations. We are
hoping that certain hardy souls will want to play around with this
interface as a work in progress, and influence its design. Hence, it is
documented here.

So far, all of the source code is contained in the one file {\tt
dot\_fns.c}, and should be more readable than the standard established
by other \mac\ source files. If you want to add a
sleepless night of your own to this effort, please send us the resulting
code, which will be duly attributed in future releases. Please
address all correspondence on dot mode to {\tt dab@math.columbia.edu}

\subsection{Design goals}

This new interface was not designed from scratch, and it shouldn't be
compared to one's visions of the ``ideal'' language. Rather, it is 
intended to be easily used by an experienced \mac\ user after a short
introduction, without requiring the user to learn new syntax on a
command by command basis. This is our best effort so far at solving
this puzzle; we welcome alternative ideas.

The internal design of this parser is slightly unfashionable, in keeping
with \mac's design strategy of employing the simplest algorithms
possible for basic system tasks. The design attempts to find middle
ground between the twin horrors of languages devoid of syntax
(favored by people who don't salt their food), and languages
overdependent on parentheses (favored by people who oversalt their
food). It is an experiment inspired by other ``toy'' languages such as
Forth, Postscript, and Lisp, whose basic syntax can be implemented in
one marathon session, but which nevertheless survive as workhorses
side by side with conventional languages employing techniques from
modern parser theory. The experiment posed is this: What are the
possibilities of an interactive language where we replace the stack in
stack-based languages (such as Forth and Postscript) with a token list
combining operators and data, and use operator precedence to
determine the order in which operators get to manipulate this list? In
principle, such a design could support flow control, macros, and
deferred parsing more flexibly than ``parse then execute'' interpreters.
So far, we have implemented a rudimentary expression synax, and have
hooked up \mac's commands and scripts, relying on the existing script
processing facilities for flow control. This discussion is to give some idea
of where we hope to take this design. In  particular, we would like to
rescue some ideas from {\tt APL}, an ancient matrix-manipulation
language that afforded an economy of expression and thought missing in
modern languages. The dot mode will evolve slowly, as we use it
ourselves in our day-to-day work, and hear from other users.

\subsection{A brief introduction}

Dot mode can be entered one line at a time, by starting the
line with a period {\bf.} followed by a space:

\begin{verbatim}
% <ring 3 a-z r
% type r
a b c 
% . betti res type `dsum r r
a b c 0 0 0 
0 0 0 a b c 
0.1...
computation complete after degree 1
total:      2     6     6     2 
--------------------------------
    0:      2     6     6     2 
\end{verbatim}
The save operator {\tt `} prevents the argument to {\tt type} from
being thrown out, so it can be reused as an argument to {\tt res}.

Alternatively, dot mode can be toggled on and off by a lone dot on
a line; the prompt changes from {\tt \%} to {\tt .\%} to indicate the
mode:

\begin{verbatim}
% .
.% betti res dsum r r
0.1...
computation complete after degree 1
total:      2     6     6     2 
--------------------------------
    0:      2     6     6     2 
\end{verbatim}

The interface mode is an attribute of each input file, and each file
starts out not in dot mode. The mode of a given input file is
restored as expected, after \mac\ finishes reading other files opened
by that file. The dot processor is re-entrant, so it can be
used while a computation is interrupted, without disturbing the
remaining evaluation of the expression that created the computation.
(A user shouldn't have to think about such issues; if you run into an
unexpected problem of this nature, please let us know.)

An expression syntax is supported for manipulating matrices and
integers ($\backslash$ is a transpose operator):

\begin{verbatim}
.% type s = r * \r
a2+b2+c2 
.% type n = 1 + col_degree s 1
3
\end{verbatim}

\subsection{Using the existing \mac\ language}

Dot mode nearly accepts the existing \mac\ language as is. Thus, it is
possible to toggle existing scripts into dot mode with only a small
amount of work. Multiword command names must be joined by {\tt \_}
(not {\tt -}) to avoid parsing as a difference of two names. The dot {\tt
.} should be placed as the second line in a script, after {\tt incr\_set
prlevel 1}, if the script is to run silently. Any idiosyncratic expression
syntax required for particular \mac\ commands must be quoted in dot
mode (e.g. {\tt poly a "a2+b2"}) to slip through the dot processor as a
single token, with quotes stripped. Script invocations (e.g. \mbox{\tt
<ring 3 a-z r}) are an exception to this rule; they get handled without
ever making it to the dot processor, and therefore cannot be used as
part of larger dot expressions. At present, it is necessary to quote
logical expressions (e.g. \mbox{\tt if "\#0==3||\#0==4" START}),
because logical operators are not yet implemented in dot mode. This
will change, and the quotes will become optional.

As a practical matter, it is easier to employ dot mode in scripts on a
line by line basis, as needed. On the other  hand, toggling dot
mode on, and leaving it on, is easier when interacting directly with
\mac. On the Macintosh, be careful not to accidentally type {\tt
command-.}, which causes \mac\ to quit (unless the {\tt MPW} tool
version is in the middle of a computation, in which case the {\it first\,}
such character safely causes an interrupt). This is a particular risk on
the ``battleship'' keyboard, where {\tt command-return} is 
easier to reach than {\tt enter}.

\subsection{The token list}

Input to dot mode is parsed into tokens as follows: All space
characters are converted to a single blank. Any string that
can be recognized as a \mac\ command is converted to a token of type
{\tt oper}; such tokens display as their original text, and share the
precedence given to the virtual operator {\tt .cmd}. Any quoted string
is converted to a token of type {\tt ident}, with the quotes stripped. A
balanced braced expression (e.g. {\tt \{\{a2 ab\}\{ab b2\}\}}) is
converted as is to a single token of type {\tt brace}. Such tokens are
intended for future use, such as for flow control or deferred parsing.
\mac-style identifiers and numbers are converted to tokens of type
{\tt ident} and {\tt number}, respectively. A negative number must
have its leading minus follow a space, or any operator except {\tt )}, to
be recognized: \mbox{\tt 1-2} is a difference, and \mbox{\tt 1 -2} is a
pair of numbers. A lone {\tt \_} is converted to a token of type {\tt
ident}, and is given a unique temporary name of the form {\tt @00@1};
such variables are removed immediately after use. Finally, operators
specific to dot mode (such as {\tt ` = , + *}) are converted to tokens of
type {\tt oper}. The token list is terminated on each end by a token of
type {\tt end}, displayed as {\tt \$}. 

To display the token list for an input line, end the line with the operator
{\tt .stop}, with a count of 0. For example:
\begin{verbatim}
.% a b = b a*((a=2)+(b=3)) .stop 0
$ a b = b a * ( ( a = 2 ) + ( b = 3 ) ) $ 
\end{verbatim}

The token list is evaluated using operator precedence as follows: Each
{\tt oper} token, and the {\tt end} tokens, have left and right
precedence strings associated with them. The token list is scanned
from right to left, comparing adjacent pairs of such tokens, until a pair
is found where the right string of the left token alphabetizes before or
is equal to the left string of the right token. The action associated with the
right token is then carried out; this action will usually include a
modification of the token list, such as replacing the token and its
arguments with a result token. This process is then repeated until there
are no more {\tt oper} tokens, or an error occurs.

This process can be observed by turning on tracing, using the
operator {\tt .trace}. For example,
\begin{verbatim}
.% .trace
; tracing on
.% a b = b a*((a=2)+(b=3))
$ a b = b a * ( ( a = 2 ) + ( b = 3 ) ) $ 
                                ^         
$ a b = b a * ( ( a = 2 ) + ( b ) ) $ 
                                ^     
$ a b = b a * ( ( a = 2 ) + b ) $ 
                    ^             
$ a b = b a * ( ( a ) + b ) $ 
                    ^         
$ a b = b a * ( a + b ) $ 
                  ^       
$ a b = b a * ( @00@1 ) $ 
                      ^   
$ a b = b a * @00@1 $ 
            ^         
$ a b = b @00@2 $ 
      ^           
$ a b $ 
.% type a type b
$ type a type b $ 
         ^        
10
$ type a $ 
  ^        
3
\end{verbatim}

To stop the evaluation loop after a specific number of steps, end the line
with the operator {\tt .stop}, with the desired count. For example:
\begin{verbatim}
.% a b = b a*((a=2)+(b=3)) .stop 5
$ a b = b a * ( @00@1 ) $ 
\end{verbatim}
Variables (including temporaries) can now be examined to sort out
what happened.

To see the left and right precedence strings used in the evaluation
loop, enter {\tt .parse} by itself:

\begin{verbatim}
.% .parse
               =     z    c
               +     m    n
               -     m    n
               *     p    q
               ,     r    s
               \     z    x
               (     y    b
               )     b    y
               `     a    c
            .cmd     z    c
          .trace     z    x
           .stop     z    x
          .parse     z    x
               $     a    a
\end{verbatim}

For example, if we adopt the convention that no right string can begin
with "z", then an operator with a left string of "z" will be executed
before any operator to its left on the token list.

To make a modification to this parse table, enter (for example):
\begin{verbatim}
.% ( .parse ya b
\end{verbatim}
Make changes at your own risk. However, you may need to fix an
interaction we didn't consider. Please report all helpful changes; you
may want to move them to your {\tt Macaulay.init} file.

\subsection{Calling \mac\ commands}

When an {\tt oper} token representing a  \mac\ command is evaluated,
the {\tt ident} and {\tt number} tokens immediately to its right on the
token list are used as arguments to the corresponding command. After
execution of this command, the command token and its arguments are
removed from the token list.

The save operator {\tt `} confers an extra life to the next
argument; save operators are ignored during the scan for command
arguments, and are removed afterwards instead of the arguments
they protect. For example:
\begin{verbatim}
.% betti res (dsum r r `_) `_
$ betti res ( dsum r r ` @00@1 ) ` @00@2 $ 
              ^                            
$ betti res ( @00@1 ) ` @00@2 $ 
                    ^           
$ betti res @00@1 ` @00@2 $ 
        ^                   
0.1...
computation complete after degree 1
$ betti @00@2 $ 
  ^             
total:      2     6     6     2 
--------------------------------
    0:      2     6     6     2 
\end{verbatim}
Any number of save operators can be applied to a given
argument, in which case only one save per argument will be removed at
a time. Save operators can outlive their enclosing parentheses.

Most commands have at least the option of returning values via
their last argument or arguments. There is now an internal table in
\mac\ giving a preferred number of arguments when commands are
used this way. In dot mode, if this preferred argument count is greater
than the number of arguments actually provided, then at the time of
command execution, the token list is automatically padded with the
desired number of {\tt `\_} token pairs. Thus, the above can be more
succinctly written as

\begin{verbatim}
.% betti res dsum r r
0.1...
computation complete after degree 1
total:      2     6     6     2 
--------------------------------
    0:      2     6     6     2 
\end{verbatim}
 
To allow access to command help, padding does not take place if the
command is the leftmost token on the token list. The preferred argument
counts can be inspected and modified using the {\tt args} command
described in Section 1. We did not implement a maximum
argument count table, in the belief that requiring parentheses in
affected cases would improve readability.

\subsection{Dot mode operators}

The assignment operator {\tt =} invokes either or both of the {\tt
copy} and {\tt int} commands, depending on the types of its arguments.
It leaves its left-hand arguments on the token list.
It pairs multiple arguments if possible, so {\tt a b = 1 2}
is equivalent to {\tt a = 1 b = 2}. This was enabled in part to
prepare for handling matrix dimensions as pairs of integers
through an {\tt APL}-style shape operator (not yet implemented).

The binary plus {\tt +}, minus {\tt -}, and times {\tt *} operators invoke
{\tt int}, {\tt add}, {\tt subtract}, and {\tt times} on their arguments as
needed, and leave their result in a temporary variable on the token
list.

The binary comma operator {\tt ,} concatenates its arguments to a new
temporary variable, using {\tt copy} and {\tt concat}. The unary
transpose operator $\backslash$ transposes its argument to a new
temporary variable, using {\tt transpose}. For example:

\begin{verbatim}
.% type s = \r,\r
a a 
b b 
c c 
\end{verbatim}

Parentheses remove themselves from the token list once they have
served their syntactic purpose. An unbalanced parentheses matches
{\tt \$}, but this is an ugly habit to get into.

The save operator {\tt `} protects command arguments from removal
from the token list, as described earlier.

 \end{document}

\begin{verbatim}
\end{verbatim}


