Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for tcl_evaltokens (opendarwin section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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, 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_Eval-
					      Tokens 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   *string	    (in)      Pointer to first character in string to parse.

       int	    numBytes	    (in)      Number of bytes in string, not including any termi-
					      nating 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
					      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 struc-
					      ture 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_Parse-
					      Braces,	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 previ-
					      ous  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 expres-
       sion, Tcl_ParseCommand parses the expression.  If the expression was parsed  successfully,
       Tcl_ParseExpr returns TCL_OK and fills in the structure pointed to by parsePtr with infor-
       mation 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 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 string.  The first character of string must be ".  If	the  dou-
       ble-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 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 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 vari-
       able 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 mes-
       sage 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 sub-
       stitutions 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_ParseVar-
       Name 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  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 char-
       acter  pointed to by commandStart up to and including the newline, close bracket, or semi-
       colon 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 concatenat-
			   ing 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, semi-
			   colon, 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_VARI-
			   ABLE 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_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 substitution, including the $, variable
			   name, and array index (if there is one) up through the close parenthe-
			   sis	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	numCompo-
			   nents  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  remain-
			   ing	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 inte-
			   ger 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 subex-
			   pression consists of an operator and its token operands.  If the oper-
			   ator  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.
			   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  deter-
			   mine  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  subexpres-
			   sions  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, fol-
       lowed 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 com-
       mentStart,  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
       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  com-
       mentStart, 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  charac-
       ters  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

Tcl					       8.3			      Tcl_ParseCommand(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:52 PM.