%%
%% ch3.tex
%%

\chapter{Input Syntax}
\label{ch-syntax}

This chapter describes \Macaulay's input format for commands, user
defined variables, ring indeterminates, integer and polynomial
expressions, integer lists and variable lists.
	
\section{How to Input a Command}

Commands are input with one or more spaces between all parameters.
Throughout \Macaulay, spaces are always considered separators.  This means
that any integer or polynomial expression cannot include spaces.

\section{Special Characters}
\label{sec-spec}

The following characters have special meaning in \Macaulay.
	$$\mbox{\tt >, <, <<, >>, \#, \$, @, \&, ?, \%, ;}$$

The characters \type{>, <, <<, >>, \#, \$, @, \&} all have meaning when
used with script files. The characters \type{>, <, <<, >>} redirect
either the input or the output of \Macaulay, when they appear at the
beginning of a line or a parameter.  The characters \type{<, <=, >,
>=, =, !=} have their usual meaning as relational operators if they
appear in an integer or polynomial expression.

The character \type{\#} is used for arguments to scripts, the character
\type{@} is used to provide some support for local variables, and the
character \type{\$} is used to exit a script. This last character,
if typed outside of a script, causes \Macaulay\ to exit exactly as if
\type{exit} had been typed, so be careful!  See \chapref{ch-scripts} 
for more details.

The characters \type{;}, \type{?} and \type{\%} are used for comments.
Any text appearing after a semicolon is ignored (to the end of the
line).  Text appearing before a \type{?} or \type{\%} on an input line
is also ignored.  This allows the user to place comments either at the
beginning or at the end of the line.  This was included mainly for use
with the Macintosh MPW shell: when one types \type{<enter>}, the
entire current line is sent as input to \Macaulay.  \Macaulay's
prompts for input always end with either a \type{?} or \type{\%}.
Therefore the prompt part of the line is considered a comment by
\Macaulay!  An additional benefit is that a \Macaulay\ session
(recorded with \icmd{monitor} for example) can be ``played back'' as
an input file.

\section{User Defined Variables (Identifiers)}

Each mathematical object created by the user is associated
with a name selected by the user.  Identifiers begin with an
alphabetic character (upper or lower case) or one of the following three
characters: \verb+@, ', _+.
Subsequent characters of the identifer must be either digits $(0,
\ldots, 9)$ or a character from the above list.  The length of an
identifier is limited to 50 characters.  Upper and lower case
characters are distinct, thus the identifiers \type{myMatrix} and
\type{mymatrix} refer to different user variables.

For example, the following are all legal names in \Macaulay.

\begin{verbatim}
     a'mine
     @veronese
     my_matrix
     m0128
     a'
\end{verbatim}

The character @ is used for local variables inside scripts (command files):
Inside of a script, @ is expanded to @nn@, where $nn$ is the ``level''
of this script.  Thus name conflicts will not occur if all local
variables in a script contain a @.  See \chapref{ch-scripts} for
details.

Wherever an identifier is expected as a paramter to a command, 
you may enclose it in curly braces.  Therefore, the identifiers
\type{a\_mat} and \type{\{a\_mat\}} represent the same variable.
Curly braces are only required in certain instances, to avoid name conflicts.
See \secref{sec-vref} for a complete list of these instances.

\subsection{Indexed Identifiers}

Some variables which denote computations may be indexed.
An indexed identifier is an identifier as above, followed by the
character ``.'', followed by an integer expression.  See \secref{sec-syint}
for a description of integer expressions.
See \secref{sec-vref} for more information on indexed variables.
For example, if ``i'' is an integer variable, then the following are legal
indexed identifiers.

\begin{verbatim}
    a.3, 
    a.(2*i+1)
\end{verbatim}

\section{Naming polynomial ring variables (indeterminants)}
\label{sec-syvar}

Every polynomial and every matrix in \Macaulay\ must be defined over a
polynomial ring.  The indeterminates of a ring are either single letters
or are single letters indexed by one or more integers.  More specifically,
these indeterminates have the following form.

\begin{enumerate}
\item a single letter: a-z, A-Z, where upper and lower case are distinct  or
\item a single letter, indexed by a set of integers or integer expressions,
separated by commas and enclosed by square brackets.
\end{enumerate}

For example, if ``i'' is a user defined integer variable, then the
following are legal ring indeterminates:

\begin{verbatim}
    a
    A
    F[1,2,3]
    z[-1,2*i]
\end{verbatim}

The \icmd{ring} command informs \Macaulay\ which variables you wish to use.
These names do not conflict with any user defined variable names (i.e.
one can have a matrix named ``a'', as well as an indeterminate in the
base ring of this matrix, named ``a''.  The only time a conflict is possible
is with polynomial expressions.  See Sections \ref{sec-sypoly} and 
\ref{sec-vref} for more details.

We often call ring indeterminates either ``variables'' or ``ring variables''.
These should not be confused with user defined variables which are rings.

\section{Integer Expressions}
\label{sec-syint}

The syntax for integer expressions in \Macaulay\ is similar to most computer
languages, except that no blank spaces are allowed inside of such
an expression, since spaces are used as delimiters in \Macaulay.

The legal operators of \Macaulay, in order of increasing precedence, are
given in the following table.

\begin {itemize}
\item   {\tt <, <=, >, >=, =, !=}
\item	{\tt +, -}
\item	{\tt *}, {\tt /} (integer division), {\tt \&} (remainder)
\item	{\tt +, -} unary operators
\item   \verb+^+, {\tt **} (both are exponentiation operators)
\end{itemize}

Parentheses are used to enforce groupings in an expression.  User defined
variables which are integers may appear in expressions.

The relational operators all return the value one if the condition is true,
else they return zero.  

For example, using the \icmd{int} command,

\begin{verbatim}
%  int i (3+1)/2+(4-1)^2

%  type i
; 11

%  int a (i+3)*(i+2)*(i+1)/6

%  type a
; 364

%  int b i>a

%  type b
; 0

%  int b i<a

%  type b
; 1

\end{verbatim}

\section{Polynomial expressions}
\label{sec-sypoly}

The syntax for polynomial expressions is similar to integer expressions.

The legal operators for polynomials, in order of increasing precedence, are
given in the following table.

\begin {itemize}
\item	{\tt +, -}
\item	{\tt *}, {\tt /} (polynomial division), {\tt \&} (polynomial remainder)
\item	{\tt +, -} unary operators
\item   \verb+^+, {\tt **} (both are exponentiation operators)
\end{itemize}

The polynomial division and remainder are done using the defined monomial
order in the base ring.  Parentheses are used to enforce groupings in an
expression.  

The following remarks describe certain aspects of polynomial expressions.

\begin{itemize}

\item Polynomials in \Macaulay are output in an abbreviated notation:
each polynomial is displayed as a number of monomials separated by
``+'' or ``-''.  Each monomial is preceeded by its coefficient and
each indeterminate is followed by its degree with no intervening
blanks.  Rational number coefficients are represented by $x/y$.  A
polynomial which extends over a line boundary is displayed by using
\bslash\ as the continuation character.  If you wish to have polynomials
output in Mathematica format, use the \icmd{prmat} command.

\item User defined matrix variables can appear in polynomial expressions.
The variable must be enclosed in curly braces so that \Macaulay\ won't
think that it is a sequence of ring indeterminates.  \type{\{M\}}
refers to the $(1,1)$ entry of the matrix $M$.

\item A \bslash\ at the end of a line, preceded by a space, is the line 
continuation character.  \Macaulay\ computes the polynomial on each 
continued line, and then adds them all together.  Thus, each line must
be a well-defined polynomial.

\item Certain abbreviations are allowed, mainly in order to allow easier
entry of polynomials, and to allow the output polynomials of
\Macaulay\ to be legal input.  One can suppress the
``*'' between a number or a ring indeterminate and another ring
indeterminate, the ``\verb+^+'' between a ring indeterminate and its
exponent, and the ``*'' before a left parenthesis, or after a right
parenthesis.  

\end{itemize}

For example,

\begin{verbatim}
%  poly f (x[1]+x[2])^2

%  type f
; x[1]2+2x[1]x[2]+x[2]2 

%  int i 1

%  poly g (x[i]-x[i+1])^2*{f}

%  type g
; x[1]4-2x[1]2x[2]2+x[2]4 

%  poly h ab2+c2d+a(b+c)(b-c)

%  type h
; 2ab2-ac2+c2d 

\end{verbatim}

\section{Integer lists}
\label{sec-intlist}

An integer list in \Macaulay\ is an ordered list of integers.  
They are used for many purposes including, listing the
degrees of the rows or columns of a matrix, weights of the variables
in a ring, weight functions for monomial orders, and selecting rows or
columns of a matrix to define a submatrix. 

An integer list consists of a sequence of items, separated by blanks.
Each item is one of the following, where $e$ and $f$ are arbitrary integer
expressions.

\begin{itemize} 
\item 	an integer expression $e$
\item	$e$..$f$ (range)
\item	$e$:$f$	(replication)
\item	a matrix variable $m$
\end{itemize}

Ranges must represent an increasing sequence of integers, for example
\type{a..b}, denotes the sequence $a, a+1, \ldots, b$, where $a$ and 
$b$ are user defined integer variables, and $a \leq b$.  \type{a..b}
is legal even if $a > b$, but denotes the empty sequence.

Replications $e$..$f$ replicate the first integer $e$ the
number of times indicated by the second integer $f$.  Thus \type{2:4}
represents the sequence $2,2,2,2$.  If $f \leq 0$, $e$..$f$ denotes
the empty sequence.

A matrix variable $m$ denotes the sequence of row degrees of the matrix $m$.

If a fixed length list is expected (as in the \icmd{setdegs} command),
and fewer items are specified, the last integer is replicated to fill
the list.  If more items are specified, the extras are simply ignored
with no warning.

Using special characters in response to an integer list prompt has
the following meaning.
\begin{itemize}
\item \return\ This gives a
default integer list which is dependent upon the command.  For
example, the default value for row degrees in the \icmd{setdegs} command
is 0, and the default for the variable weights in a ring, using the
\icmd{ring} command is 1.

\item  ``\bslash'' This is the line continuation 
character.  If this is entered, preceded by a blank space, you will be
prompted to continue the integer list on the next line (which may also be
continued with ``\bslash'', etc.)

\end{itemize}

Integer lists are displayed using replication.

Examples:  Suppose that the row degrees of the matrix $m$ are \type{1,1,2,3}
and the row degrees of the matrix $n$ are \type{-1,-4,5,100,1200}.  Then

\vskip10pt
\begin{tabular}{ll}
\tt
3:5 & 3 3 3 3 3\\
1 2 3..5 0:3 & 1 2 3 4 5 0 0 0\\
2 1 -1..4 1:2	& 2 1 -1 0 1 2 3 4 1 1\\
1 2 3..5 i..i+3	& 1 2 3 4 5 i i+1 i+2 i+3\\
4 1 2 & 4 1 2\\
0:5 1 &	 0 0 0 0 0 1\\
0:d & 0 0 0 ... 0  (d zeros)\\
m 10 n &  1 1 2 3 10 -1 -4 5 100 1200
\end{tabular}

Integer lists are used by the commands:	\icmd{submat, cat, ring,
setdegs,setcoldegs}.

\section{Variable lists}
\label{sec-varlist}

A variable list is an unordered subset of the variables
of a ring.  Variable lists are used by the command \icmd {jacob}
to determine which variables to differentiate with respect to, and the
commands \icmd {coef}, \icmd {stdpart}, \icmd {inpart}, \icmd {std-minimal},
\icmd{k-basis}, and \icmd{truncate}
which divide the variables into the ``essential'' variables and the
``parameters'' or ``coefficients''.  

A variable list consists of items separated by blanks.  An item in the
variable list is one of the following:

\begin{itemize}
\item ring variables, e.g. {\tt a, x[i+1], d[i,j]}.
\item \parm{ring variable}..\parm{ring variable} (range).
\end{itemize}

Duplicates in the list are not counted and ranges are determined by
the order of the variables in the ring.

Using special characters in response to a variable list request has
the following meaning:
\begin{itemize}
\item \return\  indicates the default and denotes the variables
in the first block.

\item	{\tt ! \parm{list}} An exclamation mark at the beginning of a list 
 means complement the set.

\item	{\tt !} Denotes the set of all variables in the ring.

\item  \bslash\ This is the line continuation 
    character.  If this is entered, preceded by a blank space, you
will be prompted to continue entering the variable list on the next
line (which may also be continued with \bslash, etc.)
\end{itemize}

For example,  suppose the ring variables in the current ring, in the
order they were given in the \icmd {ring} command, are \type{xyzabcdef}, where
\type{xyz} are the three variables in the first block, and \type{abcdef}
are the variables in the second block.  The following variable lists
denote the corresponding sets of variables.

\begin{tabular}{ll}
\tt
x y z a..d    & \{x,y,z,a,b,c,d\}\\
f z..c        & \{z,a,b,c,f\}\\
a a y..x      & \{a\}\\
\return		& \{x,y,z\}\\
! a..f		& \{x,y,z\}
\end{tabular}

Suppose that the variables in the current ring, in the order they were
given in the \icmd{ring} command, are \type{xyzdcbax[1]x[2]x[3]y[2]}.
Suppose that \type{xyz} are the variables in the first block, and that
the rest of the variables are in the second block.  The following
variable lists denote the corresponding sets of variables.

\begin{tabular}{ll}
\tt
x y x[1]..y[2]	& {x,y,x[1],x[2],x[3],y[2]}\\
x..z d..a	& {x,y,z,d,c,b,a}\\
a..d		& \mbox{bad variable list}\\
! x..z		& {d,c,b,a,x[1],x[2],x[3],y[2]}\\
\return\  	& {x,y,z}\\
!		& \mbox{all variables}\ {x,y,z,d,c,b,a,x[1],x[2],x[3],y[2]}
\end{tabular}

