Provided by: tcl8.6-doc_8.6.14+dfsg-1build1_all bug

NAME

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

SYNOPSIS

       #include <tcl.h>

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

       int
       Tcl_ParseExpr(interp, start, numBytes, parsePtr)

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

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

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

       const char *
       Tcl_ParseVar(interp, start, termPtr)

       Tcl_FreeParse(usedParsePtr)

       Tcl_Obj *
       Tcl_EvalTokens(interp, tokenPtr, numTokens)

       int
       Tcl_EvalTokensStandard(interp, tokenPtr, numTokens)

ARGUMENTS

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

       const char *start (in)                 Pointer to first character in string to parse.

       int numBytes (in)                      Number  of  bytes in string to parse, not including
                                              any terminating null character.   If  less  than  0
                                              then   the   script   consists  of  all  characters
                                              following start up to the first null character.

       int nested (in)                        Non-zero means that the script is part of a command
                                              substitution so an unquoted close bracket should be
                                              treated as a command 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 uninitialized; any information in it is ignored.
                                              This argument is normally 0.

       Tcl_Parse *parsePtr (out)              Points  to  structure  to  fill in with information
                                              about  the  parsed  command,  expression,  variable
                                              name,   etc.   Any  previous  information  in  this
                                              structure is ignored, unless append is non-zero  in
                                              a  call  to Tcl_ParseBraces, Tcl_ParseQuotedString,
                                              or Tcl_ParseVarName.

       const char **termPtr (out)             If  not  NULL,   points   to   a   location   where
                                              Tcl_ParseBraces,     Tcl_ParseQuotedString,     and
                                              Tcl_ParseVar will store a pointer to the  character
                                              just  after  the  terminating character (the close-
                                              brace, the last character of the variable name,  or
                                              the  close-quote  (respectively))  if the parse was
                                              successful.

       Tcl_Parse *usedParsePtr (in)           Points  to  structure  that  was  filled  in  by  a
                                              previous  call  to Tcl_ParseCommand, Tcl_ParseExpr,
                                              Tcl_ParseVarName, 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 structure 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  a  script  containing  an
       expression,   Tcl_ParseExpr   parses   the  expression.   If  the  expression  was  parsed
       successfully, 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 start.  The first character of
       start  must  be  {.  If the braced string was parsed successfully, Tcl_ParseBraces returns
       TCL_OK, fills in the structure 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 terminating } in the location given by *termPtr.  If an error occurs 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  argument  start.  The first character of start must be ".  If the
       double-quoted string was parsed successfully, Tcl_ParseQuotedString returns TCL_OK,  fills
       in the structure 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  terminating
       "  in  the  location  given by *termPtr.  If an error occurs 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 start argument.  The first character of start must be $.   If  a
       variable  name  was  parsed successfully, Tcl_ParseVarName 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 occurs while parsing the command then TCL_ERROR is
       returned, an error message is left in interp's result (if interp  is  not  NULL),  and  no
       information is left at *parsePtr.

       Tcl_ParseVar  parses a Tcl variable reference such as $abc or $x([expr {$index + 1}]) from
       the beginning of its start argument.  The first character of start  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.

       The  information  left  at  *parsePtr by Tcl_ParseCommand, 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  information  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_EvalTokensStandard 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_EvalTokensStandard  performs  the
       substitutions  requested  by the tokens and concatenates the resulting values.  The return
       value from Tcl_EvalTokensStandard is a Tcl completion code with one of the values  TCL_OK,
       TCL_ERROR,  TCL_RETURN,  TCL_BREAK,  or TCL_CONTINUE, or possibly some other integer value
       originating in an extension.  In addition, a result value or  error  message  is  left  in
       interp's result; it can be retrieved using Tcl_GetObjResult.

       Tcl_EvalTokens  differs from Tcl_EvalTokensStandard only in the return convention used: it
       returns the result in a new Tcl_Obj.  The reference count of the value returned as  result
       has  been incremented, so the caller must invoke Tcl_DecrRefCount when it is finished with
       the value.  If an error or other exception 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. The use of Tcl_EvalTokens is deprecated.

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 {
                  const char *commentStart;
                  int commentSize;
                  const char *commandStart;
                  int commandSize;
                  int numWords;
                  Tcl_Token *tokenPtr;
                  int numTokens;
                  ...
              } Tcl_Parse;

              typedef struct Tcl_Token {
                  int type;
                  const 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 information that  describes  one  Tcl
       command  and  any  comments  that  precede  the  command.   If  there  are  comments,  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 command, including the
       newline character that terminates the last comment.  If the command is not preceded by any
       comments, 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  leading
       space)  and  commandSize  gives  the  total  number of bytes in the command, including the
       character pointed to by commandStart 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 command.

       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 components
       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 numComponents 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 component 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, including sub-tokens of
                           TCL_TOKEN_VARIABLE and TCL_TOKEN_BS tokens.

       TCL_TOKEN_SIMPLE_WORD
                           This token has the same meaning as  TCL_TOKEN_WORD,  except  that  the
                           word  is  guaranteed  to consist of a single TCL_TOKEN_TEXT sub-token.
                           The numComponents field is always 1.

       TCL_TOKEN_EXPAND_WORD
                           This token has the same meaning as  TCL_TOKEN_WORD,  except  that  the
                           command  parser  notes  this word began with the expansion prefix {*},
                           indicating that after substitution, the list value of this word should
                           be  expanded  to  form multiple arguments in command evaluation.  This
                           token type can only be created by Tcl_ParseCommand.

       TCL_TOKEN_TEXT      The token describes a range of literal text that is part  of  a  word.
                           The numComponents 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 must  be  substituted  into
                           the  word.   The  token includes the square brackets that surround the
                           command.  The numComponents field is always 0 (the nested  command  is
                           not  parsed;  call Tcl_ParseCommand recursively if you want to see its
                           tokens).

       TCL_TOKEN_VARIABLE  The token describes a variable substitution, 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_VARIABLE   tokens  that  must  be
                           concatenated to produce  the  array  index.  The  numComponents  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
                           expression).   A  subexpression  may  consist  of  a  value such as an
                           integer   literal,    variable    substitution,    or    parenthesized
                           subexpression;  it  may  also consist of an operator and its operands.
                           The  token  starts  with  the  first  non-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 additional tokens that describe the subexpression.  If
                           the  first  sub-token  after  the  TCL_TOKEN_SUB_EXPR   token   is   a
                           TCL_TOKEN_OPERATOR  token,  the  subexpression consists of an operator
                           and its  token  operands.   If  the  operator  has  no  operands,  the
                           subexpression  consists  of  just  the TCL_TOKEN_OPERATOR token.  Each
                           operand is described by a TCL_TOKEN_SUB_EXPR  token.   Otherwise,  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.
                           A TCL_TOKEN_OPERATOR token is always preceded 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  the  operands x, y, and z.  The numComponents field for a
                           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  or
       TCL_TOKEN_EXPAND_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 of TCL_TOKEN_EXPAND_WORD token for the second 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 expression.  Only the token information
       in the Tcl_Parse structure is modified: the commentStart, commentSize,  commandStart,  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 structure 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
       start 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 size field of the first token.  As in Tcl_ParseExpr, only the token
       information in the Tcl_Parse structure is modified 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   start   argument   passed   to   Tcl_ParseCommand,   Tcl_ParseExpr,
       Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_ParseVarName.

       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