NAME

       Tcl_ParseCommand,      Tcl_ParseExpr,     Tcl_ParseBraces,
       Tcl_ParseQuotedString,   Tcl_ParseVarName,   Tcl_ParseVar,
       Tcl_FreeParse,  Tcl_EvalTokens  -  parse  Tcl  scripts and
       expressions


SYNOPSIS

       #include <tcl.h>

       int
       Tcl_ParseCommand(interp, string, numBytes, nested, parsePtr)

       int
       Tcl_ParseExpr(interp, string, numBytes, parsePtr)

       int
       Tcl_ParseBraces(interp, string, numBytes, parsePtr, append, termPtr)

       int
       Tcl_ParseQuotedString(interp, string, numBytes, parsePtr, append, termPtr)

       int
       Tcl_ParseVarName(interp, string, numBytes, parsePtr, append)

       char *
       Tcl_ParseVar(interp, string, termPtr)

       Tcl_FreeParse(usedParsePtr)

       Tcl_Obj *
       Tcl_EvalTokens(interp, tokenPtr, numTokens)


ARGUMENTS

       Tcl_Interp   *interp         (out)     For      procedures
                                              other          than
                                              Tcl_FreeParse   and
                                              Tcl_EvalTokens,
                                              used only for error
                                              reporting; if NULL,
                                              then no error  mes­
                                              sages    are   left
                                              after errors.   For
                                              Tcl_EvalTokens,
                                              determines the con­
                                              text for evaluating
                                              the script and also
                                              is  used  for error
                                              reporting; must not
                                              be NULL.

       char         *string         (in)      Pointer   to  first

       int          numBytes        (in)      Number  of bytes in
                                              string, not includ­
                                              ing any terminating
                                              null character.  If
                                              less  than  0  then
                                              the script consists
                                              of  all  characters
                                              in string up to the
                                              first  null charac­
                                              ter.

       int          nested          (in)      Non-zero means that
                                              the  script is part
                                              of a  command  sub­
                                              stitution   so   an
                                              unquoted      close
                                              bracket  should  be
                                              treated as  a  com­
                                              mand    terminator.
                                              If   zero,    close
                                              brackets   have  no
                                              special meaning.

       int          append          (in)      Non-zero means that
                                              *parsePtr   already
                                              contains      valid
                                              tokens;   the   new
                                              tokens  should   be
                                              appended  to  those
                                              already    present.
                                              Zero   means   that
                                              *parsePtr is unini­
                                              tialized;       any
                                              information  in  it
                                              is  ignored.   This
                                              argument  is   nor­
                                              mally 0.

       Tcl_Parse    *parsePtr       (out)     Points to structure
                                              to  fill  in   with
                                              information   about
                                              the parsed command,
                                              expression,   vari­
                                              able   name,   etc.
                                              Any previous infor­
                                              mation   in    this
                                              structure        is
                                              ignored,     unless
                                              append  is non-zero
                                              in   a   call    to
                                              Tcl_ParseBraces,
                                              seVarName.

       char         **termPtr       (out)     If not NULL, points
                                              to a location where
                                              Tcl_ParseBraces,
                                              Tcl_ParseQuoted­
                                              String,         and
                                              Tcl_ParseVar   will
                                              store a pointer  to
                                              the  character just
                                              after the terminat­
                                              ing  character (the
                                              close-brace,    the
                                              last  character  of
                                              the variable  name,
                                              or  the close-quote
                                              (respectively))  if
                                              the  parse was suc­
                                              cessful.

       Tcl_Parse    *usedParsePtr   (in)      Points to structure
                                              that  was filled in
                                              by a previous  call
                                              to    Tcl_ParseCom­
                                              mand,    Tcl_Parse­
                                              Expr, Tcl_ParseVar­
                                              Name, etc.
_________________________________________________________________



