Contents

syntax

Keywords: syntax, control, general, character variables, logical variables, variables, missing values, null variables

                        Commands and Statements
A MacAnova command or statement is a sequence of characters typed in at
the keyboard followed by ';' or '<cr>' (the RETURN or ENTER key).  The
first character should not be '!' unless it is a "shell escape" (see
shell()).

Typical commands or statements are 'x <- vector(1.2,3.1,5.3,2.4)<cr>'
(assign the vector (1.2,3.1,5.3,2.4) to variable x), 'print(x)<cr>'
(print the value of variable x), 'regress("y=x1+x2+x3")<cr>' (compute a
regression of variable y on variables x1, x2 and x3), or 'y <-
3*x^2<cr>' (assign to variable y the value of 3 times x squared).

You may put several commands or statements separated by ';' on a single
line terminated by <cr>.  An example would be
  Cmd> regress("y=x"); plot(x,RESIDUALS)<cr>
When you press '<cr>', but not before, all the commands or statements in
the line are executed one after the other.

One type of statement consists solely of a number or an algebraic
expression involving numbers or variable names.  Examples are '17.3',
'3*y', 'sqrt(4+cos(-1.32))' and '3*log(640320)/sqrt(163)'.  The only
effect of this type of statement is to print out the value.  This allows
MacAnova to be used as a symbolic calculator.  Here are some examples:
  Cmd> 17.3
  (1)         17.3

  Cmd> 3*log(640320)/sqrt(163)
  (1)       3.1416

  Cmd> 3*y
  (1)       25.584       28.817       30.636

  Cmd> "Hello!"
  (1) "Hello!"

Below for brevity both commands and statements are usually just called
'commands'.

                        Side Effects of Commands
Some commands have "side effects" such as printing tables or creating
variables containing the results of computation.  For example, although
anova() returns only a NULL value (see topic 'NULL'), it has side
effects, namely the printing of an analysis of variance table and
creation of several named variables such as RESIDUALS, SS and DF.

                               Variables
Data are stored in permanent or temporary "variables" with names of up
to 12 characters.  Typical names might be 'x1', 'data', 'weight' or
'time_of_day'.

