NAME
TclParseCommand, TclParseExpr, TclParseBraces, TclParseQuoted-
String, TclParseVarName, TclParseVar, TclFreeParse, TclEvalTokens,TclEvalTokensStandard - parse Tcl scripts and expressions
SYNOPSIS
##iinncclluuddee <
int TTccllPPaarrsseeCCoommmmaanndd(interp, string, numBytes, nested, parsePtr) int TTccllPPaarrsseeEExxpprr(interp, string, numBytes, parsePtr) int TTccllPPaarrsseeBBrraacceess(interp, string, numBytes, parsePtr, append, termPtr) int TTccllPPaarrsseeQQuuootteeddSSttrriinngg(interp, string, numBytes, parsePtr, append, termPtr) int TTccllPPaarrsseeVVaarrNNaammee(interp, string, numBytes, parsePtr, append) CONST char * TTccllPPaarrsseeVVaarr(interp, string, termPtr) TTccllFFrreeeePPaarrssee(usedParsePtr) TclObj * TTccllEEvvaallTTookkeennss(interp, tokenPtr, numTokens) int TTccllEEvvaallTTookkeennssSSttaannddaarrdd(interp, tokenPtr, numTokens) AARRGGUUMMEENNTTSS TclInterp *interp (out) For procedures other than TTccllFFrreeeePPaarrssee, TTccllEEvvaallTTookkeennss and TTccllEEvvaallTTookkeennssSSttaannddaarrdd, used only for error reporting; if NULL, then no error messages are left after errors. For> TTccllEEvvaallTTookkeennss and TTccllEEvvaallTToo-
kkeennssSSttaannddaarrdd, 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 thenthe 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. TclParse *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 appendis non-zero in a call to
TTccllPPaarrsseeBBrraacceess, TTccllPPaarrsseeQQuuoott-
eeddSSttrriinngg, or TTccllPPaarrsseeVVaarrNNaammee.CONST char **termPtr (out) If not NULL, points to a loca-
tion where TTccllPPaarrsseeBBrraacceess, TTccllPPaarrsseeQQuuootteeddSSttrriinngg, and TTccllPPaarrsseeVVaarr will store a pointer to the character just after the terminating character(the close-brace, the last char-
acter of the variable name, orthe close-quote (respectively))
if the parse was successful. TclParse *usedParsePtr (in) Points to structure that was filled in by a previous call to TTccllPPaarrsseeCCoommmmaanndd, TTccllPPaarrsseeEExxpprr, TTccllPPaarrsseeVVaarrNNaammee, 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 TTCCLLOOKK. However, if an error occurs then they return TTCCLLEERRRROORR, leave an error message in interp's result (if interp is not NULL), and leave nothing in parsePtr. TTccllPPaarrsseeCCoommmmaanndd 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, TTccllPPaarrsseeCCoommmmaanndd returns TTCCLLOOKK 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 TTCCLLEERRRROORR is returned, an error message is left in interp's result, and no information is left at *parsePtr.TTccllPPaarrsseeEExxpprr parses Tcl expressions. Given a pointer to a script con-
taining an expression, TTccllPPaarrsseeCCoommmmaanndd parses the expression. If the expression was parsed successfully, TTccllPPaarrsseeEExxpprr returns TTCCLLOOKK 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 TTCCLLEERRRROORR is returned, an error message is left in interp's result, and no information is left at *parsePtr. TTccllPPaarrsseeBBrraacceess parses a string or command argument enclosed in braces such as {{hheelllloo}} or {{ssttrriinngg \\tt wwiitthh \\tt ttaabbss}} from the beginning of its argument string. The first character of string must be {{. If the braced string was parsed successfully, TTccllPPaarrsseeBBrraacceess returns TTCCLLOOKK, 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 TTCCLLEERRRROORR is returned, an error message is left in interp's result, and no information is left at *parsePtr or *termPtr.TTccllPPaarrsseeQQuuootteeddSSttrriinngg parses a double-quoted string such as ""ssuumm iiss
[[eexxpprr $$aa++$$bb]]"" from the beginning of the argument string. The first
character of string must be "". If the double-quoted string was parsed
successfully, TTccllPPaarrsseeQQuuootteeddSSttrriinngg returns TTCCLLOOKK, 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 TTCCLLEERRRROORR is returned, an error message is left in interp's result, and no information is left at *parsePtr or *termPtr.TTccllPPaarrsseeVVaarrNNaammee parses a Tcl variable reference such as $$aabbcc or
$$xx(([[eexxpprr $$iinnddeexx ++ 11]])) from the beginning of its string argument. The
first character of string must be $$. If a variable name was parsed
successfully, TTccllPPaarrsseeVVaarrNNaammee returns TTCCLLOOKK and fills in the struc-
ture pointed to by parsePtr with information about the structure of thevariable name (see below for details). If an error occurs while pars-
ing the command then TTCCLLEERRRROORR is returned, an error message is left in interp's result (if interp isn't NULL), and no information is left at *parsePtr.TTccllPPaarrsseeVVaarr parse a Tcl variable reference such as $$aabbcc or $$xx(([[eexxpprr
$$iinnddeexx ++ 11]])) from the beginning of its string argument. The first
character of string must be $$. If the variable name is parsed success-
fully, TTccllPPaarrsseeVVaarr 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 TTccllPPaarrsseeCCoommmmaanndd, TTccllPPaarrsseeEExxpprr, TTccllPPaarrsseeBBrraacceess, TTccllPPaarrsseeQQuuootteeddSSttrriinngg, and TTccllPPaarrsseeVVaarrNNaammee may include dynamically allocated memory. If these five parsing procedures return TTCCLLOOKK then the caller must invoke TTccllFFrreeeePPaarrssee to release the storage at *parsePtr. These procedures ignore any existing informationin *parsePtr (unless append is non-zero), so if repeated calls are
being made to any of them then TTccllFFrreeeePPaarrssee must be invoked once after each call. TTccllEEvvaallTTookkeennssSSttaannddaarrdd evaluates a sequence of parse tokens from a TclParse 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. TTccllEEvvaallTTookkeennssSSttaannddaarrdd performs the substitutions requested by the tokens and concatenates the resulting values. The return value from TTccllEEvvaallTTookkeennssSSttaannddaarrdd is a Tcl completion code withone of the values TTCCLLOOKK, TTCCLLEERRRROORR, TTCCLLRREETTUURRNN, TTCCLLBBRREEAAKK, or TTCCLLCCOONN-
TTIINNUUEE, 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 TTccllGGeettOObbjjRReessuulltt. TTccllEEvvaallTTookkeennss differs from TTccllEEvvaallTTookkeennssSSttaannddaarrdd only in the return convention used: it returns the result in a new TclObj. The reference count of the object returned as result has been incremented, so the caller must invoke TTccllDDeeccrrRReeffCCoouunntt when it is finished with the object. If an error or other exception occurs while evaluating thetokens (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 TTccllEEvvaallTTookkeennss is deprecated. TTCCLLPPAARRSSEE SSTTRRUUCCTTUURREETTccllPPaarrsseeCCoommmmaanndd, TTccllPPaarrsseeEExxpprr, TTccllPPaarrsseeBBrraacceess, TTccllPPaarrsseeQQuuootteedd-
SSttrriinngg, and TTccllPPaarrsseeVVaarrNNaammee return parse information in two data structures, TclParse and TclToken: typedef struct TclParse { CONST char *commentStart; int commentSize; CONST char *commandStart; int commandSize; int numWords; TclToken *tokenPtr; int numTokens; ... } TclParse; typedef struct TclToken { int type; CONST char *start; int size; int numComponents; } TclToken; The first five fields of a TclParse structure are filled in only byTTccllPPaarrsseeCCoommmmaanndd. These fields are not used by the other parsing pro-
cedures. TTccllPPaarrsseeCCoommmmaanndd fills in a TclParse 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 ofbytes 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. TTccllPPaarrsseeCCoommmmaanndd also sets the commandStart field to point to the first character of the firstword 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 TclToken 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 TTCCLLTTOOKKEENNWWOORRDD and TTCCLLTTOOKKEENNVVAARRIIAABBLLEE, 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:TTCCLLTTOOKKEENNWWOORRDD 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 acomponent of the script that is the result of con-
catenating together a sequence of subcomponents, each described by a separate subtoken. The tokenstarts 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, closebracket, close quote, or close brace that termi-
nates the component. The numComponents fieldcounts the total number of sub-tokens that make up
the word, including sub-tokens of TTCCLLTTOOKKEENNVVAARRII-
AABBLLEE and TTCCLLTTOOKKEENNBBSS tokens. TTCCLLTTOOKKEENNSSIIMMPPLLEEWWOORRDD This token has the same meaning as TTCCLLTTOOKKEENNWWOORRDD, except that the word is guaranteed to consist of asingle TTCCLLTTOOKKEENNTTEEXXTT sub-token. The numComponents
field is always 1. TTCCLLTTOOKKEENNTTEEXXTT The token describes a range of literal text that is part of a word. The numComponents field is always 0. TTCCLLTTOOKKEENNBBSS The token describes a backslash sequence such as \\nn or \\00xxaa33. The numComponents field is always 0. TTCCLLTTOOKKEENNCCOOMMMMAANNDD The token describes a command whose result result must be substituted into the word. The tokenincludes the square brackets that surround the com-
mand. The numComponents field is always 0 (the nested command is not parsed; call TTccllPPaarrsseeCCoommmmaanndd recursively if you want to see its tokens). TTCCLLTTOOKKEENNVVAARRIIAABBLLEE 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 TTCCLLTTOOKKEENNTTEEXXTT token that gives the variable name. If numComponents is greater than 1then the variable is an array: the first sub-token
is a TTCCLLTTOOKKEENNTTEEXXTT token giving the array name andthe remaining sub-tokens are TTCCLLTTOOKKEENNTTEEXXTT,
TTCCLLTTOOKKEENNBBSS, TTCCLLTTOOKKEENNCCOOMMMMAANNDD, and TTCCLLTTOOKKEENNVVAARRIIAABBLLEE tokens that must be concatenated to produce the array index. The numComponents fieldincludes nested sub-tokens that are part of
TTCCLLTTOOKKEENNVVAARRIIAABBLLEE tokens in the array index.TTCCLLTTOOKKEENNSSUUBBEEXXPPRR 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 itsoperands. The token starts with the first non-
blank character of the subexpression up to but notincluding the space, brace, close-paren, or bracket
that terminates the subexpression. This token is followed by one or more additional tokens thatdescribe the subexpression. If the first sub-token
after the TTCCLLTTOOKKEENNSSUUBBEEXXPPRR token is aTTCCLLTTOOKKEENNOOPPEERRAATTOORR token, the subexpression con-
sists of an operator and its token operands. If the operator has no operands, the subexpression consists of just the TTCCLLTTOOKKEENNOOPPEERRAATTOORR token. Each operand is described by a TTCCLLTTOOKKEENNSSUUBBEEXXPPRR token. Otherwise, the subexpression is a value described by one of the token types TTCCLLTTOOKKEENNWWOORRDD, TTCCLLTTOOKKEENNTTEEXXTT, TTCCLLTTOOKKEENNBBSS, TTCCLLTTOOKKEENNCCOOMMMMAANNDD, TTCCLLTTOOKKEENNVVAARRIIAABBLLEE, and TTCCLLTTOOKKEENNSSUUBBEEXXPPRR. ThenumComponents field counts the total number of sub-
tokens that make up the subexpression; thisincludes the sub-tokens for any nested
TTCCLLTTOOKKEENNSSUUBBEEXXPPRR tokens. TTCCLLTTOOKKEENNOOPPEERRAATTOORR The token describes one operator of an expression such as &&&& or hhyyppoott. An TTCCLLTTOOKKEENNOOPPEERRAATTOORR token is always preceded by a TTCCLLTTOOKKEENNSSUUBBEEXXPPRR token that describes the operator and its operands; the TTCCLLTTOOKKEENNSSUUBBEEXXPPRR token's numComponents field can be used to determine the number of operands. A binary operator such as ** is followed by twoTTCCLLTTOOKKEENNSSUUBBEEXXPPRR tokens that describe its oper-
ands. A unary operator like - is followed by a
single TTCCLLTTOOKKEENNSSUUBBEEXXPPRR token for its operand. If the operator is a math function such as lloogg1100, the TTCCLLTTOOKKEENNOOPPEERRAATTOORR token will give its name and the following TTCCLLTTOOKKEENNSSUUBBEEXXPPRR tokens will describe its operands; if there are no operands (as with rraanndd), no TTCCLLTTOOKKEENNSSUUBBEEXXPPRR tokens follow. There is one trinary operator, ??, that appears inif-then-else subexpressions such as x??y::z; in this
case, the ?? TTCCLLTTOOKKEENNOOPPEERRAATTOORR token is followed by three TTCCLLTTOOKKEENNSSUUBBEEXXPPRR tokens for the operands x, y, and z. The numComponents field for a TTCCLLTTOOKKEENNOOPPEERRAATTOORR token is always 0. After TTccllPPaarrsseeCCoommmmaanndd returns, the first token pointed to by the tokenPtr field of the TclParse structure always has typeTTCCLLTTOOKKEENNWWOORRDD or TTCCLLTTOOKKEENNSSIIMMPPLLEEWWOORRDD. It is followed by the sub-
tokens that must be concatenated to produce the value of that word. The next token is the TTCCLLTTOOKKEENNWWOORRDD or TTCCLLTTOOKKEENNSSIIMMPPLLEEWWOORRDD token forthe second word, followed by sub-tokens for that word, and so on until
all numWords have been accounted for. After TTccllPPaarrsseeEExxpprr returns, the first token pointed to by the tokenPtr field of the TclParse structure always has type TTCCLLTTOOKKEENNSSUUBBEEXXPPRR.It is followed by the sub-tokens that must be evaluated to produce the
value of the expression. Only the token information in the TclParse structure is modified: the commentStart, commentSize, commandStart, and commandSize fields are not modified by TTccllPPaarrsseeEExxpprr. After TTccllPPaarrsseeBBrraacceess returns, the array of tokens pointed to by the tokenPtr field of the TclParse structure will contain a singleTTCCLLTTOOKKEENNTTEEXXTT 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 TTCCLLTTOOKKEENNTTEEXXTT or TTCCLLTTOOKKEENNBBSSsub-tokens that must be concatenated to produce the value of the
string. If the braced string was just {{}} (that is, the string wasempty), the single TTCCLLTTOOKKEENNTTEEXXTT 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 TclParse structureis modified: the commentStart, commentSize, commandStart, and command-
Size fields are not modified by TTccllPPaarrsseeBBrraacceess. After TTccllPPaarrsseeQQuuootteeddSSttrriinngg returns, the array of tokens pointed to by the tokenPtr field of the TclParse structure depends on the contents of the quoted string. It will consist of one or more TTCCLLTTOOKKEENNTTEEXXTT,TTCCLLTTOOKKEENNBBSS, TTCCLLTTOOKKEENNCCOOMMMMAANNDD, and TTCCLLTTOOKKEENNVVAARRIIAABBLLEE 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 singleTTCCLLTTOOKKEENNTTEEXXTT token with a zero size field. Only the token informa-
tion in the TclParse structure is modified: the commentStart, comment-
Size, commandStart, and commandSize fields are not modified. After TTccllPPaarrsseeVVaarrNNaammee returns, the first token pointed to by the tokenPtr field of the TclParse structure always has typeTTCCLLTTOOKKEENNVVAARRIIAABBLLEE. 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 TTccllPPaarrsseeEExxpprr, only the token information in the TclParse structure ismodified by TTccllPPaarrsseeVVaarrNNaammee: the commentStart, commentSize, command-
Start, and commandSize fields are not modified. All of the character pointers in the TclParse and TclToken structures refer to characters in the string argument passed to TTccllPPaarrsseeCCoommmmaanndd,TTccllPPaarrsseeEExxpprr, TTccllPPaarrsseeBBrraacceess, TTccllPPaarrsseeQQuuootteeddSSttrriinngg, and TTccllPPaarrssee-
VVaarrNNaammee.There are additional fields in the TclParse structure after the numTo-
kens field, but these are for the private use of TTccllPPaarrsseeCCoommmmaanndd,TTccllPPaarrsseeEExxpprr, TTccllPPaarrsseeBBrraacceess, TTccllPPaarrsseeQQuuootteeddSSttrriinngg, and TTccllPPaarrssee-
VVaarrNNaammee; they should not be referenced by code outside of these proce-
dures. KKEEYYWWOORRDDSS backslash substitution, braces, command, expression, parse, token, variable substitution Tcl 8.3 TclParseCommand(3)