Windows PowerShell command on Get-command Tcl

Manual Pages for UNIX Operating System command usage for man Tcl_ParseQuotedString

Tcl Library Procedures Tcl_ParseCommand(3TCL)

_________________________________________________________________

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_EvalTokensStandard,

used only for error reporting; if NULL,

then no error mes-

sages are left after errors. For

Tcl_EvalTokens and

Tcl_EvalTokensStandard,

determines the con-

text for evaluating the script and also Tcl Last change: 8.3 1

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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 including any terminating null character. If less than 0 then the script consists of all characters in string up to the first null character.

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 com-

mand terminator. If zero, close brackets

have no special mean-

ing.

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 *par-

sePtr is uninitial-

ized; 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, variable

name, etc. Any pre-

vious information in this structure is ignored, unless Tcl Last change: 8.3 2

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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 (respec-

tively)) 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 com-

mands 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 informa-

tion is left at *parsePtr. Tcl Last change: 8.3 3

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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 informa-

tion 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 suc-

cessfully, 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 mes-

sage 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

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 terminating " in the loca-

tion 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 *par-

sePtr 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_ParseVarName

returns TCL_OK and fills in the structure pointed to by par-

sePtr 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 argu-

ment. 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 Tcl Last change: 8.3 4

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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 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 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;

Tcl Last change: 8.3 5

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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 infor-

mation that describes one Tcl command and any comments that

precede the command. If there are comments, the com-

mentStart 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 ter-

minates 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 expres-

sion. The token describes a component

of the script that is the result of con-

catenating together a sequence of sub-

components, each described by a separate subtoken. The token starts with the

first non-blank character of the

Tcl Last change: 8.3 6

Tcl Library Procedures Tcl_ParseCommand(3TCL)

component (which may be a double-quote

or open brace) and includes all charac-

ters 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 numCom-

ponents field is always 1.

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 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 substitu-

tion, including the $, variable name,

and array index (if there is one) up

through the close parenthesis that ter-

minates the index. This token is fol-

lowed 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 Last change: 8.3 7

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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 subex-

pression; it may also consist of an operator and its operands. The token

starts with the first non-blank charac-

ter of the subexpression up to but not

including the space, brace, close-paren,

or bracket that terminates the subex-

pression. 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 con-

sists 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. An

TCL_TOKEN_OPERATOR token is always pre-

ceded by a TCL_TOKEN_SUB_EXPR token that

describes the operator and its operands;

the TCL_TOKEN_SUB_EXPR token's numCom-

ponents field can be used to determine

the number of operands. A binary opera-

tor such as * is followed by two

TCL_TOKEN_SUB_EXPR tokens that describe

its operands. A unary operator like -

Tcl Last change: 8.3 8

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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. It is fol-

lowed 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 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 com-

mentStart, commentSize, commandStart, and commandSize fields

are not modified by Tcl_ParseBraces.

Tcl Last change: 8.3 9

Tcl Library Procedures Tcl_ParseCommand(3TCL)

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 con-

sist 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 modi-

fied: the commentStart, commentSize, commandStart, and com-

mandSize 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, com-

mandStart, 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_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

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes: Tcl Last change: 8.3 10

Tcl Library Procedures Tcl_ParseCommand(3TCL)

_______________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE|

|____________________|__________________|_

| Availability | runtime/tcl-8 |

|____________________|__________________|_

| Interface Stability| Uncommitted |

|____________________|_________________|

NOTES Source for Tcl is available on http://opensolaris.org. Tcl Last change: 8.3 11