Tcl_ParseCommand(3) Tcl Library Procedures Tcl_ParseCommand(3)

____________________________________________________________________________

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

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.
____________________________________________________________________________

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
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 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 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_PARSE STRUCTURE
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.

KEYWORDS

backslash substitution, braces, command, expression, parse, token,
variable substitution

Tcl 8.3 Tcl_ParseCommand(3)