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 er‐
52 ror reporting; must not be NULL.
53 const char *start (in) Pointer to first character in
55 string to parse.
56 int numBytes (in) Number of bytes in string to
58 parse, not including any termi‐
59 nating null character. If less
60 than 0 then the script consists
61 of all characters following
62 start up to the first null char‐
63 acter.
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 ap‐
76 pended to those already present.
77 Zero means that *parsePtr is
78 uninitialized; any information
79 in it is ignored. This argument
80 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
110 These procedures parse Tcl commands or portions of Tcl commands such as
111 expressions or references to variables. Each procedure takes a pointer
112 to a script (or portion thereof) and fills in the structure pointed to
113 by parsePtr with a collection of tokens describing the information that
114 was parsed. The procedures normally return TCL_OK. However, if an er‐
115 ror occurs then they return TCL_ERROR, leave an error message in in‐
116 terp's result (if interp is not NULL), and leave nothing in parsePtr.
117 Tcl_ParseCommand is a procedure that parses Tcl scripts. Given a
119 pointer to a script, it parses the first command from the script. If
120 the command was parsed successfully, Tcl_ParseCommand returns TCL_OK
121 and fills in the structure pointed to by parsePtr with information
122 about the structure of the command (see below for details). If an er‐
123 ror occurred in parsing the command then TCL_ERROR is returned, an er‐
124 ror message is left in interp's result, and no information is left at
125 *parsePtr.
126 Tcl_ParseExpr parses Tcl expressions. Given a pointer to a script con‐
128 taining an expression, Tcl_ParseExpr parses the expression. If the ex‐
129 pression was parsed successfully, Tcl_ParseExpr returns TCL_OK and
130 fills in the structure pointed to by parsePtr with information about
131 the structure of the expression (see below for details). If an error
132 occurred in parsing the command then TCL_ERROR is returned, an error
133 message is left in interp's result, and no information is left at
134 *parsePtr.
135 Tcl_ParseBraces parses a string or command argument enclosed in braces
137 such as {hello} or {string \t with \t tabs} from the beginning of its
138 argument start. The first character of start must be {. If the braced
139 string was parsed successfully, Tcl_ParseBraces returns TCL_OK, fills
140 in the structure pointed to by parsePtr with information about the
141 structure of the string (see below for details), and stores a pointer
142 to the character just after the terminating } in the location given by
143 *termPtr. If an error occurs while parsing the string then TCL_ERROR
144 is returned, an error message is left in interp's result, and no infor‐
145 mation is left at *parsePtr or *termPtr.
146 Tcl_ParseQuotedString parses a double-quoted string such as "sum is
148 [expr {$a+$b}]" from the beginning of the argument start. The first
149 character of start must be ". If the double-quoted string was parsed
150 successfully, Tcl_ParseQuotedString returns TCL_OK, fills in the struc‐
151 ture pointed to by parsePtr with information about the structure of the
152 string (see below for details), and stores a pointer to the character
153 just after the terminating " in the location given by *termPtr. If an
154 error occurs while parsing the string then TCL_ERROR is returned, an
155 error message is left in interp's result, and no information is left at
156 *parsePtr or *termPtr.
157 Tcl_ParseVarName parses a Tcl variable reference such as $abc or
159 $x([expr {$index + 1}]) from the beginning of its start argument. The
160 first character of start must be $. If a variable name was parsed suc‐
161 cessfully, Tcl_ParseVarName returns TCL_OK and fills in the structure
162 pointed to by parsePtr with information about the structure of the
163 variable name (see below for details). If an error occurs while pars‐
164 ing the command then TCL_ERROR is returned, an error message is left in
165 interp's result (if interp is not NULL), and no information is left at
166 *parsePtr.
167 Tcl_ParseVar parse a Tcl variable reference such as $abc or $x([expr
169 {$index + 1}]) from the beginning of its start argument. The first
170 character of start must be $. If the variable name is parsed success‐
171 fully, Tcl_ParseVar returns a pointer to the string value of the vari‐
172 able. If an error occurs while parsing, then NULL is returned and an
173 error message is left in interp's result.
174 The information left at *parsePtr by Tcl_ParseCommand, Tcl_ParseExpr,
176 Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_ParseVarName may in‐
177 clude dynamically allocated memory. If these five parsing procedures
178 return TCL_OK then the caller must invoke Tcl_FreeParse to release the
179 storage at *parsePtr. These procedures ignore any existing information
180 in *parsePtr (unless append is non-zero), so if repeated calls are be‐
181 ing made to any of them then Tcl_FreeParse must be invoked once after
182 each call.
183 Tcl_EvalTokensStandard evaluates a sequence of parse tokens from a
185 Tcl_Parse structure. The tokens typically consist of all the tokens in
186 a word or all the tokens that make up the index for a reference to an
187 array variable. Tcl_EvalTokensStandard performs the substitutions re‐
188 quested by the tokens and concatenates the resulting values. The re‐
189 turn value from Tcl_EvalTokensStandard is a Tcl completion code with
190 one of the values TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CON‐
191 TINUE, or possibly some other integer value originating in an exten‐
192 sion. In addition, a result value or error message is left in interp's
193 result; it can be retrieved using Tcl_GetObjResult.
194 Tcl_EvalTokens differs from Tcl_EvalTokensStandard only in the return
196 convention used: it returns the result in a new Tcl_Obj. The reference
197 count of the value returned as result has been incremented, so the
198 caller must invoke Tcl_DecrRefCount when it is finished with the value.
199 If an error or other exception occurs while evaluating the tokens (such
200 as a reference to a non-existent variable) then the return value is
201 NULL and an error message is left in interp's result. The use of
202 Tcl_EvalTokens is deprecated.
203
205 Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuoted‐
206 String, and Tcl_ParseVarName return parse information in two data
207 structures, Tcl_Parse and Tcl_Token:
208 typedef struct Tcl_Parse {
210 const char *commentStart;
211 int commentSize;
212 const char *commandStart;
213 int commandSize;
214 int numWords;
215 Tcl_Token *tokenPtr;
216 int numTokens;
217 ...
218 } Tcl_Parse;
219 typedef struct Tcl_Token {
221 int type;
222 const char *start;
223 int size;
224 int numComponents;
225 } Tcl_Token;
226 The first five fields of a Tcl_Parse structure are filled in only by
228 Tcl_ParseCommand. These fields are not used by the other parsing pro‐
229 cedures.
230 Tcl_ParseCommand fills in a Tcl_Parse structure with information that
232 describes one Tcl command and any comments that precede the command.
233 If there are comments, the commentStart field points to the # character
234 that begins the first comment and commentSize indicates the number of
235 bytes in all of the comments preceding the command, including the new‐
236 line character that terminates the last comment. If the command is not
237 preceded by any comments, commentSize is 0. Tcl_ParseCommand also sets
238 the commandStart field to point to the first character of the first
239 word in the command (skipping any comments and leading space) and com‐
240 mandSize gives the total number of bytes in the command, including the
241 character pointed to by commandStart up to and including the newline,
242 close bracket, or semicolon character that terminates the command. The
243 numWords field gives the total number of words in the command.
244 All parsing procedures set the remaining fields, tokenPtr and numTo‐
246 kens. The tokenPtr field points to the first in an array of Tcl_Token
247 structures that describe the components of the entity being parsed.
248 The numTokens field gives the total number of tokens present in the ar‐
249 ray. Each token contains four fields. The type field selects one of
250 several token types that are described below. The start field points
251 to the first character in the token and the size field gives the total
252 number of characters in the token. Some token types, such as TCL_TO‐
253 KEN_WORD and TCL_TOKEN_VARIABLE, consist of several component tokens,
254 which immediately follow the parent token; the numComponents field de‐
255 scribes how many of these there are. The type field has one of the
256 following values:
257 TCL_TOKEN_WORD This token ordinarily describes one word of a com‐
259 mand but it may also describe a quoted or braced
260 string in an expression. The token describes a
261 component of the script that is the result of con‐
262 catenating together a sequence of subcomponents,
263 each described by a separate subtoken. The token
264 starts with the first non-blank character of the
265 component (which may be a double-quote or open
266 brace) and includes all characters in the component
267 up to but not including the space, semicolon, close
268 bracket, close quote, or close brace that termi‐
269 nates the component. The numComponents field
270 counts the total number of sub-tokens that make up
271 the word, including sub-tokens of TCL_TOKEN_VARI‐
272 ABLE and TCL_TOKEN_BS tokens.
273 TCL_TOKEN_SIMPLE_WORD
275 This token has the same meaning as TCL_TOKEN_WORD,
276 except that the word is guaranteed to consist of a
277 single TCL_TOKEN_TEXT sub-token. The numComponents
278 field is always 1.
279 TCL_TOKEN_EXPAND_WORD
281 This token has the same meaning as TCL_TOKEN_WORD,
282 except that the command parser notes this word be‐
283 gan with the expansion prefix {*}, indicating that
284 after substitution, the list value of this word
285 should be expanded to form multiple arguments in
286 command evaluation. This token type can only be
287 created by Tcl_ParseCommand.
288 TCL_TOKEN_TEXT The token describes a range of literal text that is
290 part of a word. The numComponents field is always
291 0.
292 TCL_TOKEN_BS The token describes a backslash sequence such as \n
294 or \0xA3. The numComponents field is always 0.
295 TCL_TOKEN_COMMAND The token describes a command whose result must be
297 substituted into the word. The token includes the
298 square brackets that surround the command. The
299 numComponents field is always 0 (the nested command
300 is not parsed; call Tcl_ParseCommand recursively if
301 you want to see its tokens).
302 TCL_TOKEN_VARIABLE The token describes a variable substitution, in‐
304 cluding the $, variable name, and array index (if
305 there is one) up through the close parenthesis that
306 terminates the index. This token is followed by
307 one or more additional tokens that describe the
308 variable name and array index. If numComponents
309 is 1 then the variable is a scalar and the next to‐
310 ken is a TCL_TOKEN_TEXT token that gives the vari‐
311 able name. If numComponents is greater than 1 then
312 the variable is an array: the first sub-token is a
313 TCL_TOKEN_TEXT token giving the array name and the
314 remaining sub-tokens are TCL_TOKEN_TEXT, TCL_TO‐
315 KEN_BS, TCL_TOKEN_COMMAND, and TCL_TOKEN_VARIABLE
316 tokens that must be concatenated to produce the ar‐
317 ray index. The numComponents field includes nested
318 sub-tokens that are part of TCL_TOKEN_VARIABLE to‐
319 kens in the array index.
320 TCL_TOKEN_SUB_EXPR The token describes one subexpression of an expres‐
322 sion (or an entire expression). A subexpression
323 may consist of a value such as an integer literal,
324 variable substitution, or parenthesized subexpres‐
325 sion; it may also consist of an operator and its
326 operands. The token starts with the first non-
327 blank character of the subexpression up to but not
328 including the space, brace, close-paren, or bracket
329 that terminates the subexpression. This token is
330 followed by one or more additional tokens that de‐
331 scribe the subexpression. If the first sub-token
332 after the TCL_TOKEN_SUB_EXPR token is a TCL_TO‐
333 KEN_OPERATOR token, the subexpression consists of
334 an operator and its token operands. If the opera‐
335 tor has no operands, the subexpression consists of
336 just the TCL_TOKEN_OPERATOR token. Each operand is
337 described by a TCL_TOKEN_SUB_EXPR token. Other‐
338 wise, the subexpression is a value described by one
339 of the token types TCL_TOKEN_WORD, TCL_TOKEN_TEXT,
340 TCL_TOKEN_BS, TCL_TOKEN_COMMAND, TCL_TOKEN_VARI‐
341 ABLE, and TCL_TOKEN_SUB_EXPR. The numComponents
342 field counts the total number of sub-tokens that
343 make up the subexpression; this includes the sub-
344 tokens for any nested TCL_TOKEN_SUB_EXPR tokens.
345 TCL_TOKEN_OPERATOR The token describes one operator of an expression
347 such as && or hypot. A TCL_TOKEN_OPERATOR token is
348 always preceded by a TCL_TOKEN_SUB_EXPR token that
349 describes the operator and its operands; the
350 TCL_TOKEN_SUB_EXPR token's numComponents field can
351 be used to determine the number of operands. A bi‐
352 nary operator such as * is followed by two TCL_TO‐
353 KEN_SUB_EXPR tokens that describe its operands. A
354 unary operator like - is followed by a single
355 TCL_TOKEN_SUB_EXPR token for its operand. If the
356 operator is a math function such as log10, the
357 TCL_TOKEN_OPERATOR token will give its name and the
358 following TCL_TOKEN_SUB_EXPR tokens will describe
359 its operands; if there are no operands (as with
360 rand), no TCL_TOKEN_SUB_EXPR tokens follow. There
361 is one trinary operator, ?, that appears in if-
362 then-else subexpressions such as x?y:z; in this
363 case, the ? TCL_TOKEN_OPERATOR token is followed by
364 three TCL_TOKEN_SUB_EXPR tokens for the operands x,
365 y, and z. The numComponents field for a TCL_TO‐
366 KEN_OPERATOR token is always 0.
367 After Tcl_ParseCommand returns, the first token pointed to by the to‐
369 kenPtr field of the Tcl_Parse structure always has type TCL_TOKEN_WORD
370 or TCL_TOKEN_SIMPLE_WORD or TCL_TOKEN_EXPAND_WORD. It is followed by
371 the sub-tokens that must be concatenated to produce the value of that
372 word. The next token is the TCL_TOKEN_WORD or TCL_TOKEN_SIMPLE_WORD of
373 TCL_TOKEN_EXPAND_WORD token for the second word, followed by sub-tokens
374 for that word, and so on until all numWords have been accounted for.
375 After Tcl_ParseExpr returns, the first token pointed to by the tokenPtr
377 field of the Tcl_Parse structure always has type TCL_TOKEN_SUB_EXPR.
378 It is followed by the sub-tokens that must be evaluated to produce the
379 value of the expression. Only the token information in the Tcl_Parse
380 structure is modified: the commentStart, commentSize, commandStart, and
381 commandSize fields are not modified by Tcl_ParseExpr.
382 After Tcl_ParseBraces returns, the array of tokens pointed to by the
384 tokenPtr field of the Tcl_Parse structure will contain a single TCL_TO‐
385 KEN_TEXT token if the braced string does not contain any backslash-new‐
386 lines. If the string does contain backslash-newlines, the array of to‐
387 kens will contain one or more TCL_TOKEN_TEXT or TCL_TOKEN_BS sub-tokens
388 that must be concatenated to produce the value of the string. If the
389 braced string was just {} (that is, the string was empty), the single
390 TCL_TOKEN_TEXT token will have a size field containing zero; this en‐
391 sures that at least one token appears to describe the braced string.
392 Only the token information in the Tcl_Parse structure is modified: the
393 commentStart, commentSize, commandStart, and commandSize fields are not
394 modified by Tcl_ParseBraces.
395 After Tcl_ParseQuotedString returns, the array of tokens pointed to by
397 the tokenPtr field of the Tcl_Parse structure depends on the contents
398 of the quoted string. It will consist of one or more TCL_TOKEN_TEXT,
399 TCL_TOKEN_BS, TCL_TOKEN_COMMAND, and TCL_TOKEN_VARIABLE sub-tokens.
400 The array always contains at least one token; for example, if the argu‐
401 ment start is empty, the array returned consists of a single TCL_TO‐
402 KEN_TEXT token with a zero size field. Only the token information in
403 the Tcl_Parse structure is modified: the commentStart, commentSize,
404 commandStart, and commandSize fields are not modified.
405 After Tcl_ParseVarName returns, the first token pointed to by the to‐
407 kenPtr field of the Tcl_Parse structure always has type TCL_TOKEN_VARI‐
408 ABLE. It is followed by the sub-tokens that make up the variable name
409 as described above. The total length of the variable name is contained
410 in the size field of the first token. As in Tcl_ParseExpr, only the
411 token information in the Tcl_Parse structure is modified by Tcl_Parse‐
412 VarName: the commentStart, commentSize, commandStart, and commandSize
413 fields are not modified.
414 All of the character pointers in the Tcl_Parse and Tcl_Token structures
416 refer to characters in the start argument passed to Tcl_ParseCommand,
417 Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_Parse‐
418 VarName.
419 There are additional fields in the Tcl_Parse structure after the numTo‐
421 kens field, but these are for the private use of Tcl_ParseCommand,
422 Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_Parse‐
423 VarName; they should not be referenced by code outside of these proce‐
424 dures.
425
427 backslash substitution, braces, command, expression, parse, token,
428 variable substitution
429Tcl 8.3 Tcl_ParseCommand(3)