ABCDEFGHIJKLMNOPQRSTUVWXYZ

ParseCmd

Tcl_ParseCommand(3)         Tcl Library Procedures         Tcl_ParseCommand(3)



______________________________________________________________________________

NAME
       Tcl_ParseCommand,   Tcl_ParseExpr,   Tcl_ParseBraces,  Tcl_ParseQuoted-
       String, 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_EvalTo-
                                              kens,   used   only   for  error
                                              reporting;  if  NULL,  then   no
                                              error  messages  are  left after
                                              errors.    For   Tcl_EvalTokens,
                                              determines the context for eval-
                                              uating the script  and  also  is
                                              used  for  error reporting; must
                                              not be NULL.

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

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

       int          nested          (in)      Non-zero means that  the  script
                                              is  part  of a command substitu-
                                              tion  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  previ-
                                              ous  information  in this struc-
                                              ture is ignored,  unless  append
                                              is   non-zero   in   a  call  to
                                              Tcl_ParseBraces,  Tcl_ParseQuot-
                                              edString, or Tcl_ParseVarName.

       char         **termPtr       (out)     If  not  NULL, points to a loca-
                                              tion   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 char-
                                              acter 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 con-
       taining an expression, Tcl_ParseCommand 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 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  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 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  argument  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 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_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_ParseVarName  returns TCL_OK and fills in the struc-
       ture pointed to by parsePtr with information about the structure of the
       variable name (see below for details).  If an error occurrs while pars-
       ing 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 success-
       fully,  Tcl_ParseVar returns a pointer to the string value of the vari-
       able.  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_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 vari-
       able.   Tcl_EvalTokens  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_ParseQuoted-
       String, 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  pro-
       cedures.

       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 new-
       line 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 com-
       mandSize 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 numTo-
       kens.  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  com-
                           mand  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 con-
                           catenating 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  termi-
                           nates   the  component.   The  numComponents  field
                           counts the total number of sub-tokens that make  up
                           the  word,  including sub-tokens of TCL_TOKEN_VARI-
                           ABLE 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_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  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
                           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 expres-
                           sion (or an entire  expression).   A  subexpression
                           may  consist of a value such as an integer literal,
                           variable substitution, or parenthesized  subexpres-
                           sion;  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 con-
                           sists 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.  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 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.   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 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  back-
       slash-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 contain-
       ing 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  command-
       Size 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 argu-
       ment  string  is  empty,  the  array  returned  consists  of  a  single
       TCL_TOKEN_TEXT  token  with a zero size field.  Only the token informa-
       tion in the Tcl_Parse structure is modified: the commentStart, comment-
       Size, 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, command-
       Start, 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_ParseVarName.

       There are additional fields in the Tcl_Parse structure after the numTo-
       kens field, but these are for  the  private  use  of  Tcl_ParseCommand,
       Tcl_ParseExpr,  Tcl_ParseBraces,  Tcl_ParseQuotedString, and Tcl_Parse-
       VarName; they should not be referenced by code outside of these  proce-
       dures.


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



Tcl                                   8.3                  Tcl_ParseCommand(3)