2 '\" Copyright (c) 1997 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
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.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .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
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
277 Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
280 \fB#include <tcl.h>\fR
283 \fBTcl_ParseCommand\fR(\fIinterp, start, numBytes, nested, parsePtr\fR)
286 \fBTcl_ParseExpr\fR(\fIinterp, start, numBytes, parsePtr\fR)
289 \fBTcl_ParseBraces\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR)
292 \fBTcl_ParseQuotedString\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR)
295 \fBTcl_ParseVarName\fR(\fIinterp, start, numBytes, parsePtr, append\fR)
298 \fBTcl_ParseVar\fR(\fIinterp, start, termPtr\fR)
300 \fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
303 \fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR)
306 \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR)
308 .AS Tcl_Interp *usedParsePtr out
309 .AP Tcl_Interp *interp out
310 For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR
311 and \fBTcl_EvalTokensStandard\fR, used only for error reporting;
312 if NULL, then no error messages are left after errors.
313 For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR,
314 determines the context for evaluating the
315 script and also is used for error reporting; must not be NULL.
316 .AP "const char" *start in
317 Pointer to first character in string to parse.
319 Number of bytes in string to parse, not including any terminating null
320 character. If less than 0 then the script consists of all characters
321 following \fIstart\fR up to the first null character.
323 Non-zero means that the script is part of a command substitution so an
324 unquoted close bracket should be treated as a command terminator. If zero,
325 close brackets have no special meaning.
327 Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new
328 tokens should be appended to those already present. Zero means that
329 \fI*parsePtr\fR is uninitialized; any information in it is ignored.
330 This argument is normally 0.
331 .AP Tcl_Parse *parsePtr out
332 Points to structure to fill in with information about the parsed
333 command, expression, variable name, etc.
334 Any previous information in this structure
335 is ignored, unless \fIappend\fR is non-zero in a call to
336 \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR,
337 or \fBTcl_ParseVarName\fR.
338 .AP "const char" **termPtr out
339 If not NULL, points to a location where
340 \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and
341 \fBTcl_ParseVar\fR will store a pointer to the character
342 just after the terminating character (the close-brace, the last
343 character of the variable name, or the close-quote (respectively))
344 if the parse was successful.
345 .AP Tcl_Parse *usedParsePtr in
346 Points to structure that was filled in by a previous call to
347 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc.
351 These procedures parse Tcl commands or portions of Tcl commands such as
352 expressions or references to variables.
353 Each procedure takes a pointer to a script (or portion thereof)
354 and fills in the structure pointed to by \fIparsePtr\fR
355 with a collection of tokens describing the information that was parsed.
356 The procedures normally return \fBTCL_OK\fR.
357 However, if an error occurs then they return \fBTCL_ERROR\fR,
358 leave an error message in \fIinterp\fR's result
359 (if \fIinterp\fR is not NULL),
360 and leave nothing in \fIparsePtr\fR.
362 \fBTcl_ParseCommand\fR is a procedure that parses Tcl
363 scripts. Given a pointer to a script, it
364 parses the first command from the script. If the command was parsed
365 successfully, \fBTcl_ParseCommand\fR returns \fBTCL_OK\fR and fills in the
366 structure pointed to by \fIparsePtr\fR with information about the
367 structure of the command (see below for details).
368 If an error occurred in parsing the command then
369 \fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's
370 result, and no information is left at \fI*parsePtr\fR.
372 \fBTcl_ParseExpr\fR parses Tcl expressions.
373 Given a pointer to a script containing an expression,
374 \fBTcl_ParseExpr\fR parses the expression.
375 If the expression was parsed successfully,
376 \fBTcl_ParseExpr\fR returns \fBTCL_OK\fR and fills in the
377 structure pointed to by \fIparsePtr\fR with information about the
378 structure of the expression (see below for details).
379 If an error occurred in parsing the command then
380 \fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's
381 result, and no information is left at \fI*parsePtr\fR.
383 \fBTcl_ParseBraces\fR parses a string or command argument
384 enclosed in braces such as
385 \fB{hello}\fR or \fB{string \et with \et tabs}\fR
386 from the beginning of its argument \fIstart\fR.
387 The first character of \fIstart\fR must be \fB{\fR.
388 If the braced string was parsed successfully,
389 \fBTcl_ParseBraces\fR returns \fBTCL_OK\fR,
390 fills in the structure pointed to by \fIparsePtr\fR
391 with information about the structure of the string
392 (see below for details),
393 and stores a pointer to the character just after the terminating \fB}\fR
394 in the location given by \fI*termPtr\fR.
395 If an error occurs while parsing the string
396 then \fBTCL_ERROR\fR is returned,
397 an error message is left in \fIinterp\fR's result,
398 and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
400 \fBTcl_ParseQuotedString\fR parses a double-quoted string such as
401 \fB"sum is [expr {$a+$b}]"\fR
402 from the beginning of the argument \fIstart\fR.
403 The first character of \fIstart\fR must be \fB\N'34'\fR.
404 If the double-quoted string was parsed successfully,
405 \fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR,
406 fills in the structure pointed to by \fIparsePtr\fR
407 with information about the structure of the string
408 (see below for details),
409 and stores a pointer to the character just after the terminating \fB\N'34'\fR
410 in the location given by \fI*termPtr\fR.
411 If an error occurs while parsing the string
412 then \fBTCL_ERROR\fR is returned,
413 an error message is left in \fIinterp\fR's result,
414 and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
416 \fBTcl_ParseVarName\fR parses a Tcl variable reference such as
417 \fB$abc\fR or \fB$x([expr {$index + 1}])\fR from the beginning of its
418 \fIstart\fR argument.
419 The first character of \fIstart\fR must be \fB$\fR.
420 If a variable name was parsed successfully, \fBTcl_ParseVarName\fR
421 returns \fBTCL_OK\fR and fills in the structure pointed to by
422 \fIparsePtr\fR with information about the structure of the variable name
423 (see below for details). If an error
424 occurs while parsing the command then \fBTCL_ERROR\fR is returned, an
425 error message is left in \fIinterp\fR's result (if \fIinterp\fR is not
426 NULL), and no information is left at \fI*parsePtr\fR.
428 \fBTcl_ParseVar\fR parse a Tcl variable reference such as \fB$abc\fR
429 or \fB$x([expr {$index + 1}])\fR from the beginning of its \fIstart\fR
430 argument. The first character of \fIstart\fR must be \fB$\fR. If
431 the variable name is parsed successfully, \fBTcl_ParseVar\fR returns a
432 pointer to the string value of the variable. If an error occurs while
433 parsing, then NULL is returned and an error message is left in
434 \fIinterp\fR's result.
436 The information left at \fI*parsePtr\fR
437 by \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
438 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR
439 may include dynamically allocated memory.
440 If these five parsing procedures return \fBTCL_OK\fR
441 then the caller must invoke \fBTcl_FreeParse\fR to release
442 the storage at \fI*parsePtr\fR.
443 These procedures ignore any existing information in
444 \fI*parsePtr\fR (unless \fIappend\fR is non-zero),
445 so if repeated calls are being made to any of them
446 then \fBTcl_FreeParse\fR must be invoked once after each call.
448 \fBTcl_EvalTokensStandard\fR evaluates a sequence of parse tokens from
449 a Tcl_Parse structure. The tokens typically consist
450 of all the tokens in a word or all the tokens that make up the index for
451 a reference to an array variable. \fBTcl_EvalTokensStandard\fR performs the
452 substitutions requested by the tokens and concatenates the
454 The return value from \fBTcl_EvalTokensStandard\fR is a Tcl completion
455 code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR,
456 \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly
457 some other integer value originating in an extension.
458 In addition, a result value or error message is left in \fIinterp\fR's
459 result; it can be retrieved using \fBTcl_GetObjResult\fR.
461 \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
462 the return convention used: it returns the result in a new Tcl_Obj.
463 The reference count of the value returned as result has been
464 incremented, so the caller must
465 invoke \fBTcl_DecrRefCount\fR when it is finished with the value.
466 If an error or other exception occurs while evaluating the tokens
467 (such as a reference to a non-existent variable) then the return value
468 is NULL and an error message is left in \fIinterp\fR's result. The use
469 of \fBTcl_EvalTokens\fR is deprecated.
470 .SH "TCL_PARSE STRUCTURE"
472 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
473 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR
474 return parse information in two data structures, Tcl_Parse and Tcl_Token:
477 typedef struct Tcl_Parse {
478 const char *\fIcommentStart\fR;
479 int \fIcommentSize\fR;
480 const char *\fIcommandStart\fR;
481 int \fIcommandSize\fR;
483 Tcl_Token *\fItokenPtr\fR;
488 typedef struct Tcl_Token {
490 const char *\fIstart\fR;
492 int \fInumComponents\fR;
496 The first five fields of a Tcl_Parse structure
497 are filled in only by \fBTcl_ParseCommand\fR.
498 These fields are not used by the other parsing procedures.
500 \fBTcl_ParseCommand\fR fills in a Tcl_Parse structure
501 with information that describes one Tcl command and any comments that
503 If there are comments,
504 the \fIcommentStart\fR field points to the \fB#\fR character that begins
505 the first comment and \fIcommentSize\fR indicates the number of bytes
506 in all of the comments preceding the command, including the newline
507 character that terminates the last comment.
508 If the command is not preceded by any comments, \fIcommentSize\fR is 0.
509 \fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field
510 to point to the first character of the first
511 word in the command (skipping any comments and leading space) and
512 \fIcommandSize\fR gives the total number of bytes in the command,
513 including the character pointed to by \fIcommandStart\fR up to and
514 including the newline, close bracket, or semicolon character that
515 terminates the command. The \fInumWords\fR field gives the
516 total number of words in the command.
518 All parsing procedures set the remaining fields,
519 \fItokenPtr\fR and \fInumTokens\fR.
520 The \fItokenPtr\fR field points to the first in an array of Tcl_Token
521 structures that describe the components of the entity being parsed.
522 The \fInumTokens\fR field gives the total number of tokens
523 present in the array.
524 Each token contains four fields.
525 The \fItype\fR field selects one of several token types
526 that are described below. The \fIstart\fR field
527 points to the first character in the token and the \fIsize\fR field
528 gives the total number of characters in the token. Some token types,
529 such as \fBTCL_TOKEN_WORD\fR and \fBTCL_TOKEN_VARIABLE\fR, consist of
530 several component tokens, which immediately follow the parent token;
531 the \fInumComponents\fR field describes how many of these there are.
532 The \fItype\fR field has one of the following values:
536 This token ordinarily describes one word of a command
537 but it may also describe a quoted or braced string in an expression.
538 The token describes a component of the script that is
539 the result of concatenating together a sequence of subcomponents,
540 each described by a separate subtoken.
541 The token starts with the first non-blank
542 character of the component (which may be a double-quote or open brace)
543 and includes all characters in the component up to but not including the
544 space, semicolon, close bracket, close quote, or close brace that
545 terminates the component. The \fInumComponents\fR field counts the total
546 number of sub-tokens that make up the word, including sub-tokens
547 of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens.
549 \fBTCL_TOKEN_SIMPLE_WORD\fR
551 This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
552 the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR
553 sub-token. The \fInumComponents\fR field is always 1.
555 \fBTCL_TOKEN_EXPAND_WORD\fR
557 This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
558 the command parser notes this word began with the expansion
559 prefix \fB{*}\fR, indicating that after substitution,
560 the list value of this word should be expanded to form multiple
561 arguments in command evaluation. This
562 token type can only be created by Tcl_ParseCommand.
566 The token describes a range of literal text that is part of a word.
567 The \fInumComponents\fR field is always 0.
571 The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR.
572 The \fInumComponents\fR field is always 0.
574 \fBTCL_TOKEN_COMMAND\fR
576 The token describes a command whose result must be substituted into
577 the word. The token includes the square brackets that surround the
578 command. The \fInumComponents\fR field is always 0 (the nested command
579 is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to
582 \fBTCL_TOKEN_VARIABLE\fR
584 The token describes a variable substitution, including the
585 \fB$\fR, variable name, and array index (if there is one) up through the
586 close parenthesis that terminates the index. This token is followed
587 by one or more additional tokens that describe the variable name and
588 array index. If \fInumComponents\fR is 1 then the variable is a
589 scalar and the next token is a \fBTCL_TOKEN_TEXT\fR token that gives the
590 variable name. If \fInumComponents\fR is greater than 1 then the
591 variable is an array: the first sub-token is a \fBTCL_TOKEN_TEXT\fR
592 token giving the array name and the remaining sub-tokens are
593 \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, and
594 \fBTCL_TOKEN_VARIABLE\fR tokens that must be concatenated to produce the
595 array index. The \fInumComponents\fR field includes nested sub-tokens
596 that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index.
598 \fBTCL_TOKEN_SUB_EXPR\fR
600 The token describes one subexpression of an expression
601 (or an entire expression).
602 A subexpression may consist of a value
603 such as an integer literal, variable substitution,
604 or parenthesized subexpression;
605 it may also consist of an operator and its operands.
606 The token starts with the first non-blank character of the subexpression
607 up to but not including the space, brace, close-paren, or bracket
608 that terminates the subexpression.
609 This token is followed by one or more additional tokens
610 that describe the subexpression.
611 If the first sub-token after the \fBTCL_TOKEN_SUB_EXPR\fR token
612 is a \fBTCL_TOKEN_OPERATOR\fR token,
613 the subexpression consists of an operator and its token operands.
614 If the operator has no operands, the subexpression consists of
615 just the \fBTCL_TOKEN_OPERATOR\fR token.
616 Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token.
617 Otherwise, the subexpression is a value described by
618 one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR,
619 \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR,
620 \fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR.
621 The \fInumComponents\fR field
622 counts the total number of sub-tokens that make up the subexpression;
623 this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens.
625 \fBTCL_TOKEN_OPERATOR\fR
627 The token describes one operator of an expression
628 such as \fB&&\fR or \fBhypot\fR.
629 A \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a
630 \fBTCL_TOKEN_SUB_EXPR\fR token
631 that describes the operator and its operands;
632 the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field
633 can be used to determine the number of operands.
634 A binary operator such as \fB*\fR
635 is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens
636 that describe its operands.
637 A unary operator like \fB\-\fR
638 is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token
640 If the operator is a math function such as \fBlog10\fR,
641 the \fBTCL_TOKEN_OPERATOR\fR token will give its name and
642 the following \fBTCL_TOKEN_SUB_EXPR\fR tokens will describe
644 if there are no operands (as with \fBrand\fR),
645 no \fBTCL_TOKEN_SUB_EXPR\fR tokens follow.
646 There is one trinary operator, \fB?\fR,
647 that appears in if-then-else subexpressions
648 such as \fIx\fB?\fIy\fB:\fIz\fR;
649 in this case, the \fB?\fR \fBTCL_TOKEN_OPERATOR\fR token
650 is followed by three \fBTCL_TOKEN_SUB_EXPR\fR tokens for the operands
651 \fIx\fR, \fIy\fR, and \fIz\fR.
652 The \fInumComponents\fR field for a \fBTCL_TOKEN_OPERATOR\fR token
655 After \fBTcl_ParseCommand\fR returns, the first token pointed to by
656 the \fItokenPtr\fR field of the
657 Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or
658 \fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR.
659 It is followed by the sub-tokens
660 that must be concatenated to produce the value of that word.
661 The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR
662 of \fBTCL_TOKEN_EXPAND_WORD\fR token for the second word,
663 followed by sub-tokens for that
664 word, and so on until all \fInumWords\fR have been accounted
667 After \fBTcl_ParseExpr\fR returns, the first token pointed to by
668 the \fItokenPtr\fR field of the
669 Tcl_Parse structure always has type \fBTCL_TOKEN_SUB_EXPR\fR.
670 It is followed by the sub-tokens that must be evaluated
671 to produce the value of the expression.
672 Only the token information in the Tcl_Parse structure
673 is modified: the \fIcommentStart\fR, \fIcommentSize\fR,
674 \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified
675 by \fBTcl_ParseExpr\fR.
677 After \fBTcl_ParseBraces\fR returns,
678 the array of tokens pointed to by the \fItokenPtr\fR field of the
679 Tcl_Parse structure will contain a single \fBTCL_TOKEN_TEXT\fR token
680 if the braced string does not contain any backslash-newlines.
681 If the string does contain backslash-newlines,
682 the array of tokens will contain one or more
683 \fBTCL_TOKEN_TEXT\fR or \fBTCL_TOKEN_BS\fR sub-tokens
684 that must be concatenated to produce the value of the string.
685 If the braced string was just \fB{}\fR
686 (that is, the string was empty),
687 the single \fBTCL_TOKEN_TEXT\fR token will have a \fIsize\fR field
689 this ensures that at least one token appears
690 to describe the braced string.
691 Only the token information in the Tcl_Parse structure
692 is modified: the \fIcommentStart\fR, \fIcommentSize\fR,
693 \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified
694 by \fBTcl_ParseBraces\fR.
696 After \fBTcl_ParseQuotedString\fR returns,
697 the array of tokens pointed to by the \fItokenPtr\fR field of the
698 Tcl_Parse structure depends on the contents of the quoted string.
699 It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR,
700 \fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens.
701 The array always contains at least one token;
702 for example, if the argument \fIstart\fR is empty,
703 the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token
704 with a zero \fIsize\fR field.
705 Only the token information in the Tcl_Parse structure
706 is modified: the \fIcommentStart\fR, \fIcommentSize\fR,
707 \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified.
709 After \fBTcl_ParseVarName\fR returns, the first token pointed to by
710 the \fItokenPtr\fR field of the
711 Tcl_Parse structure always has type \fBTCL_TOKEN_VARIABLE\fR. It
712 is followed by the sub-tokens that make up the variable name as
713 described above. The total length of the variable name is
714 contained in the \fIsize\fR field of the first token.
715 As in \fBTcl_ParseExpr\fR,
716 only the token information in the Tcl_Parse structure
717 is modified by \fBTcl_ParseVarName\fR:
718 the \fIcommentStart\fR, \fIcommentSize\fR,
719 \fIcommandStart\fR, and \fIcommandSize\fR fields are not modified.
721 All of the character pointers in the
722 Tcl_Parse and Tcl_Token structures refer
723 to characters in the \fIstart\fR argument passed to
724 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
725 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR.
727 There are additional fields in the Tcl_Parse structure after the
728 \fInumTokens\fR field, but these are for the private use of
729 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
730 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be
731 referenced by code outside of these procedures.
733 backslash substitution, braces, command, expression, parse, token, variable substitution
OSDN Git Service
