
SHELL COMMAND LANGUAGE

The command parser is the common starting point
for  all  of the various input mechanisms of an application.
After initialization,
the parser waits for user input in order to perform tasks.
Strokes,  button  presses,  function keys, popup menus,
fixed menus, and ordinary keyboard text, all produce a single  line  of text.
Script files are also read and processed one line at a time.
These lines  are  sent  to  the
parser,  which splits them into separate constructs (words).
The  words  are  then  distributed  to  various   functional
modules which perform the desired action(s).
Each line of text is saved temporarily in a command  history
list for (possible) later re-use.

When a command is invoked, the parser  sets  the
status  indicator to "BUSY" until the command is completed or
requires user input.  At that point, the parser  resets  the
status indicator to "READY".  The parser has no knowledge of
what is a valid argument to a command.  It does know what
the  valid  command  names  are and how to derive arguments
from input following a simple grammar.

The following describes the grammar understood by the parser
and how the parser interacts with functional commands of an application.

The parser divides input lines into words at blanks  and
commas  with  the following exceptions:

    The characters ';', '(', ')', '{', and '}' form  separate  words.
These  parser metacharacters may be made part of other words or
have their special meaning suppressed by preceding them with a '\'.

    Strings  enclosed  in  matched  pairs  of quotation marks,
'''  or  '"',  form  a  single word (without the enclosing characters).
The special characters and the "other" type of quotation marks
are ignored inside a pair of quotes.
The exception is the '\' character,
which  must  be used  to  include  a  quotation mark within a quoted string.

A simple command is a sequence of words, the  first  of
which  specifies  the name of the command to be executed and
must not be enclosed in quotes. A command can  also  include
arguments,  which  are  either  points,  expressions, or
word(s), the first of which does not specify another command.
A simple  command  can  consist  of a variable assignment.
An empty command (nothing at all) causes the editor's  internal
command  stack  to  remove  its latest entry (pop).
Multiple commands on a single line are separated by the  ';'  character.

Words can be  abbreviated.   The  parser  maintains  an
internal  dictionary  of  valid substitutions which is consulted
when searching for a command name.
Commands which  require word arguments  must maintain their own
private dictionary of abbreviations.
The  case of characters (upper or lower) is ignored when
performing abbreviation substitution.

All letters entered are used when searching for a valid  substitution.
If  a match can be made for more than one entry,
that word is left  unchanged; this will typically generate an error.
For example, assume the parser's dictionary contains
"MOVE", "MOVETOLAYER", and "MOVSEGMENT".  The  input  "mov"
would  be  ambiguous;  "movs" would match and be translated
into "MOVSEGMENT"; "move" matches "MOVE" exactly  and  would
not be ambiguous;  "moves" would not match anything.

     Numeric expressions are evaluated by the parser  before
being  sent  as  a  word to the individual command.  Numeric
expressions are enclosed in a pair of  parentheses, '('  and
')'.   The  resulting  floating  point  value  is  sent as a
separate ASCII word  to  the  named  command.  The  standard
arithmetic  operators  '+',  '-', '*', and '/' are currently
supported.  Operands may be floating point numbers,  numeric
variables,  or  other  expressions.   Numbers may be entered
using standard floating point notation.

     A point is two numeric expressions contained  within  a
pair of parentheses, '(' and ')', that are not separated by an
operator.  This can cause problems  with  unary  minus  '-'.
For  example, is '(2 -3)' an expression for -1 or is it the
point X = 2.0, Y = -3.0?
The parser would  actually  interpret the sequence as a single expression and
not as a point.
You must either separate the expressions with a comma or enclose the
second  expression in another pair of parentheses in order to
specify a point in such a case; i.e. '(2, -3)' or '(2 (-3))'.

Point arguments are treated specially by the parser;
they are made to appear on an input line as if the
user  had  digitized them graphically.
This is accomplished by stripping the point arguments from the input
line  and sending them after calling the command (if any) as
if they were digitized. This may  cause  problems  if  you
send  the  wrong  number  of  points to a command, since the
erroneous point(s) cannot  be  referenced  easily.
Since strokes  are the most common use of textual point arguments,
consult the documentation on individual commands  for  the
correct arguments when creating stroke definitions.

User variables are created and destroyed via the VARIABLE command.
Additionally there are some predefined system variables,
such as those which specify the stroke location (SXLL, SYLL, etc.).
They are evaluated by the parser before being processed as a
single word or portion of an expression.
Variable  substitution  is  indicated by a word beginning with a '$' character.
The rest of the possibly abbreviated word must unambiguously match
a previously defined variable.

Presently, variables always have a global context.
In other words, there can  be  only  one  unique  name for every variable,
with no nesting or scoping.

Variables are set by an assignment statement,
except for the system variables, which are read-only.
The syntax for assignments is:

        $NUMERIC_VARIABLE = NUMERIC_EXPRESSION

        $STRING_VARIABLE = STRING_EXPRESSION

A STRING_EXPRESSION is one or more  words  to  be  concatenated.
The variable to the left of the '=' character is
set to the expression to the right of it.

Comments are not particularly useful for entering  commands  interactively -
they are intended primarily for script files.
There are two types of comments.  The  first
type  is the "REMARK" pseudo command.  When a command begins
with "REMARK" (or an unambiguous  abbreviation  thereof), the
rest  of  the  input line is ignored.
The second type of comment is more useful when only a portion of a line is to
be ignored; such comments may be enclosed within a pair of braces '{' and '}'.
Note that in either case, a comment is not an empty statement.
Thus, a  comment  on an otherwise empty line would not cause the parsing
stack to be popped.

When the parser detects an error in syntax,  a  message
is displayed in the message area and the rest of the line is
ignored.  Each command may also detect errors in  its  arguments  or  usage.
If a command detects an error, it signals
this to the parser; the parser will  discontinue  processing
the rest of the input line (if any).

The parser maintains an internal list of  the  last  30
input lines processed.  Each input line is assigned a number
starting with one when the editor is  first  invoked.   Note
that the line is placed on the list after being processed.

There are several methods of utilizing this history list.
The simplest method is to use the "HISTORY" command,
which displays the list in a popup menu.
The parser also recognizes the special character '!'  as  an
indication  to use the built-in history substitution mechanism.
Finally, the special editing  keys ^B  and  ^F (control-B and control-F)
may be used to access the history list.
See the HISTORY command and keyboard documentation for additional information.

When you input a line of text, it is  always  processed
by  the  command  parser with only one exception -
when an input line is typed in and terminated with a <RETURN>,
the Shell checks if the current command (if any) requires textual input;
if  this  is  the  case,  the command will receive the input line verbatim.
(Note that this only happens with typed input - input from strokes, menus, and
function keys are not treated specially.)
The  command  may  either accept  the line as valid,
or disregard it and let the parser process it as any other line.
This mechanism allows the user to input strings, etc. more easily
without worrying about correct syntax, ambiguous words,  and
lexical characters.

The standard keyboard bypass mechanism may occasionally
cause  unexpected  results  for certain commands.  To defeat
this bypass, the '>' character may be entered as the first character of the
line  to force the line to be parsed (without the '>' character).
