Tcl_ParseCommand - String, 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_ParseCommand(3tcl) Tcl Library Procedures Tcl_ParseCommand(3tcl)
______________________________________________________________________________
NAME
Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuoted-
String, 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
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_EvalTo-
kensStandard, 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 termi-
nating null character. If less
than 0 then the script consists
of all characters following
start up to the first null char-
acter.
int nested (in) Non-zero means that the script
is part of a command substitu-
tion 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 previ-
ous information in this struc-
ture is ignored, unless append
is non-zero in a call to
Tcl_ParseBraces, Tcl_ParseQuot-
edString, or Tcl_ParseVarName.
const char **termPtr (out) If not NULL, points to a loca-
tion 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 char-
acter 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.
______________________________________________________________________________
DESCRIPTION
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 con-
taining 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 infor-
mation 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 struc-
ture 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 suc-
cessfully, 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 pars-
ing 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 success-
fully, Tcl_ParseVar returns a pointer to the string value of the vari-
able. 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_CON-
TINUE, or possibly some other integer value originating in an exten-
sion. 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_PARSE STRUCTURE
Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuoted-
String, 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 pro-
cedures.
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 new-
line 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 com-
mandSize 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 numTo-
kens. 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 com-
mand 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 con-
catenating 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 termi-
nates the component. The numComponents field
counts the total number of sub-tokens that make up
the word, including sub-tokens of TCL_TOKEN_VARI-
ABLE 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 expres-
sion (or an entire expression). A subexpression
may consist of a value such as an integer literal,
variable substitution, or parenthesized subexpres-
sion; 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 con-
sists 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 oper-
ands. 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 num-
Words 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 back-
slash-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 contain-
ing 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 command-
Size 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 argu-
ment start is empty, the array returned consists of a single
TCL_TOKEN_TEXT token with a zero size field. Only the token informa-
tion in the Tcl_Parse structure is modified: the commentStart, comment-
Size, 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, command-
Start, 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_Parse-
VarName.
There are additional fields in the Tcl_Parse structure after the numTo-
kens field, but these are for the private use of Tcl_ParseCommand,
Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_Parse-
VarName; they should not be referenced by code outside of these proce-
dures.
KEYWORDS
backslash substitution, braces, command, expression, parse, token,
variable substitution
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/tcl-8 |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://prdownloads.sourceforge.net/tcl/tcl-
core8.6.7-src.tar.gz.
Further information about this software can be found on the open source
community website at https://www.tcl.tk/.
Tcl 8.3 Tcl_ParseCommand(3tcl)