DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

Tcl_ParseCommand(3tcl)




______________________________________________________________________________


NAME

       Tcl_ParseCommand,   Tcl_ParseExpr,   Tcl_ParseBraces,  Tcl_ParseQuoted-
       String, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse,  Tcl_EvalTokens,
       Tcl_EvalTokensStandard - 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)

       CONST char *
       Tcl_ParseVar(interp, string, 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_EvalTo-
                                              kensStandard,   determines   the
                                              context   for   evaluating   the
                                              script  and  also  is  used  for
                                              error  reporting;  must  not  be
                                              NULL.

       CONST 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.

       CONST 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 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  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 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 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 occurs 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_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_CON-
       TINUE,  or  possibly  some other integer value originating in an exten-
       sion.  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_ParseQuoted-
       String,  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 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 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 oper-
                           ands.  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_Parse-
       VarName.

       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)

Man(1) output converted with man2html