通讯编程

开发平台：
Visual C++

ParseCmd.3：源码内容
							'"
'" 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.
'" 
'" RCS: @(#) $Id: ParseCmd.3,v 1.10.2.2 2005/09/15 23:21:37 msofer Exp $
'" 
.so man.macros
.TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
.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_ParseCommandfR(fIinterp, string, numBytes, nested, parsePtrfR)
.sp
int
fBTcl_ParseExprfR(fIinterp, string, numBytes, parsePtrfR)
.sp
int
fBTcl_ParseBracesfR(fIinterp, string, numBytes, parsePtr, append, termPtrfR)
.sp
int
fBTcl_ParseQuotedStringfR(fIinterp, string, numBytes, parsePtr, append, termPtrfR)
.sp
int
fBTcl_ParseVarNamefR(fIinterp, string, numBytes, parsePtr, appendfR)
.sp
CONST char *
fBTcl_ParseVarfR(fIinterp, string, termPtrfR)
.sp
fBTcl_FreeParsefR(fIusedParsePtrfR)
.sp
Tcl_Obj *
fBTcl_EvalTokensfR(fIinterp, tokenPtr, numTokensfR)
.sp
int
fBTcl_EvalTokensStandardfR(fIinterp, tokenPtr, numTokensfR)
.SH ARGUMENTS
.AS Tcl_Interp *usedParsePtr
.AP Tcl_Interp *interp out
For procedures other than fBTcl_FreeParsefR, fBTcl_EvalTokensfR
and fBTcl_EvalTokensStandardfR, used only for error reporting;
if NULL, then no error messages are left after errors.
For fBTcl_EvalTokensfR and fBTcl_EvalTokensStandardfR,
determines the context for evaluating the
script and also is used for error reporting; must not be NULL.
.AP "CONST char" *string in
Pointer to first character in string to parse.
.AP int numBytes in
Number of bytes in fIstringfR, not including any terminating null
character.  If less than 0 then the script consists of all characters
in fIstringfR 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*parsePtrfR already contains valid tokens; the new
tokens should be appended to those already present.  Zero means that
fI*parsePtrfR 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 fIappendfR is non-zero in a call to
fBTcl_ParseBracesfR, fBTcl_ParseQuotedStringfR,
or fBTcl_ParseVarNamefR.
.AP "CONST char" **termPtr out
If not NULL, points to a location where
fBTcl_ParseBracesfR, fBTcl_ParseQuotedStringfR, and
fBTcl_ParseVarfR 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_ParseCommandfR, fBTcl_ParseExprfR, fBTcl_ParseVarNamefR, 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 fIparsePtrfR
with a collection of tokens describing the information that was parsed.
The procedures normally return fBTCL_OKfR.
However, if an error occurs then they return fBTCL_ERRORfR,
leave an error message in fIinterp'sfR result
(if fIinterpfR is not NULL),
and leave nothing in fIparsePtrfR.
.PP
fBTcl_ParseCommandfR 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_ParseCommandfR returns fBTCL_OKfR and fills in the
structure pointed to by fIparsePtrfR with information about the
structure of the command (see below for details).
If an error occurred in parsing the command then
fBTCL_ERRORfR is returned, an error message is left in fIinterpfR's
result, and no information is left at fI*parsePtrfR.
.PP
fBTcl_ParseExprfR parses Tcl expressions.
Given a pointer to a script containing an expression,
fBTcl_ParseExprfR parses the expression.
If the expression was parsed successfully,
fBTcl_ParseExprfR returns fBTCL_OKfR and fills in the
structure pointed to by fIparsePtrfR with information about the
structure of the expression (see below for details).
If an error occurred in parsing the command then
fBTCL_ERRORfR is returned, an error message is left in fIinterpfR's
result, and no information is left at fI*parsePtrfR.
.PP
fBTcl_ParseBracesfR parses a string or command argument
enclosed in braces such as
fB{hello}fR or fB{string \t with \t tabs}fR
from the beginning of its argument fIstringfR.
The first character of fIstringfR must be fB{fR. 
If the braced string was parsed successfully,
fBTcl_ParseBracesfR returns fBTCL_OKfR,
fills in the structure pointed to by fIparsePtrfR
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*termPtrfR.
If an error occurs while parsing the string
then fBTCL_ERRORfR is returned,
an error message is left in fIinterpfR's result,
and no information is left at fI*parsePtrfR or fI*termPtrfR.
.PP
fBTcl_ParseQuotedStringfR parses a double-quoted string such as
fB"sum is [expr $a+$b]"fR
from the beginning of the argument fIstringfR.
The first character of fIstringfR must be fB"fR. 
If the double-quoted string was parsed successfully,
fBTcl_ParseQuotedStringfR returns fBTCL_OKfR,
fills in the structure pointed to by fIparsePtrfR
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*termPtrfR.
If an error occurs while parsing the string
then fBTCL_ERRORfR is returned,
an error message is left in fIinterpfR's result,
and no information is left at fI*parsePtrfR or fI*termPtrfR.
.PP
fBTcl_ParseVarNamefR parses a Tcl variable reference such as
fB$abcfR or fB$x([expr $index + 1])fR from the beginning of its
fIstringfR argument.
The first character of fIstringfR must be fB$fR. 
If a variable name was parsed successfully, fBTcl_ParseVarNamefR
returns fBTCL_OKfR and fills in the structure pointed to by
fIparsePtrfR with information about the structure of the variable name
(see below for details).  If an error
occurs while parsing the command then fBTCL_ERRORfR is returned, an
error message is left in fIinterpfR's result (if fIinterpfR isn't
NULL), and no information is left at fI*parsePtrfR.
.PP
fBTcl_ParseVarfR parse a Tcl variable reference such as fB$abcfR
or fB$x([expr $index + 1])fR from the beginning of its fIstringfR
argument.  The first character of fIstringfR must be fB$fR.  If
the variable name is parsed successfully, fBTcl_ParseVarfR 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
fIinterpfR's result.
.PP
The information left at fI*parsePtrfR
by fBTcl_ParseCommandfR, fBTcl_ParseExprfR, fBTcl_ParseBracesfR,
fBTcl_ParseQuotedStringfR, and fBTcl_ParseVarNamefR
may include dynamically allocated memory.
If these five parsing procedures return fBTCL_OKfR
then the caller must invoke fBTcl_FreeParsefR to release
the storage at fI*parsePtrfR.
These procedures ignore any existing information in
fI*parsePtrfR (unless fIappendfR is non-zero),
so if repeated calls are being made to any of them
then fBTcl_FreeParsefR must be invoked once after each call.
.PP
fBTcl_EvalTokensStandardfR 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_EvalTokensStandardfR performs the
substitutions requested by the tokens and concatenates the
resulting values. 
The return value from fBTcl_EvalTokensStandardfR is a Tcl completion
code with one of the values fBTCL_OKfR, fBTCL_ERRORfR,
fBTCL_RETURNfR, fBTCL_BREAKfR, or fBTCL_CONTINUEfR, or possibly
some other integer value originating in an extension.
In addition, a result value or error message is left in fIinterpfR's
result; it can be retrieved using fBTcl_GetObjResultfR.
.PP
fBTcl_EvalTokensfR differs from fBTcl_EvalTokensStandardfR 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 fBTcl_DecrRefCountfR 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 fIinterpfR's result. The use
of fBTcl_EvalTokensfR is deprecated.
.SH "TCL_PARSE STRUCTURE"
.PP
fBTcl_ParseCommandfR, fBTcl_ParseExprfR, fBTcl_ParseBracesfR,
fBTcl_ParseQuotedStringfR, and fBTcl_ParseVarNamefR
return parse information in two data structures, Tcl_Parse and Tcl_Token:
.CS
typedef struct Tcl_Parse {
	CONST char *fIcommentStartfR;
	int fIcommentSizefR;
	CONST char *fIcommandStartfR;
	int fIcommandSizefR;
	int fInumWordsfR;
	Tcl_Token *fItokenPtrfR;
	int fInumTokensfR;
	...
} Tcl_Parse;
typedef struct Tcl_Token {
    int fItypefR;
    CONST char *fIstartfR;
    int fIsizefR;
    int fInumComponentsfR;
} Tcl_Token;
.CE
.PP
The first five fields of a Tcl_Parse structure
are filled in only by fBTcl_ParseCommandfR.
These fields are not used by the other parsing procedures.
.PP
fBTcl_ParseCommandfR 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 fIcommentStartfR field points to the fB#fR character that begins
the first comment and fIcommentSizefR 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, fIcommentSizefR is 0.
fBTcl_ParseCommandfR also sets the fIcommandStartfR field
to point to the first character of the first
word in the command (skipping any comments and leading space) and 
fIcommandSizefR gives the total number of bytes in the command,
including the character pointed to by fIcommandStartfR up to and
including the newline, close bracket, or semicolon character that
terminates the command.  The fInumWordsfR field gives the
total number of words in the command.
.PP
All parsing procedures set the remaining fields,
fItokenPtrfR and fInumTokensfR.
The fItokenPtrfR field points to the first in an array of Tcl_Token
structures that describe the components of the entity being parsed.
The fInumTokensfR field gives the total number of tokens
present in the array.
Each token contains four fields.
The fItypefR field selects one of several token types
that are described below.  The fIstartfR field
points to the first character in the token and the fIsizefR field
gives the total number of characters in the token.  Some token types,
such as fBTCL_TOKEN_WORDfR and fBTCL_TOKEN_VARIABLEfR, consist of
several component tokens, which immediately follow the parent token;
the fInumComponentsfR field describes how many of these there are.
The fItypefR field has one of the following values:
.TP 20
fBTCL_TOKEN_WORDfR
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 fInumComponentsfR field counts the total
number of sub-tokens that make up the word, including sub-tokens
of fBTCL_TOKEN_VARIABLEfR and fBTCL_TOKEN_BSfR tokens.
.TP
fBTCL_TOKEN_SIMPLE_WORDfR
This token has the same meaning as fBTCL_TOKEN_WORDfR, except that
the word is guaranteed to consist of a single fBTCL_TOKEN_TEXTfR
sub-token.  The fInumComponentsfR field is always 1.
.TP
fBTCL_TOKEN_TEXTfR
The token describes a range of literal text that is part of a word.
The fInumComponentsfR field is always 0.
.TP
fBTCL_TOKEN_BSfR
The token describes a backslash sequence such as fBenfR or fBe0xa3fR.
The fInumComponentsfR field is always 0.
.TP
fBTCL_TOKEN_COMMANDfR
The token describes a command whose result result must be substituted into
the word.  The token includes the square brackets that surround the
command.  The fInumComponentsfR field is always 0 (the nested command
is not parsed; call fBTcl_ParseCommandfR recursively if you want to
see its tokens).
.TP
fBTCL_TOKEN_VARIABLEfR
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 fInumComponentsfR  is 1 then the variable is a
scalar and the next token is a fBTCL_TOKEN_TEXTfR token that gives the
variable name.  If fInumComponentsfR is greater than 1 then the
variable is an array: the first sub-token is a fBTCL_TOKEN_TEXTfR
token giving the array name and the remaining sub-tokens are
fBTCL_TOKEN_TEXTfR, fBTCL_TOKEN_BSfR, fBTCL_TOKEN_COMMANDfR, and
fBTCL_TOKEN_VARIABLEfR tokens that must be concatenated to produce the
array index. The fInumComponentsfR field includes nested sub-tokens
that are part of fBTCL_TOKEN_VARIABLEfR tokens in the array index.
.TP
fBTCL_TOKEN_SUB_EXPRfR
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_EXPRfR token
is a fBTCL_TOKEN_OPERATORfR 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_OPERATORfR token.
Each operand is described by a fBTCL_TOKEN_SUB_EXPRfR token.
Otherwise, the subexpression is a value described by
one of the token types fBTCL_TOKEN_WORDfR, fBTCL_TOKEN_TEXTfR,
fBTCL_TOKEN_BSfR, fBTCL_TOKEN_COMMANDfR, 
fBTCL_TOKEN_VARIABLEfR, and fBTCL_TOKEN_SUB_EXPRfR.
The fInumComponentsfR field
counts the total number of sub-tokens that make up the subexpression;
this includes the sub-tokens for any nested fBTCL_TOKEN_SUB_EXPRfR tokens.
.TP
fBTCL_TOKEN_OPERATORfR
The token describes one operator of an expression
such as fB&&fR or fBhypotfR.
An fBTCL_TOKEN_OPERATORfR token is always preceded by a
fBTCL_TOKEN_SUB_EXPRfR token
that describes the operator and its operands;
the fBTCL_TOKEN_SUB_EXPRfR token's fInumComponentsfR field
can be used to determine the number of operands.
A binary operator such as fB*fR
is followed by two fBTCL_TOKEN_SUB_EXPRfR tokens
that describe its operands.
A unary operator like fB-fR
is followed by a single fBTCL_TOKEN_SUB_EXPRfR token
for its operand.
If the operator is a math function such as fBlog10fR,
the fBTCL_TOKEN_OPERATORfR token will give its name and
the following fBTCL_TOKEN_SUB_EXPRfR tokens will describe
its operands;
if there are no operands (as with fBrandfR),
no fBTCL_TOKEN_SUB_EXPRfR tokens follow.
There is one trinary operator, fB?fR,
that appears in if-then-else subexpressions
such as fIxfB?fIyfB:fIzfR;
in this case, the fB?fR fBTCL_TOKEN_OPERATORfR token
is followed by three fBTCL_TOKEN_SUB_EXPRfR tokens for the operands
fIxfR, fIyfR, and fIzfR.
The fInumComponentsfR field for a fBTCL_TOKEN_OPERATORfR token
is always 0.
.PP
After fBTcl_ParseCommandfR returns, the first token pointed to by
the fItokenPtrfR field of the
Tcl_Parse structure always has type fBTCL_TOKEN_WORDfR or
fBTCL_TOKEN_SIMPLE_WORDfR.  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_WORDfR or fBTCL_TOKEN_SIMPLE_WORDfR
token for the second word, followed by sub-tokens for that
word, and so on until all fInumWordsfR have been accounted
for.
.PP
After fBTcl_ParseExprfR returns, the first token pointed to by
the fItokenPtrfR field of the
Tcl_Parse structure always has type fBTCL_TOKEN_SUB_EXPRfR.
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 fIcommentStartfR, fIcommentSizefR,
fIcommandStartfR, and fIcommandSizefR fields are not modified
by fBTcl_ParseExprfR.
.PP
After fBTcl_ParseBracesfR returns,
the array of tokens pointed to by the fItokenPtrfR field of the
Tcl_Parse structure will contain a single fBTCL_TOKEN_TEXTfR 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_TEXTfR or fBTCL_TOKEN_BSfR 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_TEXTfR token will have a fIsizefR 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 fIcommentStartfR, fIcommentSizefR,
fIcommandStartfR, and fIcommandSizefR fields are not modified
by fBTcl_ParseBracesfR.
.PP
After fBTcl_ParseQuotedStringfR returns,
the array of tokens pointed to by the fItokenPtrfR field of the
Tcl_Parse structure depends on the contents of the quoted string.
It will consist of one or more fBTCL_TOKEN_TEXTfR, fBTCL_TOKEN_BSfR,
fBTCL_TOKEN_COMMANDfR, and fBTCL_TOKEN_VARIABLEfR sub-tokens.
The array always contains at least one token;
for example, if the argument fIstringfR is empty,
the array returned consists of a single fBTCL_TOKEN_TEXTfR token
with a zero fIsizefR field.
Only the token information in the Tcl_Parse structure
is modified: the fIcommentStartfR, fIcommentSizefR,
fIcommandStartfR, and fIcommandSizefR fields are not modified.
.PP
After fBTcl_ParseVarNamefR returns, the first token pointed to by
the fItokenPtrfR field of the
Tcl_Parse structure always has type fBTCL_TOKEN_VARIABLEfR.  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 fIsizefR field of the first token.
As in fBTcl_ParseExprfR,
only the token information in the Tcl_Parse structure
is modified by fBTcl_ParseVarNamefR:
the fIcommentStartfR, fIcommentSizefR,
fIcommandStartfR, and fIcommandSizefR fields are not modified.
.PP
All of the character pointers in the
Tcl_Parse and Tcl_Token structures refer
to characters in the fIstringfR argument passed to
fBTcl_ParseCommandfR, fBTcl_ParseExprfR, fBTcl_ParseBracesfR,
fBTcl_ParseQuotedStringfR, and fBTcl_ParseVarNamefR.
.PP
There are additional fields in the Tcl_Parse structure after the
fInumTokensfR field, but these are for the private use of
fBTcl_ParseCommandfR, fBTcl_ParseExprfR, fBTcl_ParseBracesfR,
fBTcl_ParseQuotedStringfR, and fBTcl_ParseVarNamefR; they should not be
referenced by code outside of these procedures.
.SH KEYWORDS
backslash substitution, braces, command, expression, parse, token, variable substitution

						