Index of Section 3 Manual Pages
| Interix / SUA | Tcl_ParseVarName.3 | Interix / SUA |
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
int
Tcl_ParseCommand(interp, string, numBytes, nested, parsePtr)
int
Tcl_ParseExpr(interp, string, numBytes, parsePtr)
int
Tcl_ParseBraces(interp, string, numBytes, parsePtr, append, termPtr)
int
Tcl_ParseQuotedString(interp, string, numBytes, parsePtr, append, termPtr)
int
Tcl_ParseVarName(interp, string, numBytes, parsePtr, append)
CONST char *
Tcl_ParseVar(interp, string, 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_EvalTokensStan-
dard, used only for
error reporting; if
NULL, then no error
messages are left
after errors. For
Tcl_EvalTokens and
Tcl_EvalTokensStan-
dard, determines
the context for
evaluating the
script and also is
used for error
reporting; must not
be NULL.
CONST char *string (in) Pointer to first
character in string
to parse.
int numBytes (in) Number of bytes in
string, not includ-
ing any terminating
null character. If
less than 0 then
the script consists
of all characters
in string up to the
first null charac-
ter.
int nested (in) Non-zero means that
the script is part
of a command sub-
stitution so an
unquoted close
bracket should be
treated as a com-
mand 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 unini-
tialized; any
information in it
is ignored. This
argument is nor-
mally 0.
Tcl_Parse *parsePtr (out) Points to structure
to fill in with
information about
the parsed command,
expression, vari-
able name, etc.
Any previous infor-
mation in this
structure is
ignored, unless
append is non-zero
in a call to
Tcl_ParseBraces,
Tcl_ParseQuoted-
String, or Tcl_Par-
seVarName.
CONST char **termPtr (out) If not NULL, points
to a location where
Tcl_ParseBraces,
Tcl_ParseQuoted-
String, and
Tcl_ParseVar will
store a pointer to
the character just
after the terminat-
ing character (the
close-brace, the
last character of
the variable name,
or the close-quote
(respectively)) if
the parse was suc-
cessful.
Tcl_Parse *usedParsePtr (in) Points to structure
that was filled in
by a previous call
to Tcl_ParseCom-
mand, Tcl_Parse-
Expr, Tcl_ParseVar-
Name, 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 struc-
ture 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 success-
fully, 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 string. The
first character of string must be {. If the braced string
was parsed successfully, Tcl_ParseBraces returns TCL_OK,
fills in the structure pointed to by parsePtr with infor-
mation 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 argu-
ment string. The first character of string 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 terminat-
ing " 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
string argument. The first character of string must be $.
If a variable name was parsed successfully, Tcl_ParseVar-
Name 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 isn't
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 string
argument. The first character of string 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 informa-
tion 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 pos-
sibly 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 object returned as
result has been incremented, so the caller must invoke
Tcl_DecrRefCount when it is finished with the object. 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 depre-
cated.
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 com-
ments 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 com-
mand, including the newline character that terminates the
last comment. If the command is not preceded by any com-
ments, 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 lead-
ing space) and commandSize gives the total number of bytes
in the command, including the character pointed to by com-
mandStart 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 com-
mand.
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 compo-
nents 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 numCompo-
nents 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 compo-
nent 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, includ-
ing 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 numCom-
ponents field is always 1.
TCL_TOKEN_TEXT The token describes a range of literal
text that is part of a word. The num-
Components 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 result must be substituted into
the word. The token includes the
square brackets that surround the com-
mand. The numComponents field is
always 0 (the nested command is not
parsed; call Tcl_ParseCommand recur-
sively if you want to see its tokens).
TCL_TOKEN_VARIABLE The token describes a variable substi-
tution, 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_VARI-
ABLE tokens that must be concatenated
to produce the array index. The num-
Components 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 expres-
sion). 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 subexpres-
sion. 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 subex-
pression consists of an operator and
its token operands. If the operator
has no operands, the subexpression
consists of just the TCL_TOKEN_OPERA-
TOR token. Each operand is described
by a TCL_TOKEN_SUB_EXPR token. Other-
wise, 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. An
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 numCom-
ponents 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. 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 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 expres-
sion. Only the token information in the Tcl_Parse struc-
ture is modified: the commentStart, commentSize, command-
Start, 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 struc-
ture 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 string 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 modi-
fied 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 string
argument passed to Tcl_ParseCommand, Tcl_ParseExpr,
Tcl_ParseBraces, Tcl_ParseQuotedString, and Tcl_ParseVar-
Name.
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)