ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

This manual page is associated with the Mac OS X developer tools. The software or headers described may not be present on your Mac OS X installation until you install the developer tools package. This package is available on your Mac OS X installation DVD, and the latest versions can be downloaded from developer.apple.com.

For more information about the manual page format, see the manual page for manpages(5).



Tcl_ParseCommand(3)                        Tcl Library Procedures                        Tcl_ParseCommand(3)



____________________________________________________________________________________________________________

NAME
       Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_Parse-Var, Tcl_ParseVar,
       Var, 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_EvalTokensStandard, determines the con-text context
                                              text 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
                                              characters in string up to the first null character.

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

       int          append          (in)      Non-zero means that *parsePtr already contains  valid  tokens;
                                              the  new  tokens  should be appended to those already present.
                                              Zero means that *parsePtr is 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 struc-ture structure
       ture 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_Par-seCommand Tcl_ParseCommand
       seCommand  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  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 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  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 isn't NULL), and no information is left at *parsePtr.

       Tcl_ParseVar  parse a Tcl variable reference such as $abc or $x([expr $index + 1]) from the beginning
       of its string argument.  The first character of string must be $.  If the  variable  name  is  parsed
       successfully, Tcl_ParseVar returns a pointer to the string value of the variable.  If an error occurs
       while parsing, then NULL is returned and an error message is left in interp's result.

       The information left at *parsePtr by Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuot-edString, Tcl_ParseQuotedString,
       edString,  and Tcl_ParseVarName may include dynamically allocated memory.  If these five parsing pro-cedures procedures
       cedures 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  refer-ence reference
       ence 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 comple-tion completion
       tion code with one of the values TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE, or possi-bly possibly
       bly some other integer value originating in an extension.  In addition, a result value or error  mes-sage message
       sage 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_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  com-mandStart commandStart
       mandStart  field  to point to the first character of the first word in the command (skipping any com-ments comments
       ments 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 con-tains contains
       tains 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, semi-colon, semicolon,
                           colon, 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  guar-anteed guaranteed
                           anteed  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  numCom-ponents numComponents
                           ponents 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 command.  The
                           numComponents field is always 0 (the nested command is not parsed; call  Tcl_Par-seCommand Tcl_ParseCommand
                           seCommand 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 subtoken
                           token  is  a  TCL_TOKEN_TEXT  token  giving the array name and the remaining sub-tokens subtokens
                           tokens are TCL_TOKEN_TEXT, TCL_TOKEN_BS, TCL_TOKEN_COMMAND,  and  TCL_TOKEN_VARI-ABLE TCL_TOKEN_VARIABLE
                           ABLE  tokens  that must be concatenated to produce the array index. The numCompo-nents numComponents
                           nents 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  sub-stitution, substitution,
                           stitution, or parenthesized subexpression; it may also consist of an operator and
                           its operands.  The token starts with the first non-blank character of the  subex-pression subexpression
                           pression  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 consists
                           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 numCompo-nents numComponents
                           nents 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. operands.
                           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_OPER-ATOR TCL_TOKEN_OPERATOR
                           ATOR 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 struc-ture structure
       ture 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 modi-fied: modified:
       fied: 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. backslash-newlines.
       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 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 mod-ified: modified:
       ified: 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 string is empty, the  array  returned  con-sists consists
       sists  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
       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 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                                                  8.3                                 Tcl_ParseCommand(3)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.