%%
%% ch10.tex
%%

\chapter{Command Files}
\label{ch-scripts}

\section{Running scripts}

	\Macaulay\ is capable of receiving its input from either the 
keyboard or from a text file, which we shall call a script. When 
\Macaulay\ starts up, it expects its input from the keyboard. (This 
is called standard input in Unix circles; you can make \Macaulay\ 
start instead from a text file named ``script'' from Unix by typing 
\type{Macaulay <script} to start \Macaulay, but we shall assume that you 
have just typed \type{Macaulay} to start \Macaulay.) We call the initial 
source of \Macaulay's input ``voice 0''. Inside a \Macaulay\ session, 
you can cause \Macaulay\ to switch over to reading from a text file 
named ``file'' by entering \type{<script}. When you do this, \Macaulay\ 
calls this new input source ``voice 1'', and it keeps track of what 
voice 0 was so it can go back to it after voice 1 ends. A voice 
ends either when \Macaulay\ encounters a dollar sign \$, or when the 
file itself ends. If voice 0 ends, \Macaulay\ quits.

	This process can be iterated many times; you can tell 
\Macaulay\ to take its input from a file, which later tells \Macaulay\ 
to take its input from a second file. When voice 2 ends, \Macaulay\  
goes back to voice 1 (which may later start another voice 2, 
etc.), and when voice 1 ends, \Macaulay\ returns to voice 0, the 
same state in which it started. There is a rather large limit to 
the number of possible input voices which \Macaulay\ can stack up at 
any one time; we'd love to hear from you if you bump into it.

	If \Macaulay\ is in a voice $> 0$, you can tell what this current 
voice is by \Macaulay's prompt characters: type{\ n\%}, where $n$ is the 
voice number. When you interrupt a computation, \Macaulay\ creates a 
new voice to take input from the keyboard (your scripts are still 
there, waiting for the suspended computation to finish). In this 
case, the prompt indicates that a previous environment is 
suspended, and that an inner environment now also exists. For 
example, the prompt \type{2\% 3\%} indicates that a computation initiated 
by voice 2 is suspended, and that voice 3 now controls \Macaulay.

\section{Creating scripts}

	This script capability makes it possible to write and run 
programs written in \Macaulay's command language. In its simplest 
form, you can save a sequence of \Macaulay\ commands to a script 
file, and then later call that script file, rather than retyping 
the commands each time you need them. To this end, \Macaulay\ 
provides a facility for saving commands to a script file as you 
enter them, so that you can enter them again later by simply 
calling the file: To create a script called ``script'' from within 
\Macaulay, enter \type{>>script}. This creates a new input voice, with 
the property that \Macaulay\ is still listening to your keyboard, 
but everything that you type is both used as input by \Macaulay\ and 
saved to ``script''. To end this process, type a dollar sign \$. You 
will return to your earlier voice, and the file named ``script'' 
will now be complete. To use it later, enter \type{<script} to call the 
script.

	Of course, you can use your favorite text editor to write a 
script, when you are not running \Macaulay, and then use this 
script later from within \Macaulay. This has the disadvantages that 
you don't get to see what happens in an example, as you plan the 
sequence of commands, and that you may have trouble remembering 
exactly what information \Macaulay\ wants when. Nevertheless, some 
people prefer this style of writing scripts; it probably reminds 
them of their childhoods, bringing decks of punched cards over to 
a mainframe to find the next bug in their program. We recommend 
that you create scripts from within \Macaulay, and then revise them 
using an editor, until you are an expert user.

\section{Tour mode}

	If you want to see a script run slowly, pausing at each line, 
enter \type{<<script} rather than \type{<script}. We call this ``tour'' mode, 
because a long time ago the on-line documentation for \Macaulay\ 
consisted mainly of three meager tours which one ran in this 
fashion. It is a good way to study someone else's script, or to 
debug your own script. What \Macaulay\ does in this mode is act like 
a player piano: it types each line of input taken from the script, 
and then waits for you to type \return (``enter'' in MPW) before 
going on.

	If you want to interrupt a script which is running in tour 
mode, you can. Type an ampersand \& before ending the line for 
\Macaulay, and \Macaulay\ will create a new input voice AFTER 
executing the line that you just ended. In this new input voice, 
\Macaulay\ takes its input from the keyboard; when you end it by a 
dollar sign \$, \Macaulay\ returns to the script in tour mode.

	If you want to complete the script, but turn back off the 
tour mode, type an exclamation ! to end a line. \Macaulay\ will then 
continue to read the script, without pausing for you. If instead 
you want to end the script early, type a dollar sign \$. This works 
to end the voice, as always.

	Tour mode is hereditary; if a script which you are playing in 
tour mode calls another script, that script will also be run in 
tour mode. If this isn't your intention, you can type ! to speed 
through this inner script. When it finishes, you will be back in 
the previous script, still in tour mode.

	The interactions between scripts in tour mode may seem 
complicated at first, but all follow from the above rules. You 
should experiment around, thinking of \&, \$, and ! as your clutch, 
brakes, and gas pedals, and you will get the hang of it.

\section{Passing parameters to scripts}

	It is possible to have a script use different names for 
