Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1997 Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: ParseCmd.3,v 1.10.2.1 2003/03/19 20:06:50 dgp Exp $ | |
8 | '\" | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
12 | '\" .AP type name in/out ?indent? | |
13 | '\" Start paragraph describing an argument to a library procedure. | |
14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
15 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
17 | '\" needed; use .AS below instead) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
20 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
21 | '\" name are examples of largest possible arguments that will be passed | |
22 | '\" to .AP later. If args are omitted, default tab stops are used. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
37 | '\" .VS ?version? ?br? | |
38 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
39 | '\" of man pages. The first argument is ignored and used for recording | |
40 | '\" the version when the .VS was added, so that the sidebars can be | |
41 | '\" found and removed when they reach a certain age. If another argument | |
42 | '\" is present, then a line break is forced before starting the sidebar. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
61 | '\" .OP cmdName dbName dbClass | |
62 | '\" Start of description of a specific option. cmdName gives the | |
63 | '\" option's name as specified in the class command, dbName gives | |
64 | '\" the option's name in the option database, and dbClass gives | |
65 | '\" the option's class in the option database. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
164 | '\" # Special macro to handle page bottom: finish off current | |
165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
166 | '\" # page bottom macro. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
173 | .\" Draw three-sided box if this is the box's first page, | |
174 | .\" draw two sides but no top otherwise. | |
175 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
179 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" | |
246 | .BS | |
247 | .SH NAME | |
248 | Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions | |
249 | .SH SYNOPSIS | |
250 | .nf | |
251 | \fB#include <tcl.h>\fR | |
252 | .sp | |
253 | int | |
254 | \fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR) | |
255 | .sp | |
256 | int | |
257 | \fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR) | |
258 | .sp | |
259 | int | |
260 | \fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) | |
261 | .sp | |
262 | int | |
263 | \fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) | |
264 | .sp | |
265 | int | |
266 | \fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR) | |
267 | .sp | |
268 | CONST char * | |
269 | \fBTcl_ParseVar\fR(\fIinterp, string, termPtr\fR) | |
270 | .sp | |
271 | \fBTcl_FreeParse\fR(\fIusedParsePtr\fR) | |
272 | .sp | |
273 | Tcl_Obj * | |
274 | \fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR) | |
275 | .sp | |
276 | int | |
277 | \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR) | |
278 | .SH ARGUMENTS | |
279 | .AS Tcl_Interp *usedParsePtr | |
280 | .AP Tcl_Interp *interp out | |
281 | For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR | |
282 | and \fBTcl_EvalTokensStandard\fR, used only for error reporting; | |
283 | if NULL, then no error messages are left after errors. | |
284 | For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR, | |
285 | determines the context for evaluating the | |
286 | script and also is used for error reporting; must not be NULL. | |
287 | .AP "CONST char" *string in | |
288 | Pointer to first character in string to parse. | |
289 | .AP int numBytes in | |
290 | Number of bytes in \fIstring\fR, not including any terminating null | |
291 | character. If less than 0 then the script consists of all characters | |
292 | in \fIstring\fR up to the first null character. | |
293 | .AP int nested in | |
294 | Non-zero means that the script is part of a command substitution so an | |
295 | unquoted close bracket should be treated as a command terminator. If zero, | |
296 | close brackets have no special meaning. | |
297 | .AP int append in | |
298 | Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new | |
299 | tokens should be appended to those already present. Zero means that | |
300 | \fI*parsePtr\fR is uninitialized; any information in it is ignored. | |
301 | This argument is normally 0. | |
302 | .AP Tcl_Parse *parsePtr out | |
303 | Points to structure to fill in with information about the parsed | |
304 | command, expression, variable name, etc. | |
305 | Any previous information in this structure | |
306 | is ignored, unless \fIappend\fR is non-zero in a call to | |
307 | \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, | |
308 | or \fBTcl_ParseVarName\fR. | |
309 | .AP "CONST char" **termPtr out | |
310 | If not NULL, points to a location where | |
311 | \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and | |
312 | \fBTcl_ParseVar\fR will store a pointer to the character | |
313 | just after the terminating character (the close-brace, the last | |
314 | character of the variable name, or the close-quote (respectively)) | |
315 | if the parse was successful. | |
316 | .AP Tcl_Parse *usedParsePtr in | |
317 | Points to structure that was filled in by a previous call to | |
318 | \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc. | |
319 | .BE | |
320 | ||
321 | .SH DESCRIPTION | |
322 | .PP | |
323 | These procedures parse Tcl commands or portions of Tcl commands such as | |
324 | expressions or references to variables. | |
325 | Each procedure takes a pointer to a script (or portion thereof) | |
326 | and fills in the structure pointed to by \fIparsePtr\fR | |
327 | with a collection of tokens describing the information that was parsed. | |
328 | The procedures normally return \fBTCL_OK\fR. | |
329 | However, if an error occurs then they return \fBTCL_ERROR\fR, | |
330 | leave an error message in \fIinterp's\fR result | |
331 | (if \fIinterp\fR is not NULL), | |
332 | and leave nothing in \fIparsePtr\fR. | |
333 | .PP | |
334 | \fBTcl_ParseCommand\fR is a procedure that parses Tcl | |
335 | scripts. Given a pointer to a script, it | |
336 | parses the first command from the script. If the command was parsed | |
337 | successfully, \fBTcl_ParseCommand\fR returns \fBTCL_OK\fR and fills in the | |
338 | structure pointed to by \fIparsePtr\fR with information about the | |
339 | structure of the command (see below for details). | |
340 | If an error occurred in parsing the command then | |
341 | \fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's | |
342 | result, and no information is left at \fI*parsePtr\fR. | |
343 | .PP | |
344 | \fBTcl_ParseExpr\fR parses Tcl expressions. | |
345 | Given a pointer to a script containing an expression, | |
346 | \fBTcl_ParseCommand\fR parses the expression. | |
347 | If the expression was parsed successfully, | |
348 | \fBTcl_ParseExpr\fR returns \fBTCL_OK\fR and fills in the | |
349 | structure pointed to by \fIparsePtr\fR with information about the | |
350 | structure of the expression (see below for details). | |
351 | If an error occurred in parsing the command then | |
352 | \fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's | |
353 | result, and no information is left at \fI*parsePtr\fR. | |
354 | .PP | |
355 | \fBTcl_ParseBraces\fR parses a string or command argument | |
356 | enclosed in braces such as | |
357 | \fB{hello}\fR or \fB{string \\t with \\t tabs}\fR | |
358 | from the beginning of its argument \fIstring\fR. | |
359 | The first character of \fIstring\fR must be \fB{\fR. | |
360 | If the braced string was parsed successfully, | |
361 | \fBTcl_ParseBraces\fR returns \fBTCL_OK\fR, | |
362 | fills in the structure pointed to by \fIparsePtr\fR | |
363 | with information about the structure of the string | |
364 | (see below for details), | |
365 | and stores a pointer to the character just after the terminating \fB}\fR | |
366 | in the location given by \fI*termPtr\fR. | |
367 | If an error occurs while parsing the string | |
368 | then \fBTCL_ERROR\fR is returned, | |
369 | an error message is left in \fIinterp\fR's result, | |
370 | and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. | |
371 | .PP | |
372 | \fBTcl_ParseQuotedString\fR parses a double-quoted string such as | |
373 | \fB"sum is [expr $a+$b]"\fR | |
374 | from the beginning of the argument \fIstring\fR. | |
375 | The first character of \fIstring\fR must be \fB"\fR. | |
376 | If the double-quoted string was parsed successfully, | |
377 | \fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR, | |
378 | fills in the structure pointed to by \fIparsePtr\fR | |
379 | with information about the structure of the string | |
380 | (see below for details), | |
381 | and stores a pointer to the character just after the terminating \fB"\fR | |
382 | in the location given by \fI*termPtr\fR. | |
383 | If an error occurs while parsing the string | |
384 | then \fBTCL_ERROR\fR is returned, | |
385 | an error message is left in \fIinterp\fR's result, | |
386 | and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. | |
387 | .PP | |
388 | \fBTcl_ParseVarName\fR parses a Tcl variable reference such as | |
389 | \fB$abc\fR or \fB$x([expr $index + 1])\fR from the beginning of its | |
390 | \fIstring\fR argument. | |
391 | The first character of \fIstring\fR must be \fB$\fR. | |
392 | If a variable name was parsed successfully, \fBTcl_ParseVarName\fR | |
393 | returns \fBTCL_OK\fR and fills in the structure pointed to by | |
394 | \fIparsePtr\fR with information about the structure of the variable name | |
395 | (see below for details). If an error | |
396 | occurs while parsing the command then \fBTCL_ERROR\fR is returned, an | |
397 | error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't | |
398 | NULL), and no information is left at \fI*parsePtr\fR. | |
399 | .PP | |
400 | \fBTcl_ParseVar\fR parse a Tcl variable reference such as \fB$abc\fR | |
401 | or \fB$x([expr $index + 1])\fR from the beginning of its \fIstring\fR | |
402 | argument. The first character of \fIstring\fR must be \fB$\fR. If | |
403 | the variable name is parsed successfully, \fBTcl_ParseVar\fR returns a | |
404 | pointer to the string value of the variable. If an error occurs while | |
405 | parsing, then NULL is returned and an error message is left in | |
406 | \fIinterp\fR's result. | |
407 | .PP | |
408 | The information left at \fI*parsePtr\fR | |
409 | by \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, | |
410 | \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR | |
411 | may include dynamically allocated memory. | |
412 | If these five parsing procedures return \fBTCL_OK\fR | |
413 | then the caller must invoke \fBTcl_FreeParse\fR to release | |
414 | the storage at \fI*parsePtr\fR. | |
415 | These procedures ignore any existing information in | |
416 | \fI*parsePtr\fR (unless \fIappend\fR is non-zero), | |
417 | so if repeated calls are being made to any of them | |
418 | then \fBTcl_FreeParse\fR must be invoked once after each call. | |
419 | .PP | |
420 | \fBTcl_EvalTokensStandard\fR evaluates a sequence of parse tokens from | |
421 | a Tcl_Parse structure. The tokens typically consist | |
422 | of all the tokens in a word or all the tokens that make up the index for | |
423 | a reference to an array variable. \fBTcl_EvalTokensStandard\fR performs the | |
424 | substitutions requested by the tokens and concatenates the | |
425 | resulting values. | |
426 | The return value from \fBTcl_EvalTokensStandard\fR is a Tcl completion | |
427 | code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, | |
428 | \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly | |
429 | some other integer value originating in an extension. | |
430 | In addition, a result value or error message is left in \fIinterp\fR's | |
431 | result; it can be retrieved using \fBTcl_GetObjResult\fR. | |
432 | .PP | |
433 | \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in | |
434 | the return convention used: it returns the result in a new Tcl_Obj. | |
435 | The reference count of the object returned as result has been | |
436 | incremented, so the caller must | |
437 | invoke \fBTcl_DecrRefCount\fR when it is finished with the object. | |
438 | If an error or other exception occurs while evaluating the tokens | |
439 | (such as a reference to a non-existent variable) then the return value | |
440 | is NULL and an error message is left in \fIinterp\fR's result. The use | |
441 | of \fBTcl_EvalTokens\fR is deprecated. | |
442 | ||
443 | .SH "TCL_PARSE STRUCTURE" | |
444 | .PP | |
445 | \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, | |
446 | \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR | |
447 | return parse information in two data structures, Tcl_Parse and Tcl_Token: | |
448 | .CS | |
449 | typedef struct Tcl_Parse { | |
450 | CONST char *\fIcommentStart\fR; | |
451 | int \fIcommentSize\fR; | |
452 | CONST char *\fIcommandStart\fR; | |
453 | int \fIcommandSize\fR; | |
454 | int \fInumWords\fR; | |
455 | Tcl_Token *\fItokenPtr\fR; | |
456 | int \fInumTokens\fR; | |
457 | ... | |
458 | } Tcl_Parse; | |
459 | ||
460 | typedef struct Tcl_Token { | |
461 | int \fItype\fR; | |
462 | CONST char *\fIstart\fR; | |
463 | int \fIsize\fR; | |
464 | int \fInumComponents\fR; | |
465 | } Tcl_Token; | |
466 | .CE | |
467 | .PP | |
468 | The first five fields of a Tcl_Parse structure | |
469 | are filled in only by \fBTcl_ParseCommand\fR. | |
470 | These fields are not used by the other parsing procedures. | |
471 | .PP | |
472 | \fBTcl_ParseCommand\fR fills in a Tcl_Parse structure | |
473 | with information that describes one Tcl command and any comments that | |
474 | precede the command. | |
475 | If there are comments, | |
476 | the \fIcommentStart\fR field points to the \fB#\fR character that begins | |
477 | the first comment and \fIcommentSize\fR indicates the number of bytes | |
478 | in all of the comments preceding the command, including the newline | |
479 | character that terminates the last comment. | |
480 | If the command is not preceded by any comments, \fIcommentSize\fR is 0. | |
481 | \fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field | |
482 | to point to the first character of the first | |
483 | word in the command (skipping any comments and leading space) and | |
484 | \fIcommandSize\fR gives the total number of bytes in the command, | |
485 | including the character pointed to by \fIcommandStart\fR up to and | |
486 | including the newline, close bracket, or semicolon character that | |
487 | terminates the command. The \fInumWords\fR field gives the | |
488 | total number of words in the command. | |
489 | .PP | |
490 | All parsing procedures set the remaining fields, | |
491 | \fItokenPtr\fR and \fInumTokens\fR. | |
492 | The \fItokenPtr\fR field points to the first in an array of Tcl_Token | |
493 | structures that describe the components of the entity being parsed. | |
494 | The \fInumTokens\fR field gives the total number of tokens | |
495 | present in the array. | |
496 | Each token contains four fields. | |
497 | The \fItype\fR field selects one of several token types | |
498 | that are described below. The \fIstart\fR field | |
499 | points to the first character in the token and the \fIsize\fR field | |
500 | gives the total number of characters in the token. Some token types, | |
501 | such as \fBTCL_TOKEN_WORD\fR and \fBTCL_TOKEN_VARIABLE\fR, consist of | |
502 | several component tokens, which immediately follow the parent token; | |
503 | the \fInumComponents\fR field describes how many of these there are. | |
504 | The \fItype\fR field has one of the following values: | |
505 | .TP 20 | |
506 | \fBTCL_TOKEN_WORD\fR | |
507 | This token ordinarily describes one word of a command | |
508 | but it may also describe a quoted or braced string in an expression. | |
509 | The token describes a component of the script that is | |
510 | the result of concatenating together a sequence of subcomponents, | |
511 | each described by a separate subtoken. | |
512 | The token starts with the first non-blank | |
513 | character of the component (which may be a double-quote or open brace) | |
514 | and includes all characters in the component up to but not including the | |
515 | space, semicolon, close bracket, close quote, or close brace that | |
516 | terminates the component. The \fInumComponents\fR field counts the total | |
517 | number of sub-tokens that make up the word, including sub-tokens | |
518 | of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens. | |
519 | .TP | |
520 | \fBTCL_TOKEN_SIMPLE_WORD\fR | |
521 | This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that | |
522 | the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR | |
523 | sub-token. The \fInumComponents\fR field is always 1. | |
524 | .TP | |
525 | \fBTCL_TOKEN_TEXT\fR | |
526 | The token describes a range of literal text that is part of a word. | |
527 | The \fInumComponents\fR field is always 0. | |
528 | .TP | |
529 | \fBTCL_TOKEN_BS\fR | |
530 | The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR. | |
531 | The \fInumComponents\fR field is always 0. | |
532 | .TP | |
533 | \fBTCL_TOKEN_COMMAND\fR | |
534 | The token describes a command whose result result must be substituted into | |
535 | the word. The token includes the square brackets that surround the | |
536 | command. The \fInumComponents\fR field is always 0 (the nested command | |
537 | is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to | |
538 | see its tokens). | |
539 | .TP | |
540 | \fBTCL_TOKEN_VARIABLE\fR | |
541 | The token describes a variable substitution, including the | |
542 | \fB$\fR, variable name, and array index (if there is one) up through the | |
543 | close parenthesis that terminates the index. This token is followed | |
544 | by one or more additional tokens that describe the variable name and | |
545 | array index. If \fInumComponents\fR is 1 then the variable is a | |
546 | scalar and the next token is a \fBTCL_TOKEN_TEXT\fR token that gives the | |
547 | variable name. If \fInumComponents\fR is greater than 1 then the | |
548 | variable is an array: the first sub-token is a \fBTCL_TOKEN_TEXT\fR | |
549 | token giving the array name and the remaining sub-tokens are | |
550 | \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, and | |
551 | \fBTCL_TOKEN_VARIABLE\fR tokens that must be concatenated to produce the | |
552 | array index. The \fInumComponents\fR field includes nested sub-tokens | |
553 | that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index. | |
554 | .TP | |
555 | \fBTCL_TOKEN_SUB_EXPR\fR | |
556 | The token describes one subexpression of an expression | |
557 | (or an entire expression). | |
558 | A subexpression may consist of a value | |
559 | such as an integer literal, variable substitution, | |
560 | or parenthesized subexpression; | |
561 | it may also consist of an operator and its operands. | |
562 | The token starts with the first non-blank character of the subexpression | |
563 | up to but not including the space, brace, close-paren, or bracket | |
564 | that terminates the subexpression. | |
565 | This token is followed by one or more additional tokens | |
566 | that describe the subexpression. | |
567 | If the first sub-token after the \fBTCL_TOKEN_SUB_EXPR\fR token | |
568 | is a \fBTCL_TOKEN_OPERATOR\fR token, | |
569 | the subexpression consists of an operator and its token operands. | |
570 | If the operator has no operands, the subexpression consists of | |
571 | just the \fBTCL_TOKEN_OPERATOR\fR token. | |
572 | Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token. | |
573 | Otherwise, the subexpression is a value described by | |
574 | one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR, | |
575 | \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, | |
576 | \fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR. | |
577 | The \fInumComponents\fR field | |
578 | counts the total number of sub-tokens that make up the subexpression; | |
579 | this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens. | |
580 | .TP | |
581 | \fBTCL_TOKEN_OPERATOR\fR | |
582 | The token describes one operator of an expression | |
583 | such as \fB&&\fR or \fBhypot\fR. | |
584 | An \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a | |
585 | \fBTCL_TOKEN_SUB_EXPR\fR token | |
586 | that describes the operator and its operands; | |
587 | the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field | |
588 | can be used to determine the number of operands. | |
589 | A binary operator such as \fB*\fR | |
590 | is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens | |
591 | that describe its operands. | |
592 | A unary operator like \fB-\fR | |
593 | is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token | |
594 | for its operand. | |
595 | If the operator is a math function such as \fBlog10\fR, | |
596 | the \fBTCL_TOKEN_OPERATOR\fR token will give its name and | |
597 | the following \fBTCL_TOKEN_SUB_EXPR\fR tokens will describe | |
598 | its operands; | |
599 | if there are no operands (as with \fBrand\fR), | |
600 | no \fBTCL_TOKEN_SUB_EXPR\fR tokens follow. | |
601 | There is one trinary operator, \fB?\fR, | |
602 | that appears in if-then-else subexpressions | |
603 | such as \fIx\fB?\fIy\fB:\fIz\fR; | |
604 | in this case, the \fB?\fR \fBTCL_TOKEN_OPERATOR\fR token | |
605 | is followed by three \fBTCL_TOKEN_SUB_EXPR\fR tokens for the operands | |
606 | \fIx\fR, \fIy\fR, and \fIz\fR. | |
607 | The \fInumComponents\fR field for a \fBTCL_TOKEN_OPERATOR\fR token | |
608 | is always 0. | |
609 | .PP | |
610 | After \fBTcl_ParseCommand\fR returns, the first token pointed to by | |
611 | the \fItokenPtr\fR field of the | |
612 | Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or | |
613 | \fBTCL_TOKEN_SIMPLE_WORD\fR. It is followed by the sub-tokens | |
614 | that must be concatenated to produce the value of that word. | |
615 | The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR | |
616 | token for the second word, followed by sub-tokens for that | |
617 | word, and so on until all \fInumWords\fR have been accounted | |
618 | for. | |
619 | .PP | |
620 | After \fBTcl_ParseExpr\fR returns, the first token pointed to by | |
621 | the \fItokenPtr\fR field of the | |
622 | Tcl_Parse structure always has type \fBTCL_TOKEN_SUB_EXPR\fR. | |
623 | It is followed by the sub-tokens that must be evaluated | |
624 | to produce the value of the expression. | |
625 | Only the token information in the Tcl_Parse structure | |
626 | is modified: the \fIcommentStart\fR, \fIcommentSize\fR, | |
627 | \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified | |
628 | by \fBTcl_ParseExpr\fR. | |
629 | .PP | |
630 | After \fBTcl_ParseBraces\fR returns, | |
631 | the array of tokens pointed to by the \fItokenPtr\fR field of the | |
632 | Tcl_Parse structure will contain a single \fBTCL_TOKEN_TEXT\fR token | |
633 | if the braced string does not contain any backslash-newlines. | |
634 | If the string does contain backslash-newlines, | |
635 | the array of tokens will contain one or more | |
636 | \fBTCL_TOKEN_TEXT\fR or \fBTCL_TOKEN_BS\fR sub-tokens | |
637 | that must be concatenated to produce the value of the string. | |
638 | If the braced string was just \fB{}\fR | |
639 | (that is, the string was empty), | |
640 | the single \fBTCL_TOKEN_TEXT\fR token will have a \fIsize\fR field | |
641 | containing zero; | |
642 | this ensures that at least one token appears | |
643 | to describe the braced string. | |
644 | Only the token information in the Tcl_Parse structure | |
645 | is modified: the \fIcommentStart\fR, \fIcommentSize\fR, | |
646 | \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified | |
647 | by \fBTcl_ParseBraces\fR. | |
648 | .PP | |
649 | After \fBTcl_ParseQuotedString\fR returns, | |
650 | the array of tokens pointed to by the \fItokenPtr\fR field of the | |
651 | Tcl_Parse structure depends on the contents of the quoted string. | |
652 | It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, | |
653 | \fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens. | |
654 | The array always contains at least one token; | |
655 | for example, if the argument \fIstring\fR is empty, | |
656 | the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token | |
657 | with a zero \fIsize\fR field. | |
658 | Only the token information in the Tcl_Parse structure | |
659 | is modified: the \fIcommentStart\fR, \fIcommentSize\fR, | |
660 | \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. | |
661 | .PP | |
662 | After \fBTcl_ParseVarName\fR returns, the first token pointed to by | |
663 | the \fItokenPtr\fR field of the | |
664 | Tcl_Parse structure always has type \fBTCL_TOKEN_VARIABLE\fR. It | |
665 | is followed by the sub-tokens that make up the variable name as | |
666 | described above. The total length of the variable name is | |
667 | contained in the \fIsize\fR field of the first token. | |
668 | As in \fBTcl_ParseExpr\fR, | |
669 | only the token information in the Tcl_Parse structure | |
670 | is modified by \fBTcl_ParseVarName\fR: | |
671 | the \fIcommentStart\fR, \fIcommentSize\fR, | |
672 | \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. | |
673 | .PP | |
674 | All of the character pointers in the | |
675 | Tcl_Parse and Tcl_Token structures refer | |
676 | to characters in the \fIstring\fR argument passed to | |
677 | \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, | |
678 | \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR. | |
679 | .PP | |
680 | There are additional fields in the Tcl_Parse structure after the | |
681 | \fInumTokens\fR field, but these are for the private use of | |
682 | \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, | |
683 | \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be | |
684 | referenced by code outside of these procedures. | |
685 | ||
686 | .SH KEYWORDS | |
687 | backslash substitution, braces, command, expression, parse, token, variable substitution |