diff options
Diffstat (limited to 'doc/ParseCmd.3')
| -rw-r--r-- | doc/ParseCmd.3 | 104 |
1 files changed, 59 insertions, 45 deletions
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index af6b02e..b5fc6d0 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -14,22 +14,22 @@ Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_Par \fB#include <tcl.h>\fR .sp int -\fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR) +\fBTcl_ParseCommand\fR(\fIinterp, start, numBytes, nested, parsePtr\fR) .sp int -\fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR) +\fBTcl_ParseExpr\fR(\fIinterp, start, numBytes, parsePtr\fR) .sp int -\fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) +\fBTcl_ParseBraces\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR) .sp int -\fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) +\fBTcl_ParseQuotedString\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR) .sp int -\fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR) +\fBTcl_ParseVarName\fR(\fIinterp, start, numBytes, parsePtr, append\fR) .sp -CONST char * -\fBTcl_ParseVar\fR(\fIinterp, string, termPtr\fR) +const char * +\fBTcl_ParseVar\fR(\fIinterp, start, termPtr\fR) .sp \fBTcl_FreeParse\fR(\fIusedParsePtr\fR) .sp @@ -39,7 +39,7 @@ Tcl_Obj * int \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR) .SH ARGUMENTS -.AS Tcl_Interp *usedParsePtr +.AS Tcl_Interp *usedParsePtr out .AP Tcl_Interp *interp out For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR, used only for error reporting; @@ -47,12 +47,12 @@ if NULL, then no error messages are left after errors. For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR, determines the context for evaluating the script and also is used for error reporting; must not be NULL. -.AP "CONST char" *string in +.AP "const char" *start in Pointer to first character in string to parse. .AP int numBytes in -Number of bytes in \fIstring\fR, not including any terminating null +Number of bytes in string to parse, not including any terminating null character. If less than 0 then the script consists of all characters -in \fIstring\fR up to the first null character. +following \fIstart\fR up to the first null character. .AP int nested in Non-zero means that the script is part of a command substitution so an unquoted close bracket should be treated as a command terminator. If zero, @@ -69,7 +69,7 @@ Any previous information in this structure is ignored, unless \fIappend\fR is non-zero in a call to \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, or \fBTcl_ParseVarName\fR. -.AP "CONST char" **termPtr out +.AP "const char" **termPtr out If not NULL, points to a location where \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVar\fR will store a pointer to the character @@ -90,7 +90,7 @@ and fills in the structure pointed to by \fIparsePtr\fR with a collection of tokens describing the information that was parsed. The procedures normally return \fBTCL_OK\fR. However, if an error occurs then they return \fBTCL_ERROR\fR, -leave an error message in \fIinterp's\fR result +leave an error message in \fIinterp\fR's result (if \fIinterp\fR is not NULL), and leave nothing in \fIparsePtr\fR. .PP @@ -117,9 +117,9 @@ result, and no information is left at \fI*parsePtr\fR. .PP \fBTcl_ParseBraces\fR parses a string or command argument enclosed in braces such as -\fB{hello}\fR or \fB{string \\t with \\t tabs}\fR -from the beginning of its argument \fIstring\fR. -The first character of \fIstring\fR must be \fB{\fR. +\fB{hello}\fR or \fB{string \et with \et tabs}\fR +from the beginning of its argument \fIstart\fR. +The first character of \fIstart\fR must be \fB{\fR. If the braced string was parsed successfully, \fBTcl_ParseBraces\fR returns \fBTCL_OK\fR, fills in the structure pointed to by \fIparsePtr\fR @@ -133,15 +133,15 @@ an error message is left in \fIinterp\fR's result, and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. .PP \fBTcl_ParseQuotedString\fR parses a double-quoted string such as -\fB"sum is [expr $a+$b]"\fR -from the beginning of the argument \fIstring\fR. -The first character of \fIstring\fR must be \fB"\fR. +\fB"sum is [expr {$a+$b}]"\fR +from the beginning of the argument \fIstart\fR. +The first character of \fIstart\fR must be \fB\N'34'\fR. If the double-quoted string was parsed successfully, \fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR, fills in the structure pointed to by \fIparsePtr\fR with information about the structure of the string (see below for details), -and stores a pointer to the character just after the terminating \fB"\fR +and stores a pointer to the character just after the terminating \fB\N'34'\fR in the location given by \fI*termPtr\fR. If an error occurs while parsing the string then \fBTCL_ERROR\fR is returned, @@ -149,20 +149,20 @@ an error message is left in \fIinterp\fR's result, and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. .PP \fBTcl_ParseVarName\fR parses a Tcl variable reference such as -\fB$abc\fR or \fB$x([expr $index + 1])\fR from the beginning of its -\fIstring\fR argument. -The first character of \fIstring\fR must be \fB$\fR. +\fB$abc\fR or \fB$x([expr {$index + 1}])\fR from the beginning of its +\fIstart\fR argument. +The first character of \fIstart\fR must be \fB$\fR. If a variable name was parsed successfully, \fBTcl_ParseVarName\fR returns \fBTCL_OK\fR and fills in the structure pointed to by \fIparsePtr\fR with information about the structure of the variable name (see below for details). If an error occurs while parsing the command then \fBTCL_ERROR\fR is returned, an -error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't +error message is left in \fIinterp\fR's result (if \fIinterp\fR is not NULL), and no information is left at \fI*parsePtr\fR. .PP \fBTcl_ParseVar\fR parse a Tcl variable reference such as \fB$abc\fR -or \fB$x([expr $index + 1])\fR from the beginning of its \fIstring\fR -argument. The first character of \fIstring\fR must be \fB$\fR. If +or \fB$x([expr {$index + 1}])\fR from the beginning of its \fIstart\fR +argument. The first character of \fIstart\fR must be \fB$\fR. If the variable name is parsed successfully, \fBTcl_ParseVar\fR returns a pointer to the string value of the variable. If an error occurs while parsing, then NULL is returned and an error message is left in @@ -210,21 +210,21 @@ of \fBTcl_EvalTokens\fR is deprecated. return parse information in two data structures, Tcl_Parse and Tcl_Token: .CS typedef struct Tcl_Parse { - CONST char *\fIcommentStart\fR; - int \fIcommentSize\fR; - CONST char *\fIcommandStart\fR; - int \fIcommandSize\fR; - int \fInumWords\fR; - Tcl_Token *\fItokenPtr\fR; - int \fInumTokens\fR; - ... + const char *\fIcommentStart\fR; + int \fIcommentSize\fR; + const char *\fIcommandStart\fR; + int \fIcommandSize\fR; + int \fInumWords\fR; + Tcl_Token *\fItokenPtr\fR; + int \fInumTokens\fR; + ... } Tcl_Parse; typedef struct Tcl_Token { - int \fItype\fR; - CONST char *\fIstart\fR; - int \fIsize\fR; - int \fInumComponents\fR; + int \fItype\fR; + const char *\fIstart\fR; + int \fIsize\fR; + int \fInumComponents\fR; } Tcl_Token; .CE .PP @@ -285,6 +285,16 @@ This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR sub-token. The \fInumComponents\fR field is always 1. .TP +\fBTCL_TOKEN_EXPAND_WORD\fR +.VS 8.5 +This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that +the command parser notes this word began with the expansion +prefix \fB{*}\fR, indicating that after substitution, +the list value of this word should be expanded to form multiple +arguments in command evaluation. This +token type can only be created by Tcl_ParseCommand. +.VE 8.5 +.TP \fBTCL_TOKEN_TEXT\fR The token describes a range of literal text that is part of a word. The \fInumComponents\fR field is always 0. @@ -294,7 +304,7 @@ The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR. The \fInumComponents\fR field is always 0. .TP \fBTCL_TOKEN_COMMAND\fR -The token describes a command whose result result must be substituted into +The token describes a command whose result must be substituted into the word. The token includes the square brackets that surround the command. The \fInumComponents\fR field is always 0 (the nested command is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to @@ -344,7 +354,7 @@ this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens. \fBTCL_TOKEN_OPERATOR\fR The token describes one operator of an expression such as \fB&&\fR or \fBhypot\fR. -An \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a +A \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a \fBTCL_TOKEN_SUB_EXPR\fR token that describes the operator and its operands; the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field @@ -352,7 +362,7 @@ can be used to determine the number of operands. A binary operator such as \fB*\fR is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens that describe its operands. -A unary operator like \fB-\fR +A unary operator like \fB\-\fR is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token for its operand. If the operator is a math function such as \fBlog10\fR, @@ -373,12 +383,16 @@ is always 0. After \fBTcl_ParseCommand\fR returns, the first token pointed to by the \fItokenPtr\fR field of the Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or -\fBTCL_TOKEN_SIMPLE_WORD\fR. It is followed by the sub-tokens +.VS 8.5 +\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR. +It is followed by the sub-tokens that must be concatenated to produce the value of that word. The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR -token for the second word, followed by sub-tokens for that +of \fBTCL_TOKEN_EXPAND_WORD\fR token for the second word, +followed by sub-tokens for that word, and so on until all \fInumWords\fR have been accounted for. +.VE 8.5 .PP After \fBTcl_ParseExpr\fR returns, the first token pointed to by the \fItokenPtr\fR field of the @@ -415,7 +429,7 @@ Tcl_Parse structure depends on the contents of the quoted string. It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens. The array always contains at least one token; -for example, if the argument \fIstring\fR is empty, +for example, if the argument \fIstart\fR is empty, the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token with a zero \fIsize\fR field. Only the token information in the Tcl_Parse structure @@ -436,7 +450,7 @@ the \fIcommentStart\fR, \fIcommentSize\fR, .PP All of the character pointers in the Tcl_Parse and Tcl_Token structures refer -to characters in the \fIstring\fR argument passed to +to characters in the \fIstart\fR argument passed to \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR. .PP |