The names of permanent variables start with a letter or '_', while the
names of temporary variables start with '@' followed by a letter or
'_'.  The remainder of a name consists of letter, digits or '_'.  Names
are case sensitive (for example, 'residuals' is a different name from
'Residuals'.  Some variables are "invisible".  See topic
'variables:"invisible"'.

Typically you will select names that are relevant to the problem such as
'weight', 'residuals', or 'depv'.

A name may not be the same as a command name.  For instance, you can't
use 'rep' as a variable name because there is a command 'rep'.

Typing the name of a variable that is not "invisible" prints out its
value.

See topic 'variables' for more details.

                              Command Line
The 'command line' consists of all the commands that are executed by a
single <cr>.  The command line follows the standard MacAnova prompt
"Cmd> ", and may, in fact be continued on several actual lines; see
next paragraph.

When a command line becomes longer than one physical line, you can just
keep typing as the characters wrap around to the next line (they do not
wrap in the Windows and Motif versions; see topic 'wx').  Alternatively,
you may continue a line by typing '\<cr>'.  Continue typing the line
after the prompt "More> " (there is no "More> " prompt in windowed
versions -- Macintosh, Windows or Motif).  If the break is at the end of
a command, you need to type ';' before '\<cr>'.  In the limited memory
DOS version you should probably always break lines with '\<cr>' because
DOS imposes a maximum length of 128 characters for lines that can be
entered at the keyboard.

If you make a mistake, you may backspace to erase the error.  On
windowed versions (Macintosh, Windows, Motif) you can move the cursor
with the mouse at any time to make corrections anywhere in the command
line.  Except in the limited memory DOS version, you can also use the
arrow keys to back up to edit the command line.

                           Compound Commands
A "compound command" is a sequence of one or more commands inside curly
brackets '{' and '}'.  For example
   {i <- i+1; plot(x[,i],y[,i])}
is a compound command.  Compound commands are used primarily with
control constructs such as 'if', 'for' and 'while'.

Once you have started typing a compound command by pressing '{' the
command line is not executed by <cr> before you type a matching '}'.
Below, '{...}'  represents an arbitrary compound command.

In a compound command, you can type <cr> at any place where a semicolon
';' would be appropriate; the compound command will not be executed
until you have pressed <cr> after the closing '}'.

You may nest compound commands ({...{...}...}).  None of them is
executed until you terminate the outermost compound command with '}' and
press <cr>.

A common mistake is to fail to terminate a compound command with '}'.
MacAnova appears to be "hung up".  Actually it is just waiting for you
to finish what you started.  Until the compound command is complete,
MacAnova has no way to recogonize that you are through typing the
command line.  You can either type '}<cr>' or press the interrupt key
and start over.

                         MacAnova as a Language
The organization of MacAnova commands can be considered as a "functional
language," in the sense that the components of commands are functions or
operators which take arguments or operands as inputs and may compute
values as outputs.

The arguments of (inputs to) a named command or macro are separated by
commas and enclosed in '(' and ')', as in 'print(x,y,z)'.  Some named
commands or macros require no arguments.  In this case you just put '()'
after the name, as in 'getoptions()'.  In MacAnova documentation,
including help() output, a named command or macro is referred to by its
name followed by '()', for example, 'log10()' and 'getmacros()'.

All commands, including compound commands (see below) have a value.  For
example, 'sqrt(3)' has the value 1.73205080756888 and '4*atan(1)' has
value 3.14159265358979.

Some commands such as print() and regress() have values which are NULL
(see topic 'NULL').  In addition, an explicitly empty command, ';;' or
'();' has a NULL value.  For obvious reasons, you can't use commands
with NULL values in algebraic expressions or comparisons or in other
contexts require data.

A named command that returns a non-NULL value is often referred to as a
"function."

A few functions (for example getseeds()) return an "invisible" value
that can be assigned but is not automatically printed when it is not
assigned.  See topic 'variables:"invisible"'.

The value of a compound command is the value of the last command in the
curly brackets.  If its last command is empty (';;' or '();'), a
compound statement has a NULL value.  You can use a compound command
which has a non-NULL value in an expression.  For example,
  Cmd> xbar <- {print(x); sum(x)}/n
prints x and computes xbar = sum(x)/n, because the value of '{...}' is
the value of 'sum(x)'.

Output from functions may be arithmetically combined (for example,
'cos(x) + 3*sin(y)') and the value of (output from) one function may be
an argument to (input for) another, (for example, 'cos(sqrt(x+y))').

See also topics 'arithmetic' and 'transformations'.

                     Conditional Execution and Looping
There are several syntax elements that you can use to control which
commands are executed and in what order.  Here is a brief summary:

 Conditional execution
   if(Logical){...}
   if(Logical){...}else{...}
   if(Logical){...}elseif(Logical){...}else{...}
 Looping
   for(Var,Vector){...}
   for(Var,start,end[,increment]){...}
   while(Logical){...}
 Escaping from a loop
   break, break n, breakall, breakif()
 Skipping to the end of a loop
   next, next n
 Leaving a macro, possibly returning a value
   return

Logical must be a LOGICAL scalar variable or expression such as 'i < 4'.
Vector must be a REAL vector and start, end and increment must be REAL
scalars.  See below for types of data.

The first '{' following 'if(...)', 'for(...)', and 'while(...)' must be
on the same line.

See topics 'if', 'for', 'while', 'break' and breakif() for more details.

                             Types of Data
There are several types of data, including REAL, LOGICAL, CHARACTER,
GRAPH, STRUCTURE and NULL.  In certain output, LOGICAL, CHARACTER, and
STRUCTURE are abbreviated as LOGIC, CHAR, and STRUC, respectively.

REAL data elements are numbers and can be entered from the keyboard,
read from a data file, or computed by arithmetic expressions,
transformations and other functions or macros.  You enter numbers as
integers without a decimal point (-321), as decimal numbers (31.4159),
or using exponential notation (7.2e+9 = 7.2*1000000000).

You can separate digits by '_' for clarity, but not after 'e'.  Thus
123_456.789_1 is equivalent to 123456.7891.  See topic 'numbers' for
more information.

A missing value is represented by a special internal code named MISSING.
When entering data at the keyboard, you enter a missing value as '?'.
On output, a missing value usually printed as "MISSING" but you can
specify a different output coding, say "?", by setoptions(missing:"?")
(see setoptions(), subtopic 'options:"missing"').

Virtually all commands and operations pay at least token attention to
MISSING, although at present nothing is done that is more complicated
than omitting cases with MISSING or setting to MISSING a result item
corresponding to a MISSING input item.

You can do arithmetic on REAL data using the arithmetic operators '+',
'-', '*', '^' or '**', and '%%' (for example, a * (b + c)).  See
topic 'arithmetic'.

You can compare REAL data items using comparison operators '<', '>',
'==', '!=', '<=', and '>='.  Except for '==' and '!=', a comparison with
a MISSING value yields a MISSING LOGICAL value.  See topic 'logic'.

LOGICAL data have values limited to True, False and MISSING and are
entered and printed as 'T' (True) or 'F' (False).  Comparison
expressions (for example 'a < 3') generate LOGICAL data as values.
See topic 'logic' for detailed information.

You can combine LOGICAL variables and expressions using logical
operators '&&', '||' and '!'.  For example, '(x > 3) && !(x > 5)' has
value True if and only if both (x > 3) and (x <= 5) are True, that is if
3 < x <= 5.  Similarly, '(x > 0) || (abs(x) == 3)' has value True if and
only if x > 0 or |x| = 3 (or both).

You can use LOGICAL data in arithmetic expressions and comparisons, with
True and False being translated as 1 and 0, respectively.  For example,
F*T is 0, 2*T is 2, and F < T is True .  Logical variables can also be
used in place of REAL variables as argument to some, but not all
functions such as sum(), prod() and max().

A CHARACTER data element consists of a sequence of characters, that is
letters, numbers, punctuation or anything else that can be typed.  It is
sometimes called a "string."  When entering CHARACTER data you must
enclose each string in double quotes as in
  Cmd> greetings <- "Hello!"
The opening and closing double quotes are not part of the string.  You
include a double quote in a string by prefixing ('escaping') it with
'\'.  For example,
  Cmd> a <- "He said, \"Hello\""
assigns the string 'He said, "Hello"' to variable a.  You can include
characters '\', newline and tab by '\\', '\n' and '\t', respectively,
using a convention borrowed from Unix/Linux.  For example,
  Cmd> b <- "1\t2\t3"
assigns to b the string consisting of '1', '2', and '3' separated by tab
characters.

Once you have started typing a CHARACTER string with '"', MacAnova
interprets everything, including <cr>, up to the next (non-escaped) '"'
as part of the string.  It does not recognize the command line to be
complete until you have typed the closing '"'.

A common mistake is to forget to terminate a string with '"'; MacAnova
appears to "hang", doing nothing.  You need to type a closing '"' and
terminate the line or press the interrupt key and start again.

You can include in a string any character, even one you cannot type
directly, using the so called escaped octal representation of its
internal (ASCII) code.  For example, since 1*8 + 5 = 13, '15' is the
octal (base 8) representation of 13 and "\15" or "\015" is the character
(usually CR) with code 13.  Similarly, because '117' is the octal
representation for 1*8*8 + 1*8 + 7 = 79, the ASCII code for 'O', "\117"
is equivalent to "O".  Also acceptable are escaped hexadecimal
representations of the form "\xmn", where m and n are hexadecimal digits
(0 - 9, and a - f or A - F).  For example, "\117" and "\x4f" are both
equal to "O" (4*16 + 15 = 79).

You can compare CHARACTER data items using comparison operators '<',
'>', '==', '!=', '<=', and '>='.  The ordering of letters is based on
their ASCII representation with "A" < "B" < ... < "Z" < "a" < ... < "z".
For example, '"A" < "B"', '"a" < "B"' and '"foo" == "bar"' have values
True, False and False, respectively.  See topic 'variables' for more
detail.

A GRAPH variable encapsulate all the information needed to draw a graph
or other plot.  You can display the plot in GRAPH variable GraphVar by
'showplot(graphVar)'.  See topic 'graphs' for more information.

A structure is made up of one or more named data components that may be
of any type.  See topic 'structures' for details.

A NULL variable contains no data.  See topic 'NULL' for details.

                   Assignment of Values to Variables
You assign values to a variable using the left pointing arrow '<-'
made up of the two characters "less than" and "minus".  For example,
'foo <- 5' assigns the value 5 to the variable foo.  If foo did not
previously exist, it is created; otherwise, its previous value is
discarded and foo is re-defined.  An expression of the form 'x <- 3',
say, is always interpreted as 'x <- 3' rather than as 'x < -3'.  If you
want the latter, be sure to put a space before '-3'.

You can string several assignments together.  For example,
  Cmd> a <- b <- 1
is interpreted from right to left, first assigning 1 to b and then
assigning the new value of b to a.

See topic 'assignment' for information about the value of an assignment
statement, assignment to subscript-selected elements of a variable, and
assignments to components of a structure, and topic 'arithmetic' about
arithmetic assignment operators <-+, <--, <-*, <-/, <-%% and <-^.

                          Organization of Data
REAL, LOGICAL, or CHARACTER data may be organized as scalars, vectors,
matrices, or arrays.  The transpose of a matrix or array x may be typed
as x' or as t(x).  Matrix multiplication operators (applicable only to
REAL data) are %*%, %c%, and %C%.

