NAME
       Tcl - Tool Command Language

SYNOPSIS
       Summary of Tcl language syntax.

DESCRIPTION
       The following rules define the syntax and semantics of the
       Tcl language:

       [1] Commands.
              A Tcl script is a string  containing  one  or  more
              commands.   Semi-colons  and  newlines  are command
              separators unless quoted as described below.  Close
              brackets  are  command  terminators  during command
              substitution (see below) unless quoted.

       [2] Evaluation.
              A command is evaluated in two  steps.   First,  the
              Tcl  interpreter  breaks the command into words and
              performs substitutions as described  below.   These
              substitutions are performed in the same way for all
              commands.  The first word is used to locate a  com-
              mand  procedure  to carry out the command, then all
              of the words of the command are passed to the  com-
              mand  procedure.   The command procedure is free to
              interpret each of its words in any  way  it  likes,
              such  as  an  integer,  variable name, list, or Tcl
              script.  Different commands interpret  their  words
              differently.

       [3] Words.
              Words  of  a  command  are separated by white space
              (except for newlines,  which  are  command  separa-
              tors).

       [4] Double quotes.
              If  the  first  character of a word is double-quote
              (``"'') then the word is  terminated  by  the  next
              double-quote   character.   If  semi-colons,  close
              brackets, or white space characters (including new-
              lines)  appear  between  the  quotes  then they are
              treated as ordinary characters and included in  the
              word.  Command substitution, variable substitution,
              and backslash substitution  are  performed  on  the
              characters  between  the quotes as described below.
              The double-quotes are not retained as part  of  the
              word.

       [5] Braces.
              If  the  first character of a word is an open brace
              (``{'') then the word is terminated by the matching
              close  brace (``}'').  Braces nest within the word:
              for each additional open brace  there  must  be  an
              additional  close  brace (however, if an open brace
              or close brace within the word  is  quoted  with  a
              backslash  then  it  is not counted in locating the
              matching close brace).  No substitutions  are  per-
              formed  on the characters between the braces except
              for   backslash-newline   substitutions   described
              below,  nor  do semi-colons, newlines, close brack-
              ets,   or   white   space   receive   any   special
              interpretation.   The  word will consist of exactly
              the  characters  between  the  outer  braces,   not
              including the braces themselves.

       [6] Command substitution.
              If a word contains an open bracket (``['') then Tcl
              performs  command  substitution.   To  do  this  it
              invokes  the Tcl interpreter recursively to process
              the characters following the open bracket as a  Tcl
              script.   The script may contain any number of com-
              mands and must be terminated  by  a  close  bracket
              (``]'').  The result of the script (i.e. the result
              of its last command) is substituted into  the  word
              in  place of the brackets and all of the characters
              between them.  There may be any number  of  command
              substitutions  in a single word.  Command substitu-
              tion is not performed on words enclosed in  braces.

       [7] Variable substitution.
              If  a  word contains a dollar-sign (``$'') then Tcl
              performs variable  substitution:   the  dollar-sign
              and  the  following  characters are replaced in the
              word by the value of a variable.  Variable  substi-
              tution may take any of the following forms:

              $name          Name  is  the name of a scalar vari-
                             able;  the name is a sequence of one
                             or  more  characters that are a let-
                             ter, digit, underscore, or namespace
                             separators (two or more colons).

              $name(index)   Name  gives  the  name  of  an array
                             variable and index gives the name of
                             an  element within that array.  Name
                             must contain only  letters,  digits,
                             underscores,  and  namespace separa-
                             tors, and may be  an  empty  string.
                             Command substitutions, variable sub-
                             stitutions, and backslash  substitu-
                             tions  are  performed on the charac-
                             ters of index.

              ${name}        Name is the name of a  scalar  vari-
                             able.  It may contain any characters
                             whatsoever except for close  braces.

              There  may  be any number of variable substitutions
              in a single word.   Variable  substitution  is  not
              performed on words enclosed in braces.

       [8] Backslash substitution.
              If  a  backslash (``\'') appears within a word then
              backslash substitution occurs.  In  all  cases  but
              those  described below the backslash is dropped and
              the following character is treated as  an  ordinary
              character  and  included  in the word.  This allows
              characters such as double quotes,  close  brackets,
              and  dollar  signs  to be included in words without
              triggering special processing.  The following table
              lists the backslash sequences that are handled spe-
              cially, along with the  value  that  replaces  each
              sequence.

              \a     Audible alert (bell) (0x7).

              \b     Backspace (0x8).

              \f     Form feed (0xc).

              \n     Newline (0xa).

              \r     Carriage-return (0xd).

              \t     Tab (0x9).

              \v     Vertical tab (0xb).

              \<newline>whiteSpace
                     A  single space character replaces the back-
                     slash, newline,  and  all  spaces  and  tabs
                     after  the newline.  This backslash sequence
                     is unique in that it is replaced in a  sepa-
                     rate pre-pass before the command is actually
                     parsed.  This means that it will be replaced
                     even  when it occurs between braces, and the
                     resulting space will be treated  as  a  word
                     separator if it isn't in braces or quotes.

              \\     Backslash (``\'').

              \ooo   The  digits ooo (one, two, or three of them)
                     give an eight-bit octal value for  the  Uni-
                     code  character  that will be inserted.  The
                     upper bits of the Unicode character will  be
                     0.

              \xhh   The  hexadecimal digits hh give an eight-bit
                     hexadecimal value for the Unicode  character
                     that  will  be inserted.  Any number of hex-
                     adecimal digits may be present; however, all
                     but  the last two are ignored (the result is
                     always a one-byte quantity).  The upper bits
                     of the Unicode character will be 0.

              \uhhhh The   hexadecimal  digits  hhhh  (one,  two,
                     three, or four of them) give  a  sixteen-bit
                     hexadecimal  value for the Unicode character
                     that will be inserted.

              Backslash substitution is not  performed  on  words
              enclosed in braces, except for backslash-newline as
              described above.

       [9] Comments.
              If a hash character  (``#'')  appears  at  a  point
              where  Tcl  is expecting the first character of the
              first word of a command, then  the  hash  character
              and  the  characters that follow it, up through the
              next newline, are treated as a comment and ignored.
              The comment character only has significance when it
              appears at the beginning of a command.

       [10] Order of substitution.
              Each character is processed exactly once by the Tcl
              interpreter as part of creating the words of a com-
              mand.  For example, if variable substitution occurs
              then  no further substitutions are performed on the
              value of the variable;  the value is inserted  into
              the  word verbatim.  If command substitution occurs
              then the nested command is  processed  entirely  by
              the  recursive call to the Tcl interpreter; no sub-
              stitutions  are   performed   before   making   the
              recursive  call and no additional substitutions are
              performed on the result of the nested script.

              Substitutions take place from left  to  right,  and
              each  substitution  is  evaluated completely before
              attempting to evaluate the next.  Thus, a  sequence
              like
                     set y [set x 0][incr x][incr x]
              will always set the variable y to the value, 012.

       [11] Substitution and word boundaries.
              Substitutions  do not affect the word boundaries of
              a command.  For example, during variable  substitu-
              tion  the entire value of the variable becomes part
              of a single word, even if the variable's value con-
