1Tcl_ParseCommand(3) Tcl Library Procedures Tcl_ParseCommand(3)
2______________________________________________________________________________
6
8 Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuoted‐
9 String, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens,
10 Tcl_EvalTokensStandard - parse Tcl scripts and expressions
11
13 #include <tcl.h>
14 int
16 Tcl_ParseCommand(interp, string, numBytes, nested, parsePtr)
17 int
19 Tcl_ParseExpr(interp, string, numBytes, parsePtr)
20 int
22 Tcl_ParseBraces(interp, string, numBytes, parsePtr, append, termPtr)
23 int
25 Tcl_ParseQuotedString(interp, string, numBytes, parsePtr, append, termPtr)
26 int
28 Tcl_ParseVarName(interp, string, numBytes, parsePtr, append)
29 CONST char *
31 Tcl_ParseVar(interp, string, termPtr)
32 Tcl_FreeParse(usedParsePtr)
34 Tcl_Obj *
36 Tcl_EvalTokens(interp, tokenPtr, numTokens)
37 int
39 Tcl_EvalTokensStandard(interp, tokenPtr, numTokens)
40
42 Tcl_Interp *interp (out) For procedures other than
43 Tcl_FreeParse, Tcl_EvalTokens
44 and Tcl_EvalTokensStandard, used
45 only for error reporting; if
46 NULL, then no error messages are
47 left after errors. For
48 Tcl_EvalTokens and Tcl_EvalTo‐
49 kensStandard, determines the
50 context for evaluating the
51 script and also is used for
52 error reporting; must not be
53 NULL.
54 CONST char *string (in) Pointer to first character in
56 string to parse.
57 int numBytes (in) Number of bytes in string, not
59 including any terminating null
60 character. If less than 0 then
61 the script consists of all char‐
62 acters in string up to the first
63 null character.
64 int nested (in) Non-zero means that the script
66 is part of a command substitu‐
67 tion so an unquoted close
68 bracket should be treated as a
69 command terminator. If zero,
70 close brackets have no special
71 meaning.
72 int append (in) Non-zero means that *parsePtr
74 already contains valid tokens;
75 the new tokens should be
76 appended to those already
77 present. Zero means that
78 *parsePtr is uninitialized; any
79 information in it is ignored.
80 This argument is normally 0.
81 Tcl_Parse *parsePtr (out) Points to structure to fill in
83 with information about the
84 parsed command, expression,
85 variable name, etc. Any previ‐
86 ous information in this struc‐
87 ture is ignored, unless append
88 is non-zero in a call to
89 Tcl_ParseBraces, Tcl_ParseQuot‐
90 edString, or Tcl_ParseVarName.
91 CONST char **termPtr (out) If not NULL, points to a loca‐
93 tion where Tcl_ParseBraces,
94 Tcl_ParseQuotedString, and
95 Tcl_ParseVar will store a
96 pointer to the character just
97 after the terminating character
98 (the close-brace, the last char‐
99 acter of the variable name, or
100 the close-quote (respectively))
101 if the parse was successful.
102 Tcl_Parse *usedParsePtr (in) Points to structure that was
104 filled in by a previous call to
105 Tcl_ParseCommand, Tcl_ParseExpr,
106 Tcl_ParseVarName, etc.
107_________________________________________________________________
108
111 These procedures parse Tcl commands or portions of Tcl commands such as
112 expressions or references to variables. Each procedure takes a pointer
113 to a script (or portion thereof) and fills in the structure pointed to
114 by parsePtr with a collection of tokens describing the information that
115 was parsed. The procedures normally return TCL_OK. However, if an
116 error occurs then they return TCL_ERROR, leave an error message in
117 interp's result (if interp is not NULL), and leave nothing in parsePtr.
118 Tcl_ParseCommand is a procedure that parses Tcl scripts. Given a
120 pointer to a script, it parses the first command from the script. If
121 the command was parsed successfully, Tcl_ParseCommand returns TCL_OK
122 and fills in the structure pointed to by parsePtr with information
123 about the structure of the command (see below for details). If an
124 error occurred in parsing the command then TCL_ERROR is returned, an
125 error message is left in interp's result, and no information is left at
126 *parsePtr.
127 Tcl_ParseExpr parses Tcl expressions. Given a pointer to a script con‐
129 taining an expression, Tcl_ParseExpr parses the expression. If the
130 expression was parsed successfully, Tcl_ParseExpr returns TCL_OK and
131 fills in the structure pointed to by parsePtr with information about
132 the structure of the expression (see below for details). If an error
133 occurred in parsing the command then TCL_ERROR is returned, an error
134 message is left in interp's result, and no information is left at
135 *parsePtr.
136 Tcl_ParseBraces parses a string or command argument enclosed in braces
138 such as {hello} or {string \t with \t tabs} from the beginning of its
139 argument string. The first character of string must be {. If the
140 braced string was parsed successfully, Tcl_ParseBraces returns TCL_OK,
141 fills in the structure pointed to by parsePtr with information about
142 the structure of the string (see below for details), and stores a
143 pointer to the character just after the terminating } in the location
144 given by *termPtr. If an error occurs while parsing the string then
145 TCL_ERROR is returned, an error message is left in interp's result, and
146 no information is left at *parsePtr or *termPtr.
147 Tcl_ParseQuotedString parses a double-quoted string such as "sum is
149 [expr $a+$b]" from the beginning of the argument string. The first
150 character of string must be ". If the double-quoted string was parsed
151 successfully, Tcl_ParseQuotedString returns TCL_OK, fills in the struc‐
152 ture pointed to by parsePtr with information about the structure of the
153 string (see below for details), and stores a pointer to the character
154 just after the terminating " in the location given by *termPtr. If an
155 error occurs while parsing the string then TCL_ERROR is returned, an
156 error message is left in interp's result, and no information is left at
157 *parsePtr or *termPtr.
158 Tcl_ParseVarName parses a Tcl variable reference such as $abc or
160 $x([expr $index + 1]) from the beginning of its string argument. The
161 first character of string must be $. If a variable name was parsed
162 successfully, Tcl_ParseVarName returns TCL_OK and fills in the struc‐
163 ture pointed to by parsePtr with information about the structure of the
164 variable name (see below for details). If an error occurs while pars‐
165 ing the command then TCL_ERROR is returned, an error message is left in
166 interp's result (if interp isn't NULL), and no information is left at
167 *parsePtr.
168 Tcl_ParseVar parse a Tcl variable reference such as $abc or $x([expr
170 $index + 1]) from the beginning of its string argument. The first
171 character of string must be $. If the variable name is parsed success‐
172 fully, Tcl_ParseVar returns a pointer to the string value of the vari‐
173 able. If an error occurs while parsing, then NULL is returned and an
174 error message is left in interp's result.
175 The information left at *parsePtr by Tcl_ParseCommand, Tcl_ParseExpr,
177 Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_ParseVarName may
178 include dynamically allocated memory. If these five parsing procedures
179 return TCL_OK then the caller must invoke Tcl_FreeParse to release the
180 storage at *parsePtr. These procedures ignore any existing information
181 in *parsePtr (unless append is non-zero), so if repeated calls are
182 being made to any of them then Tcl_FreeParse must be invoked once after
183 each call.
184 Tcl_EvalTokensStandard evaluates a sequence of parse tokens from a
186 Tcl_Parse structure. The tokens typically consist of all the tokens in
187 a word or all the tokens that make up the index for a reference to an
188 array variable. Tcl_EvalTokensStandard performs the substitutions
189 requested by the tokens and concatenates the resulting values. The
190 return value from Tcl_EvalTokensStandard is a Tcl completion code with
191 one of the values TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CON‐
192 TINUE, or possibly some other integer value originating in an exten‐
193 sion. In addition, a result value or error message is left in interp's
194 result; it can be retrieved using Tcl_GetObjResult.
195 Tcl_EvalTokens differs from Tcl_EvalTokensStandard only in the return
197 convention used: it returns the result in a new Tcl_Obj. The reference
198 count of the object returned as result has been incremented, so the
199 caller must invoke Tcl_DecrRefCount when it is finished with the
200 object. If an error or other exception occurs while evaluating the
201 tokens (such as a reference to a non-existent variable) then the return
202 value is NULL and an error message is left in interp's result. The use
203 of Tcl_EvalTokens is deprecated.
204
207 Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuoted‐
208 String, and Tcl_ParseVarName return parse information in two data
209 structures, Tcl_Parse and Tcl_Token:
210 typedef struct Tcl_Parse {
211 CONST char *commentStart;
212 int commentSize;
213 CONST char *commandStart;
214 int commandSize;
215 int numWords;
216 Tcl_Token *tokenPtr;
217 int numTokens;
218 ...
219 } Tcl_Parse;
220 typedef struct Tcl_Token {
222 int type;
223 CONST char *start;
224 int size;
225 int numComponents;
226 } Tcl_Token;
227 The first five fields of a Tcl_Parse structure are filled in only by
229 Tcl_ParseCommand. These fields are not used by the other parsing pro‐
230 cedures.
231 Tcl_ParseCommand fills in a Tcl_Parse structure with information that
233 describes one Tcl command and any comments that precede the command.
234 If there are comments, the commentStart field points to the # character
235 that begins the first comment and commentSize indicates the number of
236 bytes in all of the comments preceding the command, including the new‐
237 line character that terminates the last comment. If the command is not
238 preceded by any comments, commentSize is 0. Tcl_ParseCommand also sets
239 the commandStart field to point to the first character of the first
240 word in the command (skipping any comments and leading space) and com‐
241 mandSize gives the total number of bytes in the command, including the
242 character pointed to by commandStart up to and including the newline,
243 close bracket, or semicolon character that terminates the command. The
244 numWords field gives the total number of words in the command.
245 All parsing procedures set the remaining fields, tokenPtr and numTo‐
247 kens. The tokenPtr field points to the first in an array of Tcl_Token
248 structures that describe the components of the entity being parsed.
249 The numTokens field gives the total number of tokens present in the
250 array. Each token contains four fields. The type field selects one of
251 several token types that are described below. The start field points
252 to the first character in the token and the size field gives the total
253 number of characters in the token. Some token types, such as
254 TCL_TOKEN_WORD and TCL_TOKEN_VARIABLE, consist of several component
255 tokens, which immediately follow the parent token; the numComponents
256 field describes how many of these there are. The type field has one of
257 the following values:
258 TCL_TOKEN_WORD This token ordinarily describes one word of a com‐
260 mand but it may also describe a quoted or braced
261 string in an expression. The token describes a
262 component of the script that is the result of con‐
263 catenating together a sequence of subcomponents,
264 each described by a separate subtoken. The token
265 starts with the first non-blank character of the
266 component (which may be a double-quote or open
267 brace) and includes all characters in the component
268 up to but not including the space, semicolon, close
269 bracket, close quote, or close brace that termi‐
270 nates the component. The numComponents field
271 counts the total number of sub-tokens that make up
272 the word, including sub-tokens of TCL_TOKEN_VARI‐
273 ABLE and TCL_TOKEN_BS tokens.
274 TCL_TOKEN_SIMPLE_WORD
276 This token has the same meaning as TCL_TOKEN_WORD,
277 except that the word is guaranteed to consist of a
278 single TCL_TOKEN_TEXT sub-token. The numComponents
279 field is always 1.
280 TCL_TOKEN_TEXT The token describes a range of literal text that is
282 part of a word. The numComponents field is always
283 0.
284 TCL_TOKEN_BS The token describes a backslash sequence such as \n
286 or \0xa3. The numComponents field is always 0.
287 TCL_TOKEN_COMMAND The token describes a command whose result result
289 must be substituted into the word. The token
290 includes the square brackets that surround the com‐
291 mand. The numComponents field is always 0 (the
292 nested command is not parsed; call Tcl_ParseCommand
293 recursively if you want to see its tokens).
294 TCL_TOKEN_VARIABLE The token describes a variable substitution,
296 including the $, variable name, and array index (if
297 there is one) up through the close parenthesis that
298 terminates the index. This token is followed by
299 one or more additional tokens that describe the
300 variable name and array index. If numComponents
301 is 1 then the variable is a scalar and the next
302 token is a TCL_TOKEN_TEXT token that gives the
303 variable name. If numComponents is greater than 1
304 then the variable is an array: the first sub-token
305 is a TCL_TOKEN_TEXT token giving the array name and
306 the remaining sub-tokens are TCL_TOKEN_TEXT,
307 TCL_TOKEN_BS, TCL_TOKEN_COMMAND, and
308 TCL_TOKEN_VARIABLE tokens that must be concatenated
309 to produce the array index. The numComponents field
310 includes nested sub-tokens that are part of
311 TCL_TOKEN_VARIABLE tokens in the array index.
312 TCL_TOKEN_SUB_EXPR The token describes one subexpression of an expres‐
314 sion (or an entire expression). A subexpression
315 may consist of a value such as an integer literal,
316 variable substitution, or parenthesized subexpres‐
317 sion; it may also consist of an operator and its
318 operands. The token starts with the first non-
319 blank character of the subexpression up to but not
320 including the space, brace, close-paren, or bracket
321 that terminates the subexpression. This token is
322 followed by one or more additional tokens that
323 describe the subexpression. If the first sub-token
324 after the TCL_TOKEN_SUB_EXPR token is a
325 TCL_TOKEN_OPERATOR token, the subexpression con‐
326 sists of an operator and its token operands. If
327 the operator has no operands, the subexpression
328 consists of just the TCL_TOKEN_OPERATOR token.
329 Each operand is described by a TCL_TOKEN_SUB_EXPR
330 token. Otherwise, the subexpression is a value
331 described by one of the token types TCL_TOKEN_WORD,
332 TCL_TOKEN_TEXT, TCL_TOKEN_BS, TCL_TOKEN_COMMAND,
333 TCL_TOKEN_VARIABLE, and TCL_TOKEN_SUB_EXPR. The
334 numComponents field counts the total number of sub-
335 tokens that make up the subexpression; this
336 includes the sub-tokens for any nested
337 TCL_TOKEN_SUB_EXPR tokens.
338 TCL_TOKEN_OPERATOR The token describes one operator of an expression
340 such as && or hypot. An TCL_TOKEN_OPERATOR token
341 is always preceded by a TCL_TOKEN_SUB_EXPR token
342 that describes the operator and its operands; the
343 TCL_TOKEN_SUB_EXPR token's numComponents field can
344 be used to determine the number of operands. A
345 binary operator such as * is followed by two
346 TCL_TOKEN_SUB_EXPR tokens that describe its oper‐
347 ands. A unary operator like - is followed by a
348 single TCL_TOKEN_SUB_EXPR token for its operand.
349 If the operator is a math function such as log10,
350 the TCL_TOKEN_OPERATOR token will give its name and
351 the following TCL_TOKEN_SUB_EXPR tokens will
352 describe its operands; if there are no operands (as
353 with rand), no TCL_TOKEN_SUB_EXPR tokens follow.
354 There is one trinary operator, ?, that appears in
355 if-then-else subexpressions such as x?y:z; in this
356 case, the ? TCL_TOKEN_OPERATOR token is followed by
357 three TCL_TOKEN_SUB_EXPR tokens for the operands x,
358 y, and z. The numComponents field for a
359 TCL_TOKEN_OPERATOR token is always 0.
360 After Tcl_ParseCommand returns, the first token pointed to by the
362 tokenPtr field of the Tcl_Parse structure always has type
363 TCL_TOKEN_WORD or TCL_TOKEN_SIMPLE_WORD. It is followed by the sub-
364 tokens that must be concatenated to produce the value of that word.
365 The next token is the TCL_TOKEN_WORD or TCL_TOKEN_SIMPLE_WORD token for
366 the second word, followed by sub-tokens for that word, and so on until
367 all numWords have been accounted for.
368 After Tcl_ParseExpr returns, the first token pointed to by the tokenPtr
370 field of the Tcl_Parse structure always has type TCL_TOKEN_SUB_EXPR.
371 It is followed by the sub-tokens that must be evaluated to produce the
372 value of the expression. Only the token information in the Tcl_Parse
373 structure is modified: the commentStart, commentSize, commandStart, and
374 commandSize fields are not modified by Tcl_ParseExpr.
375 After Tcl_ParseBraces returns, the array of tokens pointed to by the
377 tokenPtr field of the Tcl_Parse structure will contain a single
378 TCL_TOKEN_TEXT token if the braced string does not contain any back‐
379 slash-newlines. If the string does contain backslash-newlines, the
380 array of tokens will contain one or more TCL_TOKEN_TEXT or TCL_TOKEN_BS
381 sub-tokens that must be concatenated to produce the value of the
382 string. If the braced string was just {} (that is, the string was
383 empty), the single TCL_TOKEN_TEXT token will have a size field contain‐
384 ing zero; this ensures that at least one token appears to describe the
385 braced string. Only the token information in the Tcl_Parse structure
386 is modified: the commentStart, commentSize, commandStart, and command‐
387 Size fields are not modified by Tcl_ParseBraces.
388 After Tcl_ParseQuotedString returns, the array of tokens pointed to by
390 the tokenPtr field of the Tcl_Parse structure depends on the contents
391 of the quoted string. It will consist of one or more TCL_TOKEN_TEXT,
392 TCL_TOKEN_BS, TCL_TOKEN_COMMAND, and TCL_TOKEN_VARIABLE sub-tokens.
393 The array always contains at least one token; for example, if the argu‐
394 ment string is empty, the array returned consists of a single
395 TCL_TOKEN_TEXT token with a zero size field. Only the token informa‐
396 tion in the Tcl_Parse structure is modified: the commentStart, comment‐
397 Size, commandStart, and commandSize fields are not modified.
398 After Tcl_ParseVarName returns, the first token pointed to by the
400 tokenPtr field of the Tcl_Parse structure always has type
401 TCL_TOKEN_VARIABLE. It is followed by the sub-tokens that make up the
402 variable name as described above. The total length of the variable
403 name is contained in the size field of the first token. As in
404 Tcl_ParseExpr, only the token information in the Tcl_Parse structure is
405 modified by Tcl_ParseVarName: the commentStart, commentSize, command‐
406 Start, and commandSize fields are not modified.
407 All of the character pointers in the Tcl_Parse and Tcl_Token structures
409 refer to characters in the string argument passed to Tcl_ParseCommand,
410 Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_Parse‐
411 VarName.
412 There are additional fields in the Tcl_Parse structure after the numTo‐
414 kens field, but these are for the private use of Tcl_ParseCommand,
415 Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_Parse‐
416 VarName; they should not be referenced by code outside of these proce‐
417 dures.
418
421 backslash substitution, braces, command, expression, parse, token,
422 variable substitution
423Tcl 8.3 Tcl_ParseCommand(3)