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 '\" RCS: @(#) $Id: ParseCmd.3,v 1.10.2.1 2003/03/19 20:06:50 dgp Exp $
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
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)
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.
25 '\" Start box enclosure. From here until next .BE, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure.
32 '\" Begin code excerpt.
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.
45 '\" End of vertical sidebar.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines, in four columns separated
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.
70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
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.
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
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
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
248 Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
251 \fB#include <tcl.h>\fR
254 \fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR)
257 \fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR)
260 \fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
263 \fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR)
266 \fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR)
269 \fBTcl_ParseVar\fR(\fIinterp, string, termPtr\fR)
271 \fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
274 \fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR)
277 \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
443 .SH "TCL_PARSE STRUCTURE"
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:
449 typedef struct Tcl_Parse {
450 CONST char *\fIcommentStart\fR;
451 int \fIcommentSize\fR;
452 CONST char *\fIcommandStart\fR;
453 int \fIcommandSize\fR;
455 Tcl_Token *\fItokenPtr\fR;
460 typedef struct Tcl_Token {
462 CONST char *\fIstart\fR;
464 int \fInumComponents\fR;
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.
472 \fBTcl_ParseCommand\fR fills in a Tcl_Parse structure
473 with information that describes one Tcl command and any comments that
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.
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:
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.
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.
526 The token describes a range of literal text that is part of a word.
527 The \fInumComponents\fR field is always 0.
530 The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR.
531 The \fInumComponents\fR field is always 0.
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
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.
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.
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
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
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
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
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.
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
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.
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.
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.
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.
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.
687 backslash substitution, braces, command, expression, parse, token, variable substitution
OSDN Git Service
