%\documentclass[11pt]{article}
%
%\title{A Programming Language for Scientific Computation: Reference Manual}
%\author{
%\begin{tabular}{cccc}
%Yong Man Ra & Domiano Lee & Tiantian Zhou & Hanhua Feng\thanks{
%}
%\\
%\multicolumn{2}{c}{\{yr86,cl588\}@columbia.edu} &
%\multicolumn{2}{c}{\{tiantian,hanhua\}@cs.columbia.edu}
%\end{tabular}
%}
%
% $Id: lrm.tex,v 1.14 2003/05/12 17:37:34 hanhua Exp $

%\usepackage{graphicx}

%\setlength{\textwidth}{6.7in}
%\setlength{\textheight}{8.5in}
%\setlength{\oddsidemargin}{-0.2in}
%\setlength{\evensidemargin}{-0.4in}
%\setlength{\topmargin}{0in}

%\begin{document}
%\maketitle

\section{Lexical conventions}

\subsection{Comments}

The characters ``$/*$'' start a comment terminated by ``$*/$'', while the
characters ``$//$'' start a single-line comment.

\subsection{Identifiers}

An identifier consists of letters, digits and underscore ``\_''.  The
first character of an identifier should be a letter or underscore.
Upper and lower case letters are considered different.

\subsection{Keywords}

These identifiers are reserved as keywords:

\begin{verbatim}
for     if       else    loop     
break   continue return  exit
include func     and     or       
not     true     false
\end{verbatim}

\subsection{Numbers}

A number consists of digits, optional decimal point ``.'' and optional
``e'' followed by signed integer exponent.  Integers and floating numbers
will be distinguished.

\subsection{Strings}

A string is a sequence of characters enclosed by double quotes
``$''$''.  A double quote inside the string is represented by two
consecutive double quotes.

\subsection{Other tokens}

Some symbolic characters or sequences of symbolic characters are used
in the language:

\begin{verbatim}
{   }   (   )   [   ]   ,   ;   
+   -   *   /   %   /'
=   +=  -=  *=  /=  /'=
>=  <=  >   <   ==  !=  
'   :   ::
\end{verbatim}

\section{Types}

In this language we do not have any explicit type specifications.  As
a result, the language is not statically-typed, though this language is
possibly compiled to Java source code.  Data types are distinguished
at run time.  Each variable is bounded by a type tag, which could be
checked at run time.

Implemented run-time types:
\begin{itemize}
\item \texttt{bool} boolean values being either \textbf{true} or
\textbf{false}
\item \texttt{int} : 32-bit integers
\item \texttt{double} : 64-bit IEEE floating format
\item \texttt{matrix} : M-by-n matrix containing entries of the double type
\item \texttt{string} : string of characters
\item \texttt{function} : user-defined functions
\item \texttt{matmask} : indicating what elements are selected in a matrix
\item \texttt{range} : Only for temporary values (cannot be assigned to a
variable), used as matrix indexes
\end{itemize}

\section{Expression}

\subsection{Primary expressions}

Primary expressions include identifiers, constants, function calls,
access to matrix/vectors elements or sub-matrix/sub-vectors, transpose
of a matrix, anonymous matrices or vectors, and any other expressions
surrounded by ``('' and ``)''.

\subsection{Identifier}

An identifier itself is a left-value expression.  It will be
evaluated to some values bounded to this identifier.

\subsection{Constant}

A constant is a right-value expression, which will be evaluated
to the constant itself.

\subsubsection{Function call}

A function call consists of a function identifier, followed by a list
of arguments enclosed by ``('' and ``)''.  The list of arguments
contains zero or more arguments separated by ``,''.  Each argument
is an expression.

Function call is a right-value expression.

\subsubsection{Access to array elements or sub-arrays}

This primary expression consists of an array(matrix/vector) identifier
or other left-value expressions, followed by a list of indexes
enclosed by ``['' and ``]''.  The list of indexes contains one or two
range specifiers.  

This expression is itself left-value.

\subsubsection{Matrix transpose}

The right-value transpose expression consists of an array identifier
or other left-value expressions, following by transpose operator
``$'$''.

\subsubsection{Anonymous arrays}

An anonymous array is a way to build up a matrix or vector via
individual elements.  Each element of an array could be an expression,
separated by ``,'' or ``;'', where ``;'' separates columns of an
array.  The whole anonymous array is surrounded by ``['' and ``]''.

\subsubsection{( expression )}

A parenthesized expression is a primary expression, which returns the
value of enclosed expression.  The presence of parentheses is to boost
the precedence.

\subsection{Arithmetic expressions}

Arithmetic expressions take primary expressions as operands.

