home | help 
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_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)

     int
     Tcl_EvalTokensStandard(interp, tokenPtr, numTokens)

ARGUMENTS
     Tcl_Interp *interp (out)		    For     procedures	   other    than
					    Tcl_FreeParse  and	 Tcl_EvalTokens-
					    Standard,  used  only  for error re-
					    porting; if NULL, then no error mes-
					    sages are left  after  errors.   For
					    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.

     Tcl_Size 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  al-
					    ready contains valid tokens; the new
					    tokens  should  be appended to those
					    already present.   Zero  means  that
					    *parsePtr  is uninitialized; any in-
					    formation in it  is  ignored.   This
					    argument is normally 0.

     Tcl_Parse *parsePtr (out)		    Points  to structure to fill in with
					    information about  the  parsed  com-
					    mand,   expression,  variable  name,
					    etc.  Any  previous  information  in
					    this  structure  is  ignored, unless
					    append is  non-zero  in  a	call  to
					    Tcl_ParseBraces,	Tcl_ParseQuoted-
					    String, or Tcl_ParseVarName.

     const char **termPtr (out) 	    If not NULL, points  to  a	location
					    where   Tcl_ParseBraces,  Tcl_Parse-
					    QuotedString, 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_ParseC-
					    ommand, Tcl_ParseExpr, Tcl_ParseVar-
					    Name, etc.
________________________________________________________________________________

DESCRIPTION
     These procedures parse Tcl commands or portions of Tcl commands such as ex-
     pressions	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  oc-
     curs  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 contain-
     ing 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  in-
     terp'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 re-
     sult, 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 charac-
     ter  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 be-
     low  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  in-
     terp is not NULL), and no information is left at *parsePtr.

     Tcl_ParseVar parses a Tcl variable reference such as $abc or $x([expr {$in-
     dex  +  1}]) from the beginning of its start argument.  The first character
     of start must be $.  If the variable name is parsed successfully,	Tcl_Par-
     seVar  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 us-
     ing Tcl_GetObjResult.

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 {
		const char *commentStart;
		Tcl_Size commentSize;
		const char *commandStart;
		Tcl_Size commandSize;
		Tcl_Size numWords;
		Tcl_Token *tokenPtr;
		Tcl_Size numTokens;
		...
	    } Tcl_Parse;

	    typedef struct {
		int type;
		const char *start;
		Tcl_Size size;
		Tcl_Size 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 proce-
     dures.

     Tcl_ParseCommand fills in a Tcl_Parse structure with information  that  de-
     scribes 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  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 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	concate-
	    nating  together  a  sequence  of subcomponents, each described by a
	    separate subtoken.	The token starts with the first non-blank  char-
	    acter  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-to-
	    kens 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 $,  vari-
	    able  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  ar-
	    ray  name  and  the remaining sub-tokens are TCL_TOKEN_TEXT, TCL_TO-
	    KEN_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  to-
	    kens 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 in-
	    teger literal, variable substitution,  or  parenthesized  subexpres-
	    sion;  it may also consist of an operator and its operands.  The to-
	    ken 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_TO-
	    KEN_OPERATOR token, the subexpression consists of  an  operator  and
	    its token operands.  If the operator has no operands, the subexpres-
	    sion consists of just the TCL_TOKEN_OPERATOR token.  Each operand is
	    described  by a TCL_TOKEN_SUB_EXPR token.  Otherwise, the subexpres-
	    sion 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 hy-
	    pot.  A TCL_TOKEN_OPERATOR token is always	preceded  by  a  TCL_TO-
	    KEN_SUB_EXPR token that describes the operator and its operands; the
	    TCL_TOKEN_SUB_EXPR token's numComponents field can be used to deter-
	    mine  the  number  of operands.  A binary operator such as * is fol-
	    lowed 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 fol-
	    lowing 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_OP-
	    ERATOR  token is followed by three TCL_TOKEN_SUB_EXPR tokens for the
	    operands x, y, and z.  The numComponents field for a TCL_TOKEN_OPER-
	    ATOR 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_TO-
     KEN_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  to-
     ken 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  to-
     kenPtr  field  of	the  Tcl_Parse	structure  will contain a single TCL_TO-
     KEN_TEXT token if the braced string does  not  contain  any  backslash-new-
     lines.   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_TO-
     KEN_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 in-
     formation in the Tcl_Parse structure is modified:	the  commentStart,  com-
     mentSize,	 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_TO-
     KEN_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  com-
     mentStart,  commentSize, commandStart, and commandSize fields are not modi-
     fied.

     All of the character pointers in the Tcl_Parse and Tcl_Token structures re-
     fer to  characters  in  the  start  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_Parse-
     Expr, 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)
home | help