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