\subsubsection{Unary arithmetic operators}
Unary operators ``$+$'' and ``$-$'' can be prefixed to a expression.
``$+$'' operator returns the expression itself whereas the ``$-$''
operator returns the negative of the primary expression.

They are applicable to int, double, and matrix values.

\subsubsection{Multiplicative operators}

Binary operators ``$*$'', ``$/$'', ``$\%$'' and ``$/'$'' indicate
multiplication, division, modulo and prefixed division,
\footnote{Modulo is effective for both integers and floating numbers,
but not for matrices.  For integers and floating numbers, division
and prefixed division do exactly the same operation, while for
matrices, $A/B$ means $AB^{-1}$ and $A/'B$ means $B^{-1}A$.}
respectively.  They are grouped left to right.

They are applicable to int, double, and matrix values.

\subsubsection{Additive operators}

Binary operators ``$+$'', ``$-$'' indicate addition and subtraction,
respectively.  They are grouped left to right.

They are applicable to int, double, and matrix values.
Operator ``$+$'' is also applicable to string values.

\subsection{Relational expression}

Binary relational operators ``$>=$'', ``$<=$'', ``$==$'', ``$!=$'',
``$>$'' and ``$<$'' indicate whether the first operand is greater than
or equal to, less than or equal to, equal to, not equal to, greater
than, or less than the second operand, respectively.  A bool value
is returned in case that both operands are numbers (int and double),
and exactly two operands are needed.

These operators are also applicable to matrix.  If two matrices are
compared, a matmask value is returned.  It can be assigned to a variable,
or directly used as the index of a matrix.

\subsection{Logical expression}

Logical operators take relational expressions as operands.  Among
these operators, operator \textbf{not} has the highest precedence,
then operator \textbf{and}, and operator \textbf{or} is the lowest.

These operators are applicable to either bool values or matmask
values.

\subsubsection{Not operator}

A logical expression consisting of a \textbf{not} operator followed by
a relational expression returns the logical negation of this relational
expression.

\subsubsection{And operator}

Operator \textbf{and} indicates the logical and of two relational expressions.
It is short-circuited for bool values, but not for matmask values.

\subsubsection{Or operator}

Operator \textbf{or} indicates the logical or of two relational expressions.
It is short-circuited for bool values, but not for matmask values.

\section{Matrix indexes}

Matrix/vector indexes can have only one component, or two components
separated by comma ``,''.  If two components are supplied, each index
component indicates the index on the corresponding dimension.  Both
index components can be a single arithmetic expression with an
integer-compatible value, or two arithmetic expressions separated by
``:'' or ``::'' to form a \textsl{range}.  If only one component is
supplied, this component can be integer-valued expression, range, or
matmask.

If two arithmetic expressions of a range are separated by ``:'', the
first expression indicates the lower bound of the range, and the
second expression indicates the upper bound of the range.  The upper
bound is the largest possible index if it is omitted.  If two bounds
are both omitted, a single ``:'' means all elements on this dimension
are included.

If two arithmetic expressions of a range are separated by ``::'', the
first expression (non-negative value) indicates one bound of the
range, and the second expression (positive value) indicates how many
elements are included.  None of two expressions can be omitted in this
case.

If range or matmask is used, the language is basically operating on
the selected elements of the original matrix.  The expression
$A[expr]$ and $A[range,range]$ are left-values, and the original
elements of matrix $A$ will be operated.

A 1-by-1 sub-matrix can be handled as a double.

\section{Statements}

Statements are basically elements of a program.  A sequence of statements
will be executed sequentially, unless the flow-control statements indicate
otherwise.

Note that in the following specifications, elements enclosed in $<$ and $>$
will be replaced by some corresponding component.

\subsection{statements in ``\{'' and ``\}''}

A group of zero or more statements can be surrounded by ``\{'' and ``\}'',
in which case they altogether are treated as a single statement.

\subsection{Assignments}

An assignment is in this form:

\begin{verbatim}
<left-value expr> = <right-value expr>;
\end{verbatim}

where ``;'' is the terminator of this assignment statement.

\subsection{Conditional statements}

A conditional statement is in this form:

\begin{verbatim}
if ( <logical expression> ) 
    <statement>
\end{verbatim}

or 

\begin{verbatim}
if ( <logical expression> ) 
    <statement> 
else 
    <statement> 
\end{verbatim}

If the logical expression returns true, the first statement is
executed, otherwise the optional second statement is executed.

\subsection{Iterative statements}

Iterative statements are basically loops.  There are two kinds of loops,
\textbf{for} and \textbf{loop}.

\subsubsection{For statement}

The \textbf{for} statement is usually used for indexes of array elements.
It has this form: (note that id means identifier)
\begin{verbatim}
for ( <id> = <range> ) 
    <statement>
\end{verbatim}
or 
\begin{verbatim}
for ( <id1> = <range>, <id2> = <range>  ) 
    <statement>
\end{verbatim}

More \verb`<id> = <range>` can be accepted.  The \texttt{range} field
is the same as matrix indexes.  \verb`<id1>` also acts as the label of
the for statement.

\subsubsection{Loop statement}

The \textbf{Loop} statement is the general iterative statement.  It
is in this form:
\begin{verbatim}
loop <statement>
\end{verbatim}
or
\begin{verbatim}
loop (<label>) <statement>
\end{verbatim}

An infinite loop will be introduced if none of break and return is
used in the loop statement.  The \texttt{label} is an identifier that can be
used by break or continue statements.

\subsubsection{Break statement}

The \textbf{break} statement will break the inner-most or labeled iterative
statement.  This statement consists of keyword \textbf{break},
optionally followed by a label, then followed by a ``;''.

\subsubsection{Continue statement}

The \textbf{continue} statement will end the current iteration of the
inner-most or labeled iterative statement and proceed to its next
iteration.  This statement consists of keyword \textbf{continue},
optionally followed by a label, then followed by a ``;''.

\subsection{Function invocation and return}

\subsubsection{Function call}

Different from other expressions, a function call followed by a ``;''
 can be a single statement.

\subsubsection{Return statement}

The return statement is used inside the function definition body, in
order to return from the function at that point.  It can be followed
by an optional expression, for the return value, and a ``;''.

\subsection{Inclusion of other programs}

Keyword \textbf{include} is used to include other program files.  The
format of this statement is:

\begin{verbatim}
include <string of the path> ;
\end{verbatim}

\section{Function definition}

A function definition is in this form:
\begin{verbatim}
func <id> ( <var-list> ) = <expression> ;
\end{verbatim}
or
\begin{verbatim}
func <id> ( <var-list> ) { <body> }
\end{verbatim}

Field \texttt{id} indicates the name of this function.  Field
\texttt{var-list} is a list of identifier of (formal) arguments,
separated by commas ``,''.  The list of arguments can be empty.  Field
body is zero, one or multiple statements.  In the first form, the
function returns the evaluated value of field expression, whereas the
in the second form, the return statement should be used in the body in
order to return a value.

\section{Internal functions}

\subsection{Console output functions}

\subsubsection{Print}

Function print() takes one or more arguments and print them to the
standard output one by one.  This function returns the first argument.

\subsubsection{What}

Function what() prints the information of variables, for debugging
purposes.  It takes zero or more arguments.  If it takes no argument,
it will print all variables in the current scope.

\subsection{Picture drawing functions}

\subsubsection{Paint}

Function paint() draws a matrix in a new window as an image.  It takes
one or three arguments.  The first argument should be a matrix, and
the rest optional arguments indicate the minimum and maximum values of
this matrix, which can be different from the real minimum and maximum
values for display.   This function returns the first argument: the
matrix to be drawn.

\subsubsection{Opaint}

Function opaint() draws a matrix in the current window, over the
existing image.  The format of opaint() is one of\\
\begin{verbatim}
opaint( matrix )
opaint( matrix, mask )
opaint( matrix, x, y )
opaint( matrix, mask, x, y )
opaint( matrix, x, y, min, max )
opaint( matrix, mask, x, y, min, max)
\end{verbatim}
where argument \texttt{mask} is a matmask of the matrix to be drawn.
Arguments \texttt{x} and \texttt{y} are the upper-left coordinates to
draw the matrix (default to be (0,0)).  Arguments \texttt{min} and
\texttt{max} are similar to those in paint().

\subsubsection{Plot}

Function plot() takes one or two arguments.  The first argument should
be a matrix with 2 or 3 columns, indicating x-, y-, and optionally
z-coordinates of a data point.  Each row of the matrix is a data point
to be drawn.  The second argument is optional, and have two rows and
same number of columns as the first argument, indicating the minimum
(the first row) and maximum (the second row) of the first argument.

\subsection{Color}

Function color() sets the current color.  It needs three double
arguments for red, green and blue values, in this order.  These
values should be no less than 0 and no more than 1.

\subsection{Colormap}

Function colormap() sets a colormap for painting images and plotting
with changing colors.  It takes an argument of matrix type.  This
matrix should have three rows: the first rows for blue values, the
second for green values and the third for red values.  None of
the entries can be less than 0 or more than 1.  Alternatively,
the internal color maps can be used, in which case the user use
an integer as the only argument.

\begin{tabular}{|l|l|}
\hline
argument & color map \\
\hline
0 & black/white \\
1 & grayscaled \\
2 & all colors (red$\to$orange$\to$yellow$\to$green$\to$blue$\to$violet) \\
3 & dark colors (same as all colors but darker)\\
4 & hot colors (red$\to$yellow$\to$white)\\
5 & warm colors (green$\to$blue)\\
6 & cold colors (blue$\to$violet)\\
\hline
\end{tabular}

\subsection{File I/O functions}

\subsubsection{Load}

Function load() loads binary data from a data file.  It takes four or
five arguments, in one of the following formats:
\begin{verbatim}
load( file, type, m, n )
load( file, type, m, n, skip )
\end{verbatim}
where argument \texttt{file} is a string indicating the file name,
argument
\texttt{type} is a string indicating the data type in the file, and 
\texttt{m} and \texttt{n} are two dimensions.  Optional argument 
\texttt{skip} tells the function how many
bytes should be skipped before reading the data from the file.

Either \texttt{m} or \texttt{n}, but not both, can be zero, in which
case load() will compute this dimension according to the file size.

The argument \texttt{type} should have one of the following values:
``byte'', ``short'', ``int'', ``float'', or ``double''.

\subsubsection{Save}

Function save() saves a binary data to a data file.  It takes three or
four arguments, and has one of the following formats:
\begin{verbatim}
save( matrix, file, type )
save( matrix, file, type, skip )
\end{verbatim}
where $matrix$ is the matrix to be saved, and other arguments are
described in load().

\subsection{Matrix dimensions}

Functions width() and height() each take one matrix argument and
return the sizes of the horizontal and vertical dimensions,
respectively.

\subsection{Matrix generators}

Let \texttt{m} and \texttt{n} be two dimensions, following functions
will generate a new matrix:

\begin{verbatim}
zeros( m, n )
random( m, n )
eye( n )
indgen( m, n, s, dsm, dsn )
\end{verbatim}

Function zeros() returns a new matrix containing only zeros.  Function
random() returns a new matrix of uniformly distributed random values
within range [0,1].  Function eye() returns the identity matrix, i.e.,
a square matrix whose diagonal entries are ones and other entries are
zeros.  The last function, indgen(), generates a matrix, in which the
difference between two vertically adjacent entries are all equal to
\texttt{dsm} and the difference between two horizontally adjacent entries are
all equal to \texttt{dsn}.  The first entry of the new matrix is
\texttt{s}.  If \texttt{dsm} and \texttt{dsn} are both zero, indgen() 
will generate a matrix having all entries equal to \texttt{s}.

\subsection{Matrix operations}

\begin{verbatim}
inv( matrix )
det( matrix )
flip( matrix )
mirror( matrix )
\end{verbatim}

Function inv() inverts a matrix (just like 1/\texttt{matrix} does).
Function det() returns the determinant of a matrix (as double).
Function flip() returns a vertically flipped matrix.  Function
mirror() returns a horizontally mirrored matrix.

\begin{verbatim}
mul( A, B )
div( A, B )
\end{verbatim}
Functions mul() and div() compute the product and the quotient,
respectively, of corresponding entries in two matrix $A$ and $B$ having the
same size.  They both return a matrix with the same size.

\subsection{Order statistics}

Function min() returns the minimum value of a matrix.  Function max()
returns the maximum value of a matrix.  They both take a matrix as
the argument.

\subsection{Mathematic functions}

The following mathematic functions are supported:

\begin{tabular}{|l|l|}
\hline
round( $x$ ) & round to the nearest integer\\
ceil( $x$ ) & smallest integer greater than\\
floor( $x$ ) & largest integer less than\\
abs( $x$ ) & absolute value\\
exp( $x$ ) & $e^x$ \\
log( $x$ ) & $\ln x$\\
sin( $x$ ) & $\sin x$\\
cos( $x$ ) & $\cos x$\\
tan( $x$ ) & $\tan x$\\
asin( $x$ ) & $\arcsin x$\\
acos( $x$ ) & $\arccos x$\\
atan( $x$ ) & $\arctan x$\\
pow( $x$, $y$ ) & $x^y$ \\
\hline
\end{tabular}

Note that $x$ can be either a double or a matrix.  In the latter
case, this function is called for all entries of this matrix, and
a result matrix with the same dimensions is returned.  Argument
$y$ cannot be a matrix.

\subsection{Other functions}

\subsubsection{Count}

Function count() counts the number of entries selected by a matmask.
It accepts a matmask as the only argument.

%\appendix

%\section{Syntax summary}

%Note that this is just an abstract syntax specification, which
%is different from syntax rules actually used in the front end.

%\input{syntax}
%\end{document}