DESCRIPTION

       These procedures parse Tcl commands  or  portions  of  Tcl
       commands  such  as expressions or references to variables.
       Each procedure takes a pointer to  a  script  (or  portion
       thereof) and fills in the structure pointed to by parsePtr
       with a collection of  tokens  describing  the  information
       that  was  parsed.  The procedures normally return TCL_OK.
       However, if an error occurs then  they  return  TCL_ERROR,
       leave  an  error  message in interp's result (if interp is
       not NULL), and leave nothing in parsePtr.

       Tcl_ParseCommand is a procedure that parses  Tcl  scripts.
       Given  a  pointer to a script, it parses the first command
       from the script.  If the command was parsed  successfully,
       Tcl_ParseCommand returns TCL_OK and fills in the structure
       pointed to by parsePtr with information about  the  struc­
       ture  of the command (see below for details).  If an error
       occurred  in  parsing  the  command  then   TCL_ERROR   is
       returned, an error message is left in interp's result, and
       no information is left at *parsePtr.

       Tcl_ParseExpr parses Tcl expressions.  Given a pointer  to
       fully,  Tcl_ParseExpr  returns  TCL_OK  and  fills  in the
       structure pointed to by parsePtr  with  information  about
       the  structure  of the expression (see below for details).
       If an error occurred in parsing the command then TCL_ERROR
       is  returned, an error message is left in interp's result,
       and no information is left at *parsePtr.

       Tcl_ParseBraces  parses  a  string  or  command   argument
       enclosed  in  braces such as {hello} or {string \t with \t
       tabs} from the beginning  of  its  argument  string.   The
       first character of string must be {.  If the braced string
       was parsed successfully, Tcl_ParseBraces  returns  TCL_OK,
       fills  in the structure pointed to by parsePtr with infor­
       mation about the structure of the string  (see  below  for
       details), and stores a pointer to the character just after
       the terminating } in the location given by  *termPtr.   If
       an  error  occurrs while parsing the string then TCL_ERROR
       is returned, an error message is left in interp's  result,
       and no information is left at *parsePtr or *termPtr.

       Tcl_ParseQuotedString  parses  a double-quoted string such
       as "sum is [expr $a+$b]" from the beginning of  the  argu­
       ment string.  The first character of string must be ".  If
       the  double-quoted   string   was   parsed   successfully,
       Tcl_ParseQuotedString  returns TCL_OK, fills in the struc­
       ture pointed to by parsePtr  with  information  about  the
       structure  of  the  string  (see  below  for details), and
       stores a pointer to the character just after the terminat­
       ing  "  in  the  location  given by *termPtr.  If an error
       occurrs  while  parsing  the  string  then  TCL_ERROR   is
       returned, an error message is left in interp's result, and
       no information is left at *parsePtr or *termPtr.

       Tcl_ParseVarName parses a Tcl variable reference  such  as
       $abc  or  $x([expr  $index + 1]) from the beginning of its
       string argument.  The first character of string must be $.
       If  a variable name was parsed successfully, Tcl_ParseVar­
       Name returns TCL_OK and fills in the structure pointed  to
       by  parsePtr  with  information about the structure of the
       variable name  (see  below  for  details).   If  an  error
       occurrs  while  parsing  the  command  then  TCL_ERROR  is
       returned, an error message is left in interp's result  (if
       interp   isn't  NULL),  and  no  information  is  left  at
       *parsePtr.

       Tcl_ParseVar parse a Tcl variable reference such  as  $abc
       or  $x([expr $index + 1]) from the beginning of its string
       argument.  The first character of string must  be  $.   If
       the  variable  name  is  parsed successfully, Tcl_ParseVar
       returns a pointer to the string value of the variable.  If
       an  error  occurs while parsing, then NULL is returned and
       an error message is left in interp's result.
       Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, and
       Tcl_ParseVarName may include dynamically allocated memory.
       If  these  five  parsing procedures return TCL_OK then the
       caller must invoke Tcl_FreeParse to release the storage at
       *parsePtr.   These procedures ignore any existing informa­
       tion in *parsePtr  (unless  append  is  non-zero),  so  if
       repeated  calls  are  being  made  to  any  of  them  then
       Tcl_FreeParse must be invoked once after each call.

       Tcl_EvalTokens evaluates a sequence of parse tokens from a
       Tcl_Parse  structure.  The tokens typically consist of all
       the tokens in a word or all the tokens that  make  up  the
       index  for  a reference to an array variable.  Tcl_EvalTo­
       kens performs the substitutions requested by  the  tokens,
       concatenates  the resulting values, and returns the result
       in a new Tcl_Obj.   The  reference  count  of  the  object
       returned  as  result  has  been incremented, so the caller
       must invoke Tcl_DecrRefCount when it is finished with  the
       object.   If  an  error occurs while evaluating the tokens
       (such as a reference to a non-existent variable) then  the
       return  value  is  NULL  and  an  error message is left in
       interp's result.



