Syntax Tokens
*************

Nagelfar's syntax descriptions for a command consists of little
language describing the arguments to the command.

Check the syntax database (syntaxdb.tcl) or in the database browser in
the gui for examples.


Entry
=====

For each command there is a syntax entry in the database. An entry
must be a valid list.

If an entry is an integer, the number of arguments are just checked
against it.

If an entry is of the format "r min ?max?" it specifies a range for
allowed number of arguments.

Otherwise an entry must be a valid list of tokens as described below.


Tokens
======

* x Anything, the argument is not checked.

* k Any, do not check against variables. Assumed to be keyword.

* o Option, i.e anything starting with -. An option may consume a
  second arg if the option database says so.

* p Option+Any i.e. (o x) (p as in option Pair)

* s Subcommand

* e Expression

* E Expression that should be in braces

* re Regular expression like regexp/regsub

* n, v and l all mark variable names. Those arguments will not be
  checked against known variables to detect missing $.

* n The variable does not have to exist, and is set by the command.
  (out parameter)

* v The variable must exist. It is not marked as set. (in or inout
  parameter)

* l Does not have to exist. It will be marked as known, but not set.

* nl Like n, but a list of variable names

* c  Code, checked in surrounding context If an integer is added to
  it, that number of arguments are added to the code to emulate a
  command prefix. (cg has this too)

* cg Code, checked in global context

* cn Code, checked in a virtual namespace

* cl Code, checked in its own local context

* cv Code, checked in its own local context, preceded by variable list

* All d* tokens are definitions. Most of them define a new command.

* dc  Define new command. If followed by =cmd, it copies syntax from
  cmd.

* do  Define object. If followed by =cmd, it copies syntax from cmd.

* di  Define inheritance

* dk  Define constructor (args+body)

* dd  Define destructor (just body)

* dp  Define procedure (name+args+body)

* dm  Define method (name+args+body)

* dmp Define method/procedure (name+args+body)

* div Define implicit variable


Modifiers
---------

A modifier is put after the token (no spaces).

* ? Zero or One

* * Zero or more  ( not supported by all tokens)

* . One or nothing at all

If a token is followed by a parenthesis it denotes a type. The local
variable in the proc is marked with this type. Any modifier goes after
the parens.

Example:   x(varName)   x(script)?

If a token is followed by a number it is token dependent. Any modifier
goes after the number.

Example:   c2   cg4?

If a token is followed by =, it is a token dependent modifier.

Example:   do=_stdclass_oo


Multi-tokens
------------

Multiple tokens can be joined with "&" to consume multiple arguments.
Such a multi token must have an * or ? modifier. If they are mandatory
they can be just separated. The point of multi-tokens is to have them
repeat as a group. The individual tokens may not have modifiers that
make them optional, but may use e.g. parenthesis.

   ##nagelfar syntax dict\ create x&x*


Subcommands
===========

For commands that have subcommands (as indicated by token "s"),
separate descriptions can be set up for each subcommand. If a syntax
for a subcommand is defined, it is used to check the rest.

   ##nagelfar syntax string             s x x*
   ##nagelfar syntax string\ bytelength 1
   ##nagelfar syntax string\ compare    o* x x

The allowed list of subcommands is defined by the "subcmd" syntax. To
add to the list, use "subcmd+"

   ##nagelfar subcmd string bytelength compare equal is
   ##nagelfar subcmd+ file mystat


Options
=======

For commands that have options (as indicated by tokens "o" and "p"),
the options database provides details. To list the allowed options the
"option" syntax is used, and to add to a known list "option+" is used.

   ##nagelfar option send -- -async -displayof
   ##nagelfar option string\ is -failindex -strict

The syntax for the parameter of an option is set like this.

   ##nagelfar option send\ -displayof x
   ##nagelfar option string\ is\ -failindex n

For the "p" token, an option always take a parameter and it defaults
to "x" syntax. For the "o" token, on option only takes a parameter if
a parameter syntax is set up. Otherwise it is assumed the option is
stand-alone.


Different syntax for different number of arguments
==================================================

If the first token ends with : it means that there are different
syntax descriptions for different number of arguments.  Any token
ending with : starts a syntax for the number of arguments that the
number preceding it says. A lone : starts the default syntax.

Example: "1: x 2: n n : e x*"

If this is checked against a call with two args, the "n n" part is
extracted and used as the entry according to all other rules.
