DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_FreeParse(3tcl)




Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

_________________________________________________________________


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  mes-
                                            sages  are left after
                                            errors.           For
                                            Tcl_EvalTokens    and
                                            Tcl_EvalTokensStandard,
                                            determines  the  con-
                                            text  for  evaluating
                                            the  script  and also

Tcl                     Last change: 8.3                        1

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

                                            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   ter-
                                            minating null charac-
                                            ter.  If less than  0
                                            then  the script con-
                                            sists of all  charac-
                                            ters  following start
                                            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 com-
                                            mand terminator.   If
                                            zero,  close brackets
                                            have no special mean-
                                            ing.

     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 *par-
                                            sePtr  is  uninitial-
                                            ized; 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,  variable
                                            name,  etc.  Any pre-
                                            vious information  in
                                            this   structure   is

Tcl                     Last change: 8.3                        2

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

                                            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  (respec-
                                            tively)) 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  com-
     mands  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

Tcl                     Last change: 8.3                        3

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

     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 informa-
     tion 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 success-
     fully, Tcl_ParseBraces 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  occurs  while
     parsing the string then TCL_ERROR is returned, an error mes-
     sage 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 par-
     sePtr  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 parse 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

Tcl                     Last change: 8.3                        4

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

     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  object  returned  as
     result  has  been  incremented,  so  the  caller must invoke
     Tcl_DecrRefCount when it is finished with the object.  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                     Last change: 8.3                        5

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

          } 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  infor-
     mation  that describes one Tcl command and any comments that
     precede the  command.   If  there  are  comments,  the  com-
     mentStart  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 ter-
     minates 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  expres-
                         sion.   The  token describes a component
                         of the script that is the result of con-
                         catenating  together  a sequence of sub-
                         components, each described by a separate

Tcl                     Last change: 8.3                        6

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

                         subtoken.   The  token  starts  with the
                         first non-blank character  of  the  com-
                         ponent  (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 ter-
                         minates  the  component.   The   numCom-
                         ponents 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 numCom-
                         ponents 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  evalua-  |
                         tion.   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 substitu-
                         tion,  including  the  $, variable name,
                         and array index (if  there  is  one)  up

Tcl                     Last change: 8.3                        7

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

                         through  the close parenthesis that ter-
                         minates the index.  This token  is  fol-
                         lowed  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  subex-
                         pression;  it  may  also  consist  of an
                         operator and its  operands.   The  token
                         starts  with the first non-blank charac-
                         ter of the subexpression up to  but  not
                         including the space, brace, close-paren,
                         or bracket that  terminates  the  subex-
                         pression.  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  con-
                         sists  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

Tcl                     Last change: 8.3                        8

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

                         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  pre-
                         ceded by a TCL_TOKEN_SUB_EXPR token that
                         describes the operator and its operands;
                         the  TCL_TOKEN_SUB_EXPR  token's numCom-
                         ponents field can be used  to  determine
                         the number of operands.  A binary opera-
                         tor  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 expres-
     sion.  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

Tcl                     Last change: 8.3                        9

Tcl_ParseCommand(3)  Tcl Library Procedures   Tcl_ParseCommand(3)

     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 com-
     mentStart, 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  con-
     sist   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  modi-
     fied:  the commentStart, commentSize, commandStart, and com-
     mandSize 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,  com-
     mandStart, 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

Tcl                     Last change: 8.3                       10


Man(1) output converted with man2html