See also topics 'vectors', 'matrices', vector(), matrix(), array(),
dim(), ndims(), ismatrix(), nrows(), ncols(), 'transpose'.

Data may have vectors of labels for each coordinate.  In particular,
matrices may have row and column labels.  Labels propagate through
operations and functions in a fairly sensible way.  Labels are primarily
used in output .  See topic 'labels' for information.

                               Subscripts
You refer to an element or set of elements of a vector, matrix, or array
by using subscripts -- numbers or variables enclosed in square brackets
'[...]' immediately following the variable name.

For example, 'x[3,4]' is the element in row 3 and column 4 of matrix x,
'x[vector(1,3,5),4]' consists of rows 1, 3 and 5 of column 5 of x,
'x[3,]' is row 3 of x and 'x[,4]' is column 4 of x.

You can assign values to subscripted elements, as in 'x[3,4] <- 17' or
'x[3,] <- 5'.  See topics 'matrices', matrix(), array(), 'transpose',
'subscripts', 'assignment'.

When x is a structure, you can use x[[J]] in place of x[J].  When x is
not a structure, x[[1]] is the same as x and x[[J]] is illegal unless J
= 1.

                          Combining Data Items
There are commands to combine several data items into a larger vector,
matrix, or structure.  See vector(), hconcat(), vconcat(), structure(),
strconcat().

                            Keyword Phrases
