- NAME
- Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard — parse Tcl scripts and expressions
- SYNOPSIS
- #include <tcl.h>
- int
- Tcl_ParseCommand(interp, start, numBytes, nested, parsePtr)
- int
- Tcl_ParseExpr(interp, start, numBytes, parsePtr)
- int
- Tcl_ParseBraces(interp, start, numBytes, parsePtr, append, termPtr)
- int
- Tcl_ParseQuotedString(interp, start, numBytes, parsePtr, append, termPtr)
- int
- Tcl_ParseVarName(interp, start, numBytes, parsePtr, append)
- const char *
- Tcl_ParseVar(interp, start, termPtr)
- Tcl_FreeParse(usedParsePtr)
- Tcl_Obj *
- Tcl_EvalTokens(interp, tokenPtr, numTokens)
- int
- Tcl_EvalTokensStandard(interp, tokenPtr, numTokens)
- ARGUMENTS
- DESCRIPTION
- DEPRECATED FUNCTIONS
- TCL_PARSE STRUCTURE
- TCL_TOKEN_WORD
- TCL_TOKEN_SIMPLE_WORD
- TCL_TOKEN_EXPAND_WORD
- TCL_TOKEN_TEXT
- TCL_TOKEN_BS
- TCL_TOKEN_COMMAND
- TCL_TOKEN_VARIABLE
- TCL_TOKEN_SUB_EXPR
- TCL_TOKEN_OPERATOR
- REFERENCE COUNT MANAGEMENT
- KEYWORDS
Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard — parse Tcl scripts and expressions
#include <tcl.h>
int
Tcl_ParseCommand(interp, start, numBytes, nested, parsePtr)
int
Tcl_ParseExpr(interp, start, numBytes, parsePtr)
int
Tcl_ParseBraces(interp, start, numBytes, parsePtr, append, termPtr)
int
Tcl_ParseQuotedString(interp, start, numBytes, parsePtr, append, termPtr)
int
Tcl_ParseVarName(interp, start, numBytes, parsePtr, append)
const char *
Tcl_ParseVar(interp, start, termPtr)
Tcl_FreeParse(usedParsePtr)
Tcl_Obj *
Tcl_EvalTokens(interp, tokenPtr, numTokens)
int
Tcl_EvalTokensStandard(interp, tokenPtr, numTokens)
- Tcl_Interp *interp (out)
-
For procedures other than Tcl_FreeParse, Tcl_EvalTokens
and Tcl_EvalTokensStandard, used only for error reporting;
if NULL, then no error messages are left after errors.
For Tcl_EvalTokens and Tcl_EvalTokensStandard,
determines the context for evaluating the
script and also is used for error reporting; must not be NULL.
- const char *start (in)
-
Pointer to first character in string to parse.
- 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 start up to the first null character.
- 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.
- int append (in)
-
Non-zero means that *parsePtr already contains valid tokens; the new
tokens should be appended to those already present. Zero means that
*parsePtr is uninitialized; any information in it is ignored.
This argument is normally 0.
- 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 append is non-zero in a call to
Tcl_ParseBraces, Tcl_ParseQuotedString,
or Tcl_ParseVarName.
- const char **termPtr (out)
-
If not NULL, points to a location where
Tcl_ParseBraces, Tcl_ParseQuotedString, and
Tcl_ParseVar 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.
- Tcl_Parse *usedParsePtr (in)
-
Points to structure that was filled in by a previous call to
Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseVarName, etc.
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 parsePtr
with a collection of tokens describing the information that was parsed.
The procedures normally return TCL_OK.
However, if an error occurs then they return TCL_ERROR,
leave an error message in interp's result
(if interp is not NULL),
and leave nothing in parsePtr.
Tcl_ParseCommand 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, Tcl_ParseCommand returns TCL_OK and fills in the
structure pointed to by parsePtr with information about the
structure of the command (see below for details).
If an error occurred in parsing the command then
TCL_ERROR is returned, an error message is left in interp's
result, and no information is left at *parsePtr.
Tcl_ParseExpr parses Tcl expressions.
Given a pointer to a script containing an expression,
Tcl_ParseExpr parses the expression.
If the expression was parsed successfully,
Tcl_ParseExpr returns TCL_OK and fills in the
structure pointed to by parsePtr with information about the
structure of the expression (see below for details).
If an error occurred in parsing the command then
TCL_ERROR is returned, an error message is left in interp's
result, and no information is left at *parsePtr.
Tcl_ParseBraces parses a string or command argument
enclosed in braces such as
{hello} or {string \t with \t tabs}
from the beginning of its argument start.
The first character of start must be {.
If the braced string was parsed successfully,
Tcl_ParseBraces returns TCL_OK,
fills in the structure pointed to by parsePtr
with information about the structure of the string
(see below for details),
and stores a pointer to the character just after the terminating }
in the location given by *termPtr.
If an error occurs while parsing the string
then TCL_ERROR is returned,
an error message is left in interp's result,
and no information is left at *parsePtr or *termPtr.
Tcl_ParseQuotedString parses a double-quoted string such as
"sum is [expr {$a+$b}]"
from the beginning of the argument start.
The first character of start must be ".
If the double-quoted string was parsed successfully,
Tcl_ParseQuotedString returns TCL_OK,
fills in the structure pointed to by parsePtr
with information about the structure of the string
(see below for details),
and stores a pointer to the character just after the terminating "
in the location given by *termPtr.
If an error occurs while parsing the string
then TCL_ERROR is returned,
an error message is left in interp's result,
and no information is left at *parsePtr or *termPtr.
Tcl_ParseVarName parses a Tcl variable reference such as
$abc or $x([expr {$index + 1}]) from the beginning of its
start argument.
The first character of start must be $.
If a variable name was parsed successfully, Tcl_ParseVarName
returns TCL_OK and fills in the structure pointed to by
parsePtr with information about the structure of the variable name
(see below for details). If an error
occurs while parsing the command then TCL_ERROR is returned, an
error message is left in interp's result (if interp is not
NULL), and no information is left at *parsePtr.
Tcl_ParseVar parse a Tcl variable reference such as $abc
or $x([expr {$index + 1}]) from the beginning of its start
argument. The first character of start must be $. If
the variable name is parsed successfully, Tcl_ParseVar 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
interp's result.
The information left at *parsePtr
by Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces,
Tcl_ParseQuotedString, and Tcl_ParseVarName
may include dynamically allocated memory.
If these five parsing procedures return TCL_OK
then the caller must invoke Tcl_FreeParse to release
the storage at *parsePtr.
These procedures ignore any existing information in
*parsePtr (unless append is non-zero),
so if repeated calls are being made to any of them
then Tcl_FreeParse must be invoked once after each call.
Tcl_EvalTokensStandard 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. Tcl_EvalTokensStandard performs the
substitutions requested by the tokens and concatenates the
resulting values.
The return value from Tcl_EvalTokensStandard is a Tcl completion
code with one of the values TCL_OK, TCL_ERROR,
TCL_RETURN, TCL_BREAK, or TCL_CONTINUE, or possibly
some other integer value originating in an extension.
In addition, a result value or error message is left in interp's
result; it can be retrieved using Tcl_GetObjResult.
Tcl_EvalTokens differs from Tcl_EvalTokensStandard 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 Tcl_DecrRefCount 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 interp's result. The use
of Tcl_EvalTokens is deprecated.
Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces,
Tcl_ParseQuotedString, and Tcl_ParseVarName
return parse information in two data structures, Tcl_Parse and Tcl_Token:
typedef struct Tcl_Parse {
const char *commentStart;
int commentSize;
const char *commandStart;
int commandSize;
int numWords;
Tcl_Token *tokenPtr;
int numTokens;
...
} Tcl_Parse;
typedef struct Tcl_Token {
int type;
const char *start;
int size;
int numComponents;
} Tcl_Token;
The first five fields of a Tcl_Parse structure
are filled in only by Tcl_ParseCommand.
These fields are not used by the other parsing procedures.
Tcl_ParseCommand 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 commentStart field points to the # character that begins
the first comment and commentSize 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, commentSize is 0.
Tcl_ParseCommand also sets the commandStart field
to point to the first character of the first
word in the command (skipping any comments and leading space) and
commandSize gives the total number of bytes in the command,
including the character pointed to by commandStart up to and
including the newline, close bracket, or semicolon character that
terminates the command. The numWords field gives the
total number of words in the command.
All parsing procedures set the remaining fields,
tokenPtr and numTokens.
The tokenPtr field points to the first in an array of Tcl_Token
structures that describe the components of the entity being parsed.
The numTokens field gives the total number of tokens
present in the array.
Each token contains four fields.
The type field selects one of several token types
that are described below. The start field
points to the first character in the token and the size field
gives the total number of characters in the token. Some token types,
such as TCL_TOKEN_WORD and TCL_TOKEN_VARIABLE, consist of
several component tokens, which immediately follow the parent token;
the numComponents field describes how many of these there are.
The type field has one of the following values:
- TCL_TOKEN_WORD
-
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 numComponents field counts the total
number of sub-tokens that make up the word, including sub-tokens
of TCL_TOKEN_VARIABLE and TCL_TOKEN_BS tokens.
- TCL_TOKEN_SIMPLE_WORD
-
This token has the same meaning as TCL_TOKEN_WORD, except that
the word is guaranteed to consist of a single TCL_TOKEN_TEXT
sub-token. The numComponents field is always 1.
- TCL_TOKEN_EXPAND_WORD
-
This token has the same meaning as TCL_TOKEN_WORD, except that
the command parser notes this word began with the expansion
prefix {*}, 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.
- TCL_TOKEN_TEXT
-
The token describes a range of literal text that is part of a word.
The numComponents field is always 0.
- TCL_TOKEN_BS
-
The token describes a backslash sequence such as \n or \0xA3.
The numComponents field is always 0.
- TCL_TOKEN_COMMAND
-
The token describes a command whose result must be substituted into
the word. The token includes the square brackets that surround the
command. The numComponents field is always 0 (the nested command
is not parsed; call Tcl_ParseCommand recursively if you want to
see its tokens).
- TCL_TOKEN_VARIABLE
-
The token describes a variable substitution, including the
$, 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 numComponents is 1 then the variable is a
scalar and the next token is a TCL_TOKEN_TEXT token that gives the
variable name. If numComponents is greater than 1 then the
variable is an array: the first sub-token is a TCL_TOKEN_TEXT
token giving the array name and the remaining sub-tokens are
TCL_TOKEN_TEXT, TCL_TOKEN_BS, TCL_TOKEN_COMMAND, and
TCL_TOKEN_VARIABLE tokens that must be concatenated to produce the
array index. The numComponents field includes nested sub-tokens
that are part of TCL_TOKEN_VARIABLE tokens in the array index.
- TCL_TOKEN_SUB_EXPR
-
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 TCL_TOKEN_SUB_EXPR token
is a TCL_TOKEN_OPERATOR token,
the subexpression consists of an operator and its token operands.
If the operator has no operands, the subexpression consists of
just the TCL_TOKEN_OPERATOR token.
Each operand is described by a TCL_TOKEN_SUB_EXPR token.
Otherwise, the subexpression is a value described by
one of the token types TCL_TOKEN_WORD, TCL_TOKEN_TEXT,
TCL_TOKEN_BS, TCL_TOKEN_COMMAND,
TCL_TOKEN_VARIABLE, and TCL_TOKEN_SUB_EXPR.
The numComponents field
counts the total number of sub-tokens that make up the subexpression;
this includes the sub-tokens for any nested TCL_TOKEN_SUB_EXPR tokens.
- TCL_TOKEN_OPERATOR
-
The token describes one operator of an expression
such as && or hypot.
A TCL_TOKEN_OPERATOR token is always preceded by a
TCL_TOKEN_SUB_EXPR token
that describes the operator and its operands;
the TCL_TOKEN_SUB_EXPR token's numComponents field
can be used to determine the number of operands.
A binary operator such as *
is followed by two TCL_TOKEN_SUB_EXPR tokens
that describe its operands.
A unary operator like -
is followed by a single TCL_TOKEN_SUB_EXPR token
for its operand.
If the operator is a math function such as log10,
the TCL_TOKEN_OPERATOR token will give its name and
the following TCL_TOKEN_SUB_EXPR tokens will describe
its operands;
if there are no operands (as with rand),
no TCL_TOKEN_SUB_EXPR tokens follow.
There is one trinary operator, ?,
that appears in if-then-else subexpressions
such as x?y:z;
in this case, the ? TCL_TOKEN_OPERATOR token
is followed by three TCL_TOKEN_SUB_EXPR tokens for the operands
x, y, and z.
The numComponents field for a TCL_TOKEN_OPERATOR token
is always 0.
After Tcl_ParseCommand returns, the first token pointed to by
the tokenPtr field of the
Tcl_Parse structure always has type TCL_TOKEN_WORD or
TCL_TOKEN_SIMPLE_WORD or TCL_TOKEN_EXPAND_WORD.
It is followed by the sub-tokens
that must be concatenated to produce the value of that word.
The next token is the TCL_TOKEN_WORD or TCL_TOKEN_SIMPLE_WORD
of TCL_TOKEN_EXPAND_WORD token for the second word,
followed by sub-tokens for that
word, and so on until all numWords have been accounted
for.
After Tcl_ParseExpr returns, the first token pointed to by
the tokenPtr field of the
Tcl_Parse structure always has type TCL_TOKEN_SUB_EXPR.
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 commentStart, commentSize,
commandStart, and commandSize fields are not modified
by Tcl_ParseExpr.
After Tcl_ParseBraces returns,
the array of tokens pointed to by the tokenPtr field of the
Tcl_Parse structure will contain a single TCL_TOKEN_TEXT 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
TCL_TOKEN_TEXT or TCL_TOKEN_BS sub-tokens
that must be concatenated to produce the value of the string.
If the braced string was just {}
(that is, the string was empty),
the single TCL_TOKEN_TEXT token will have a size 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 commentStart, commentSize,
commandStart, and commandSize fields are not modified
by Tcl_ParseBraces.
After Tcl_ParseQuotedString returns,
the array of tokens pointed to by the tokenPtr field of the
Tcl_Parse structure depends on the contents of the quoted string.
It will consist of one or more TCL_TOKEN_TEXT, TCL_TOKEN_BS,
TCL_TOKEN_COMMAND, and TCL_TOKEN_VARIABLE sub-tokens.
The array always contains at least one token;
for example, if the argument start is empty,
the array returned consists of a single TCL_TOKEN_TEXT token
with a zero size field.
Only the token information in the Tcl_Parse structure
is modified: the commentStart, commentSize,
commandStart, and commandSize fields are not modified.
After Tcl_ParseVarName returns, the first token pointed to by
the tokenPtr field of the
Tcl_Parse structure always has type TCL_TOKEN_VARIABLE. 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 size field of the first token.
As in Tcl_ParseExpr,
only the token information in the Tcl_Parse structure
is modified by Tcl_ParseVarName:
the commentStart, commentSize,
commandStart, and commandSize fields are not modified.
All of the character pointers in the
Tcl_Parse and Tcl_Token structures refer
to characters in the start argument passed to
Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces,
Tcl_ParseQuotedString, and Tcl_ParseVarName.
There are additional fields in the Tcl_Parse structure after the
numTokens field, but these are for the private use of
Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces,
Tcl_ParseQuotedString, and Tcl_ParseVarName; they should not be
referenced by code outside of these procedures.
The result of Tcl_EvalTokens is an unshared value with a reference count
of 1; the caller of that function should call Tcl_DecrRefCount on the
result value to dispose of it. (The equivalent with
Tcl_EvalTokenStandard is just the interpreter result, which can be
retrieved with Tcl_GetObjResult.)
backslash substitution, braces, command, expression, parse, token, variable substitution
Copyright © 1997 Sun Microsystems, Inc.