diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
commit | 5514e37335c012cc70f5b9aee3cedfe3d57f583f (patch) | |
tree | 4ba7d8aad13735e52f59bdce7ca5ba3151ebd7e3 /tcl8.6/doc/ParseCmd.3 | |
parent | 768f87f613cc9789fcf8073018fa02178c8c91df (diff) | |
download | blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.zip blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.gz blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.bz2 |
undo subtree
Diffstat (limited to 'tcl8.6/doc/ParseCmd.3')
-rw-r--r-- | tcl8.6/doc/ParseCmd.3 | 467 |
1 files changed, 0 insertions, 467 deletions
diff --git a/tcl8.6/doc/ParseCmd.3 b/tcl8.6/doc/ParseCmd.3 deleted file mode 100644 index 667d697..0000000 --- a/tcl8.6/doc/ParseCmd.3 +++ /dev/null @@ -1,467 +0,0 @@ -'\" -'\" Copyright (c) 1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_ParseCommand\fR(\fIinterp, start, numBytes, nested, parsePtr\fR) -.sp -int -\fBTcl_ParseExpr\fR(\fIinterp, start, numBytes, parsePtr\fR) -.sp -int -\fBTcl_ParseBraces\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR) -.sp -int -\fBTcl_ParseQuotedString\fR(\fIinterp, start, numBytes, parsePtr, append, termPtr\fR) -.sp -int -\fBTcl_ParseVarName\fR(\fIinterp, start, numBytes, parsePtr, append\fR) -.sp -const char * -\fBTcl_ParseVar\fR(\fIinterp, start, termPtr\fR) -.sp -\fBTcl_FreeParse\fR(\fIusedParsePtr\fR) -.sp -Tcl_Obj * -\fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR) -.sp -int -\fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR) -.SH ARGUMENTS -.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; -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" *start in -Pointer to first character in string to parse. -.AP int numBytes in -Number of bytes in string to parse, not including any terminating null -character. If less than 0 then the script consists of all characters -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, -close brackets have no special meaning. -.AP int append in -Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new -tokens should be appended to those already present. Zero means that -\fI*parsePtr\fR is uninitialized; any information in it is ignored. -This argument is normally 0. -.AP Tcl_Parse *parsePtr out -Points to structure to fill in with information about the parsed -command, expression, variable name, etc. -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 -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 -just after the terminating character (the close-brace, the last -character of the variable name, or the close-quote (respectively)) -if the parse was successful. -.AP Tcl_Parse *usedParsePtr in -Points to structure that was filled in by a previous call to -\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc. -.BE -.SH DESCRIPTION -.PP -These procedures parse Tcl commands or portions of Tcl commands such as -expressions or references to variables. -Each procedure takes a pointer to a script (or portion thereof) -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\fR's result -(if \fIinterp\fR is not NULL), -and leave nothing in \fIparsePtr\fR. -.PP -\fBTcl_ParseCommand\fR is a procedure that parses Tcl -scripts. Given a pointer to a script, it -parses the first command from the script. If the command was parsed -successfully, \fBTcl_ParseCommand\fR returns \fBTCL_OK\fR and fills in the -structure pointed to by \fIparsePtr\fR with information about the -structure of the command (see below for details). -If an error occurred in parsing the command then -\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's -result, and no information is left at \fI*parsePtr\fR. -.PP -\fBTcl_ParseExpr\fR parses Tcl expressions. -Given a pointer to a script containing an expression, -\fBTcl_ParseExpr\fR parses the expression. -If the expression was parsed successfully, -\fBTcl_ParseExpr\fR returns \fBTCL_OK\fR and fills in the -structure pointed to by \fIparsePtr\fR with information about the -structure of the expression (see below for details). -If an error occurred in parsing the command then -\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's -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 \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 -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 -in the location given by \fI*termPtr\fR. -If an error occurs while parsing the string -then \fBTCL_ERROR\fR is returned, -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 \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\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, -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 -\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 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 \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 -\fIinterp\fR's result. -.PP -The information left at \fI*parsePtr\fR -by \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, -\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR -may include dynamically allocated memory. -If these five parsing procedures return \fBTCL_OK\fR -then the caller must invoke \fBTcl_FreeParse\fR to release -the storage at \fI*parsePtr\fR. -These procedures ignore any existing information in -\fI*parsePtr\fR (unless \fIappend\fR is non-zero), -so if repeated calls are being made to any of them -then \fBTcl_FreeParse\fR must be invoked once after each call. -.PP -\fBTcl_EvalTokensStandard\fR evaluates a sequence of parse tokens from -a Tcl_Parse structure. The tokens typically consist -of all the tokens in a word or all the tokens that make up the index for -a reference to an array variable. \fBTcl_EvalTokensStandard\fR performs the -substitutions requested by the tokens and concatenates the -resulting values. -The return value from \fBTcl_EvalTokensStandard\fR is a Tcl completion -code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, -\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly -some other integer value originating in an extension. -In addition, a result value or error message is left in \fIinterp\fR's -result; it can be retrieved using \fBTcl_GetObjResult\fR. -.PP -\fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in -the return convention used: it returns the result in a new Tcl_Obj. -The reference count of the value returned as result has been -incremented, so the caller must -invoke \fBTcl_DecrRefCount\fR when it is finished with the value. -If an error or other exception occurs while evaluating the tokens -(such as a reference to a non-existent variable) then the return value -is NULL and an error message is left in \fIinterp\fR's result. The use -of \fBTcl_EvalTokens\fR is deprecated. -.SH "TCL_PARSE STRUCTURE" -.PP -\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, -\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR -return parse information in two data structures, Tcl_Parse and Tcl_Token: -.PP -.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; - ... -} \fBTcl_Parse\fR; - -typedef struct Tcl_Token { - int \fItype\fR; - const char *\fIstart\fR; - int \fIsize\fR; - int \fInumComponents\fR; -} \fBTcl_Token\fR; -.CE -.PP -The first five fields of a Tcl_Parse structure -are filled in only by \fBTcl_ParseCommand\fR. -These fields are not used by the other parsing procedures. -.PP -\fBTcl_ParseCommand\fR fills in a Tcl_Parse structure -with information that describes one Tcl command and any comments that -precede the command. -If there are comments, -the \fIcommentStart\fR field points to the \fB#\fR character that begins -the first comment and \fIcommentSize\fR indicates the number of bytes -in all of the comments preceding the command, including the newline -character that terminates the last comment. -If the command is not preceded by any comments, \fIcommentSize\fR is 0. -\fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field -to point to the first character of the first -word in the command (skipping any comments and leading space) and -\fIcommandSize\fR gives the total number of bytes in the command, -including the character pointed to by \fIcommandStart\fR up to and -including the newline, close bracket, or semicolon character that -terminates the command. The \fInumWords\fR field gives the -total number of words in the command. -.PP -All parsing procedures set the remaining fields, -\fItokenPtr\fR and \fInumTokens\fR. -The \fItokenPtr\fR field points to the first in an array of Tcl_Token -structures that describe the components of the entity being parsed. -The \fInumTokens\fR field gives the total number of tokens -present in the array. -Each token contains four fields. -The \fItype\fR field selects one of several token types -that are described below. The \fIstart\fR field -points to the first character in the token and the \fIsize\fR field -gives the total number of characters in the token. Some token types, -such as \fBTCL_TOKEN_WORD\fR and \fBTCL_TOKEN_VARIABLE\fR, consist of -several component tokens, which immediately follow the parent token; -the \fInumComponents\fR field describes how many of these there are. -The \fItype\fR field has one of the following values: -.TP 20 -\fBTCL_TOKEN_WORD\fR -. -This token ordinarily describes one word of a command -but it may also describe a quoted or braced string in an expression. -The token describes a component of the script that is -the result of concatenating together a sequence of subcomponents, -each described by a separate subtoken. -The token starts with the first non-blank -character of the component (which may be a double-quote or open brace) -and includes all characters in the component up to but not including the -space, semicolon, close bracket, close quote, or close brace that -terminates the component. The \fInumComponents\fR field counts the total -number of sub-tokens that make up the word, including sub-tokens -of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens. -.TP -\fBTCL_TOKEN_SIMPLE_WORD\fR -. -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 -. -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. -.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. -.TP -\fBTCL_TOKEN_BS\fR -. -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 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 -see its tokens). -.TP -\fBTCL_TOKEN_VARIABLE\fR -. -The token describes a variable substitution, including the -\fB$\fR, variable name, and array index (if there is one) up through the -close parenthesis that terminates the index. This token is followed -by one or more additional tokens that describe the variable name and -array index. If \fInumComponents\fR is 1 then the variable is a -scalar and the next token is a \fBTCL_TOKEN_TEXT\fR token that gives the -variable name. If \fInumComponents\fR is greater than 1 then the -variable is an array: the first sub-token is a \fBTCL_TOKEN_TEXT\fR -token giving the array name and the remaining sub-tokens are -\fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, and -\fBTCL_TOKEN_VARIABLE\fR tokens that must be concatenated to produce the -array index. The \fInumComponents\fR field includes nested sub-tokens -that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index. -.TP -\fBTCL_TOKEN_SUB_EXPR\fR -. -The token describes one subexpression of an expression -(or an entire expression). -A subexpression may consist of a value -such as an integer literal, variable substitution, -or parenthesized subexpression; -it may also consist of an operator and its operands. -The token starts with the first non-blank character of the subexpression -up to but not including the space, brace, close-paren, or bracket -that terminates the subexpression. -This token is followed by one or more additional tokens -that describe the subexpression. -If the first sub-token after the \fBTCL_TOKEN_SUB_EXPR\fR token -is a \fBTCL_TOKEN_OPERATOR\fR token, -the subexpression consists of an operator and its token operands. -If the operator has no operands, the subexpression consists of -just the \fBTCL_TOKEN_OPERATOR\fR token. -Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token. -Otherwise, the subexpression is a value described by -one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR, -\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, -\fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR. -The \fInumComponents\fR field -counts the total number of sub-tokens that make up the subexpression; -this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens. -.TP -\fBTCL_TOKEN_OPERATOR\fR -. -The token describes one operator of an expression -such as \fB&&\fR or \fBhypot\fR. -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 -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 -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, -the \fBTCL_TOKEN_OPERATOR\fR token will give its name and -the following \fBTCL_TOKEN_SUB_EXPR\fR tokens will describe -its operands; -if there are no operands (as with \fBrand\fR), -no \fBTCL_TOKEN_SUB_EXPR\fR tokens follow. -There is one trinary operator, \fB?\fR, -that appears in if-then-else subexpressions -such as \fIx\fB?\fIy\fB:\fIz\fR; -in this case, the \fB?\fR \fBTCL_TOKEN_OPERATOR\fR token -is followed by three \fBTCL_TOKEN_SUB_EXPR\fR tokens for the operands -\fIx\fR, \fIy\fR, and \fIz\fR. -The \fInumComponents\fR field for a \fBTCL_TOKEN_OPERATOR\fR token -is always 0. -.PP -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 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 -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. -.PP -After \fBTcl_ParseExpr\fR returns, the first token pointed to by -the \fItokenPtr\fR field of the -Tcl_Parse structure always has type \fBTCL_TOKEN_SUB_EXPR\fR. -It is followed by the sub-tokens that must be evaluated -to produce the value of the expression. -Only the token information in the Tcl_Parse structure -is modified: the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified -by \fBTcl_ParseExpr\fR. -.PP -After \fBTcl_ParseBraces\fR returns, -the array of tokens pointed to by the \fItokenPtr\fR field of the -Tcl_Parse structure will contain a single \fBTCL_TOKEN_TEXT\fR token -if the braced string does not contain any backslash-newlines. -If the string does contain backslash-newlines, -the array of tokens will contain one or more -\fBTCL_TOKEN_TEXT\fR or \fBTCL_TOKEN_BS\fR sub-tokens -that must be concatenated to produce the value of the string. -If the braced string was just \fB{}\fR -(that is, the string was empty), -the single \fBTCL_TOKEN_TEXT\fR token will have a \fIsize\fR field -containing zero; -this ensures that at least one token appears -to describe the braced string. -Only the token information in the Tcl_Parse structure -is modified: the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified -by \fBTcl_ParseBraces\fR. -.PP -After \fBTcl_ParseQuotedString\fR returns, -the array of tokens pointed to by the \fItokenPtr\fR field of the -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 \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 -is modified: the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. -.PP -After \fBTcl_ParseVarName\fR returns, the first token pointed to by -the \fItokenPtr\fR field of the -Tcl_Parse structure always has type \fBTCL_TOKEN_VARIABLE\fR. It -is followed by the sub-tokens that make up the variable name as -described above. The total length of the variable name is -contained in the \fIsize\fR field of the first token. -As in \fBTcl_ParseExpr\fR, -only the token information in the Tcl_Parse structure -is modified by \fBTcl_ParseVarName\fR: -the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. -.PP -All of the character pointers in the -Tcl_Parse and Tcl_Token structures refer -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 -There are additional fields in the Tcl_Parse structure after the -\fInumTokens\fR field, but these are for the private use of -\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, -\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be -referenced by code outside of these procedures. -.SH KEYWORDS -backslash substitution, braces, command, expression, parse, token, variable substitution |