Some command arguments can be "keyword phases" in the form
'keyword:value'.  For example, on several commands that write numbers,
the argument 'nsig:8' specifies that up to 8 significant digits are to
be printed and 'format:"18.13g"' specifies a format with width 18 and 13
significant digits.

LOGICAL keyword phrases like 'keep:T' or 'coefs:F' are particularly
common.  These enable (T) or suppress (F) alternative actions of a
command.  See topic 'keywords' for details.

             Indirect Reference to Variables and Constants
<<String>>, where String is a quoted string or CHARACTER variable whose
value is the name of a variable, refers indirectly to that variable. For
example, '<<"cos">>(PI/4)' and '<<"E">>+3' are equivalent to 'cos(PI/4)'
and 'E+3', and, after the command 'a <- vector("x1","x2","x3")' creates
a CHARACTER vector a, '<<a[2]>> <- 3' is equivalent to 'x2 <- 3'.

The following line creates variables x1, x2, and x3 from the columns of
matrix x.

  Cmd> for(i,run(ncols(x))){<<paste("x",i,sep:"")>> <- x[,i];;}

See topics paste(), 'for' and 'subscripts'.

Indirect reference works even with keywords and structure component
names.  For example, setoptions(<<"nsig">>:5) is equivalent to
setoptions(nsig:5) and, when Str is a structure with a component named
'x', Str$<<"x">> is equivalent to Str$x.

If String is "?", "T", "F", or "NULL", the value of <<String>> is
MISSING, True, False, or a NULL variable.  If String represents a
number, <<String>> is the value of the number.  For example
10*<<"-123.456">> has value -1234.56.  If String represents a CHARACTER
scalar of the form "\"string without non-escaped quotes\"", <<String>>
is equivalent to "string without non-escaped quotes".  For example,
"ABCD" == <<"\"ABCD\"">> is True.

More generally, String can contain one or more MacAnova expressions or
commands.  The commands are executed and the value of <<String>> is the
value of the last command in String.  In this case, <<String>>
essentially does the same as evaluate(String).  There are some
restrictions on what commands can appear in String.  See evaluate().
  Cmd> <<"sqrt(2*PI)">>
  (1)       2.5066

On a Macintosh, you can use Option+\ and Option+| instead of << and >>,
respectively.

                      Re-executing a Command Line
Just before MacAnova accepts a new command line, the immediately
preceding command line is saved as macro LASTLINE.  This allows you to
re-execute the immediately preceding command line by typing LASTLINE()
Alternatively, you can used pre-defined macro redo(): redo() makes a
copy of LASTLINE as macro REDO() and then executes REDO().  You can
subsequently re-execute the same line one or more additional times by
typing REDO().  You cannot use redo() on two successive lines.  See
topics 'macros', redo().

On machines where macro edit() is defined, you can edit the immediately
preceding line and re-execute the modified version by
  Cmd> REDO <- edit(LASTLINE); REDO()
See topic edit().

See also topics 'comments', 'interrupt', 'quitting'.