\Macaulay\ objects, each time you call it. If you call a script by 
the sequence \type{<script aa bbb c}, then \Macaulay\ will substitute the 
strings ``aa'', ``bbb'', and ``c'' anyplace in the text of ``script'' that 
it finds the strings \#1, \#2, and \#3. In addition, \#0 stands for 
the number of arguments used when the script is called (in this 
case, 3). More generally, any valid \Macaulay\ expression that 
produces an integer can be used in place of \#1, \#2, \#3 (\#0 can 
only be the digit 0). The expression will be read up to the next 
blank character, to figure out which integer you mean, unless it 
begins with a digit, or a parenthesis ``(``. A leading digit is used 
by itself, and a parenthesis are read until the matching 
parenthesis is found. Thus if $i$ has value 3, then in our 
example, \type{a\#19 b\#(i)b} will be translated to \type{aa9 bcb}. In 
particular, numbers greater than 9 must always be parenthesized, 
as in \#(19). There is a rather large limit to the number of 
possible input parameters which \Macaulay\ can handle at any one 
time; we'd love to hear from you if you bump into it.

	\Macaulay's parameter passing scheme is best understood if you 
realize that the core of the program has no idea that all this 
stuff is happening; all of the effects described here are handled 
by a single preprocessing routine that hands lines of input to 
\Macaulay\ as if you typed them. In particular, all \Macaulay\ 
variables are accessible at all times; there is no internal 
concept of local variables, since the inner depths of \Macaulay\ 
have no idea when the voice changes. This can be a real pain if 
several of your scripts use the same variable name in conflicting 
ways.

	To avoid this problem, we created a way for scripts to 
uniquely name their temporary variables: the character @ is 
translated to @nn@, where ``nn'' is the current voice level. Thus if 
a script running as voice 1 uses a temporary name i@, and it calls 
a script which also uses a variable i@, then the two names will read as 
i@01@ and i@02@. These variables are not automatically erased, but 
if later a new script running as voice 2 uses i@, it will write 
over the old i@02@ (which is OK with us if it's OK with you).

	There are two exceptions to the automatic expansion of @: 
\Macaulay\ recognizes something that looks like it is already 
expanded, and doesn't reexpand it (so i@01@ doesn't become 
i@01@01@01@), and when the input voice is from the keyboard, 
\Macaulay\ assumes that you mean the closest voice associated with a 
script (so i@ becomes i@01@ in voice 0, and i@02@ in voice 3, for 
example.) This is handy when debugging.

	If a script needs to use a name which isn't intended to be 
temporary, it should be passed as a parameter to the script, to 
avoid name conflicts. If a script needs to use a name which is 
intended to be temporary, it should kill the variable after it is 
done with it, in case space usage becomes a problem.

	If you want to create scripts interactively which use 
parameters, then pass parameters to the script as you create it:
Enter \type{>>script dd eee f} to use ``dd'', ``eee'', and ``f'' as example 
names. While recording this script, you must use \#1, \#2, and \#3 to 
refer to these parameters if you want your commands to change 
whene the parameters change. If you use ``dd'', ``eee'', and ``f'' while 
writing your script, it will be hard-wired to use these names, 
even if it is later called via the sequence \type{<script aa bbb c}. 

\section{Silence is sometimes golden}

	If you build up a collection of scripts which call scripts 
which call scripts, you'll probably get sick of watching every 
line go by. Moreover, in many cases it actually takes \Macaulay\ 
longer to get the results up on the screen than to think them up. 
By the command \type{incr-set prlevel 1} at the beginning of a sequence 
of commands, and \type{incr-set prlevel -1} at the end, you can 
normally hide from your sight everything that happens in between, 
and speed up the process to boot. Many people like to do this at 
the beginning and end of all of their scripts, so that their 
scripts run almost like built-in \Macaulay\ commands.

	Exceptions: Error messages will still be printed. What you 
have actually done is to increment and decrement a \Macaulay\ set 
variable which starts out with value 0, and which inhibits output 
to the screen whenever it is positive. Thus, if you first enter 
\type{set prlevel -3} then your first three voices of ``silent'' scripts 
will show their output after all, and any higher voice silent 
scripts will in fact run silently. 

\section{If statements and jumps}

	\Macaulay\ provides some rudimentary ``control flow'' for jumping 
around in scripts. These commands basically tell the preprocessor 
which handles scripts to start reading the scripts in different 
places. In other words, \Macaulay\ scripts are interpretted, not 
compiled. This is not a serious speed disadvantage for two 
reasons. First, most of the time is spend actually computing 
things like standard bases and free resolutions, not figuring out 
what commands mean. Second, it usually takes the host computer's 
operating system far longer to find scripts as they are called, 
than it takes \Macaulay\ to scan an entire script once found. Thus 
jumps within a script are faster that calls to other scripts, 
which is itself faster than the actual computations.

	\Macaulay\ jumps around in scripts using labels. A label is 
anything at the beginning of a line (ignoring leading white space) 
up to a colon ``:''. Labels are ignored by \Macaulay\ for all purposes 
besides if statments and jumps. When \Macaulay\ is directed by an if 
statement or a jump to continue reading input from a label, it 
starts scanning the script file from the beginning, until it finds 
the label. It begins executing statements on the line of the 
label, or on the next line if the label is on a line of its own.

	A jump statement takes the form \type{jump label}, and sends 
\Macaulay\ careening off in search of this label. An if statement 
takes the form \type{if condition label} or 
\type{if condition label label2}. In the first form, \Macaulay\ 
jumps to ``label:'' if the condition is true. In the second form,
\Macaulay\ jumps instead to ``label2:'' (rather than just continuing on
from where it was) if the condition is false.

\section{Summary}

	Together, these facilities allow for a fairly high degree of 
automation of the process of directing commands to \Macaulay's 
innards. This ain't Lisp we're talking about here (As Popeye says, 
I yam what I yam), but many novice computer users actually prefer 
the simplicity of our environment. If you can think of simple 
additions to the above constructs that would greatly increase the 
flexibility or power of \Macaulay\ scripts, please suggest them to 
us.