TCL_PARSE STRUCTURE

       Tcl_ParseCommand,     Tcl_ParseExpr,      Tcl_ParseBraces,
       Tcl_ParseQuotedString,  and  Tcl_ParseVarName return parse
       information  in  two  data   structures,   Tcl_Parse   and
       Tcl_Token:
              typedef struct Tcl_Parse {
                char *commentStart;
                int commentSize;
                char *commandStart;
                int commandSize;
                int numWords;
                Tcl_Token *tokenPtr;
                int numTokens;
                ...
              } Tcl_Parse;

              typedef struct Tcl_Token {
                  int type;
                  char *start;
                  int size;
                  int numComponents;
              } Tcl_Token;

       The  first five fields of a Tcl_Parse structure are filled
       in only by Tcl_ParseCommand.  These fields are not used by
       the other parsing procedures.

       Tcl_ParseCommand  fills  in  a  Tcl_Parse  structure  with
       the commentStart field points  to  the  #  character  that
       begins  the  first  comment  and commentSize indicates the
       number of bytes in all of the comments preceding the  com­
       mand,  including the newline character that terminates the
       last comment.  If the command is not preceded by any  com­
       ments,  commentSize  is 0.  Tcl_ParseCommand also sets the
       commandStart field to point to the first character of  the
       first word in the command (skipping any comments and lead­
       ing space) and commandSize gives the total number of bytes
       in the command, including the character pointed to by com­
       mandStart up to and including the newline, close  bracket,
       or  semicolon  character that terminates the command.  The
       numWords field gives the total number of words in the com­
       mand.

       All  parsing procedures set the remaining fields, tokenPtr
       and numTokens.  The tokenPtr field points to the first  in
       an  array of Tcl_Token structures that describe the compo­
       nents of the entity being  parsed.   The  numTokens  field
       gives  the  total  number  of tokens present in the array.
       Each token contains four fields.  The type  field  selects
       one  of several token types that are described below.  The
       start field points to the first character in the token and
       the size field gives the total number of characters in the
       token.  Some  token  types,  such  as  TCL_TOKEN_WORD  and
       TCL_TOKEN_VARIABLE,  consist  of several component tokens,
       which immediately follow the parent token;  the  numCompo­
       nents  field  describes  how many of these there are.  The
       type field has one of the following values:

       TCL_TOKEN_WORD      This token  ordinarily  describes  one
                           word  of  a  command  but  it may also
                           describe a quoted or braced string  in
                           an  expression.  The token describes a
                           component of the script  that  is  the
                           result  of  concatenating  together  a
                           sequence   of   subcomponents,    each
                           described by a separate subtoken.  The
                           token starts with the first  non-blank
                           character  of the component (which may
                           be a double-quote or open  brace)  and
                           includes  all characters in the compo­
                           nent  up  to  but  not  including  the
                           space, semicolon, close bracket, close
                           quote, or close brace that  terminates
                           the   component.    The  numComponents
                           field counts the total number of  sub-
                           tokens  that make up the word, includ­
                           ing sub-tokens  of  TCL_TOKEN_VARIABLE
                           and TCL_TOKEN_BS tokens.

       TCL_TOKEN_SIMPLE_WORD
                           is  guaranteed  to consist of a single
                           TCL_TOKEN_TEXT sub-token.  The numCom­
                           ponents field is always 1.

       TCL_TOKEN_TEXT      The token describes a range of literal
                           text that is part of a word.  The num­
                           Components field is always 0.

       TCL_TOKEN_BS        The   token   describes   a  backslash
                           sequence such as  \n  or  \0xa3.   The
                           numComponents field is always 0.

       TCL_TOKEN_COMMAND   The  token  describes  a command whose
                           result result must be substituted into
                           the  word.   The  token  includes  the
                           square brackets that surround the com­
                           mand.    The  numComponents  field  is
                           always 0 (the nested  command  is  not
                           parsed;  call  Tcl_ParseCommand recur­
                           sively if you want to see its tokens).

       TCL_TOKEN_VARIABLE  The token describes a variable substi­
                           tution,  including  the  $,   variable
                           name,  and  array  index  (if there is
                           one) up through the close  parenthesis
                           that terminates the index.  This token
                           is followed by one or more  additional
                           tokens that describe the variable name
                           and array index.  If numComponents  is
                           1  then  the  variable is a scalar and
                           the next  token  is  a  TCL_TOKEN_TEXT
                           token  that  gives  the variable name.
                           If numComponents  is  greater  than  1
                           then  the  variable  is  an array: the
                           first sub-token  is  a  TCL_TOKEN_TEXT
                           token  giving  the  array name and the
                           remaining        sub-tokens        are
                           TCL_TOKEN_TEXT,          TCL_TOKEN_BS,
                           TCL_TOKEN_COMMAND, and TCL_TOKEN_VARI­
                           ABLE  tokens that must be concatenated
                           to produce the array index.  The  num­
                           Components  field includes nested sub-
                           tokens    that     are     part     of
                           TCL_TOKEN_VARIABLE tokens in the array
                           index.

       TCL_TOKEN_SUB_EXPR  The token describes one  subexpression
                           of an expression (or an entire expres­
                           sion).  A subexpression may consist of
                           a  value  such  as an integer literal,
                           variable  substitution,  or  parenthe­
                           sized  subexpression; it may also con­
                           blank character of  the  subexpression
                           up  to  but  not  including the space,
                           brace, close-paren,  or  bracket  that
                           terminates  the  subexpression.   This
                           token is followed by one or more addi­
                           tional tokens that describe the subex­
                           pression.   If  the  first   sub-token
                           after  the TCL_TOKEN_SUB_EXPR token is
                           a TCL_TOKEN_OPERATOR token, the subex­
                           pression  consists  of an operator and
                           its token operands.  If  the  operator
                           has  no  operands,  the  subexpression
                           consists of just the  TCL_TOKEN_OPERA­
                           TOR  token.  Each operand is described
                           by a TCL_TOKEN_SUB_EXPR token.  Other­
                           wise,  the  subexpression  is  a value
                           described by one of  the  token  types
                           TCL_TOKEN_WORD,        TCL_TOKEN_TEXT,
                           TCL_TOKEN_BS,       TCL_TOKEN_COMMAND,
                           TCL_TOKEN_VARIABLE,                and
                           TCL_TOKEN_SUB_EXPR.  The numComponents
                           field  counts the total number of sub-
                           tokens that make up the subexpression;
                           this  includes  the sub-tokens for any
                           nested TCL_TOKEN_SUB_EXPR tokens.

       TCL_TOKEN_OPERATOR  The token describes one operator of an
                           expression  such  as  && or hypot.  An
                           TCL_TOKEN_OPERATOR  token  is   always
                           preceeded   by   a  TCL_TOKEN_SUB_EXPR
                           token that describes the operator  and
                           its  operands;  the TCL_TOKEN_SUB_EXPR
                           token's  numComponents  field  can  be
                           used   to   determine  the  number  of
                           operands.  A binary operator such as *
                           is  followed by two TCL_TOKEN_SUB_EXPR
                           tokens that describe its operands.   A
                           unary operator like - is followed by a
                           single  TCL_TOKEN_SUB_EXPR  token  for
                           its  operand.   If  the  operator is a
                           math  function  such  as  log10,   the
                           TCL_TOKEN_OPERATOR token will give its
                           name      and      the       following
                           TCL_TOKEN_SUB_EXPR     tokens     will
                           describe its operands; if there are no
                           operands    (as    with    rand),   no
                           TCL_TOKEN_SUB_EXPR   tokens    follow.
                           There is one trinary operator, ?, that
                           appears in if-then-else subexpressions
                           such  as  x?y:z;  in  this case, the ?
                           TCL_TOKEN_OPERATOR token  is  followed
                           by three TCL_TOKEN_SUB_EXPR tokens for
                           TCL_TOKEN_OPERATOR token is always  0.

       After Tcl_ParseCommand returns, the first token pointed to
       by the tokenPtr field of the  Tcl_Parse  structure  always
       has  type  TCL_TOKEN_WORD or TCL_TOKEN_SIMPLE_WORD.  It is
       followed by the sub-tokens that must  be  concatenated  to
       produce  the  value  of  that word.  The next token is the
       TCL_TOKEN_WORD or TCL_TOKEN_SIMPLE_WORD token for the sec­
       ond  word, followed by sub-tokens for that word, and so on
       until all numWords have been accounted for.

       After Tcl_ParseExpr returns, the first token pointed to by
       the  tokenPtr  field of the Tcl_Parse structure always has
       type TCL_TOKEN_SUB_EXPR.  It is followed by the sub-tokens
       that must be evaluated to produce the value of the expres­
       sion.  Only the token information in the Tcl_Parse  struc­
       ture  is modified: the commentStart, commentSize, command­
       Start,  and  commandSize  fields  are  not   modified   by
       Tcl_ParseExpr.

       After Tcl_ParseBraces returns, the array of tokens pointed
       to by the tokenPtr field of the Tcl_Parse  structure  will
       contain a single TCL_TOKEN_TEXT token if the braced string
       does not contain any backslash-newlines.   If  the  string
       does  contain backslash-newlines, the array of tokens will
       contain one or more TCL_TOKEN_TEXT  or  TCL_TOKEN_BS  sub-
       tokens  that  must be concatenated to produce the value of
       the string.  If the braced string was just  {}  (that  is,
       the  string  was  empty),  the single TCL_TOKEN_TEXT token
       will have a size field containing zero; this ensures  that
       at  least one token appears to describe the braced string.
       Only the token information in the Tcl_Parse  structure  is
       modified: the commentStart, commentSize, commandStart, and
       commandSize fields are not modified by Tcl_ParseBraces.

       After Tcl_ParseQuotedString returns, the array  of  tokens
       pointed  to  by the tokenPtr field of the Tcl_Parse struc­
       ture depends on the contents of  the  quoted  string.   It
       will  consist of one or more TCL_TOKEN_TEXT, TCL_TOKEN_BS,
       TCL_TOKEN_COMMAND, and TCL_TOKEN_VARIABLE sub-tokens.  The
       array  always contains at least one token; for example, if
       the argument string is empty, the array returned  consists
       of  a  single TCL_TOKEN_TEXT token with a zero size field.
       Only the token information in the Tcl_Parse  structure  is
       modified: the commentStart, commentSize, commandStart, and
       commandSize fields are not modified.

       After Tcl_ParseVarName returns, the first token pointed to
       by  the  tokenPtr  field of the Tcl_Parse structure always
       has type TCL_TOKEN_VARIABLE.  It is followed by  the  sub-
       tokens  that make up the variable name as described above.
       The total length of the variable name is contained in  the
       fied  by  Tcl_ParseVarName: the commentStart, commentSize,
       commandStart, and commandSize fields are not modified.

       All  of  the  character  pointers  in  the  Tcl_Parse  and
       Tcl_Token  structures  refer  to  characters in the string
       argument  passed   to   Tcl_ParseCommand,   Tcl_ParseExpr,
       Tcl_ParseBraces,  Tcl_ParseQuotedString, and Tcl_ParseVar­
       Name.

       There are additional fields  in  the  Tcl_Parse  structure
       after  the  numTokens field, but these are for the private
       use of Tcl_ParseCommand,  Tcl_ParseExpr,  Tcl_ParseBraces,
       Tcl_ParseQuotedString,  and  Tcl_ParseVarName; they should
       not be referenced by code outside of these procedures.



KEYWORDS

       backslash  substitution,  braces,   command,   expression,
       parse, token, variable substitution