Tcl_EvalTokens man page on QNX

Man page or keyword search:  
man Server   4347 pages
apropos Keyword Search (all sections)
Output format
QNX logo
[printable version]

Tcl_ParseCommand(3)	    Tcl Library Procedures	   Tcl_ParseCommand(3)

______________________________________________________________________________

NAME
       Tcl_ParseCommand,   Tcl_ParseExpr,   Tcl_ParseBraces,  Tcl_ParseQuoted‐
       String, 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_EvalTokens
					      and Tcl_EvalTokensStandard, used
					      only  for	 error	reporting;  if
					      NULL, then no error messages are
					      left    after    errors.	   For
					      Tcl_EvalTokens  and  Tcl_EvalTo‐
					      kensStandard,   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  terminating  null
					      character.   If less than 0 then
					      the script consists of all char‐
					      acters 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
					      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	previ‐
					      ous  information	in this struc‐
					      ture is ignored,	unless	append
					      is   non-zero   in   a  call  to
					      Tcl_ParseBraces,	Tcl_ParseQuot‐
					      edString, or Tcl_ParseVarName.

       CONST char   **termPtr	    (out)     If  not  NULL, points to a loca‐
					      tion   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 char‐
					      acter 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_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 con‐
       taining	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  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 double-quoted string was	parsed
       successfully, Tcl_ParseQuotedString returns TCL_OK, fills in the struc‐
       ture 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	struc‐
       ture pointed to by parsePtr with information about the structure of the
       variable name (see below for details).  If an error occurs while	 pars‐
       ing 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 success‐
       fully, Tcl_ParseVar returns a pointer to the string value of the	 vari‐
       able.   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_CON‐
       TINUE, or possibly 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 deprecated.

TCL_PARSE STRUCTURE
       Tcl_ParseCommand,   Tcl_ParseExpr,   Tcl_ParseBraces,  Tcl_ParseQuoted‐
       String, 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  pro‐
       cedures.

       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 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 new‐
       line 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 com‐
       mandSize 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 numTo‐
       kens.  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  com‐
			   mand	 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 con‐
			   catenating 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	termi‐
			   nates   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 com‐
			   mand.   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 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_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 expres‐
			   sion (or an entire  expression).   A	 subexpression
			   may	consist of a value such as an integer literal,
			   variable substitution, or parenthesized  subexpres‐
			   sion;  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  subexpression con‐
			   sists of an operator and its	 token	operands.   If
			   the	operator  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 determine the  number  of	 operands.   A
			   binary  operator  such  as  *  is  followed	by two
			   TCL_TOKEN_SUB_EXPR tokens that describe  its	 oper‐
			   ands.   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   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 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 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	 back‐
       slash-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 contain‐
       ing 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  command‐
       Size 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 argu‐
       ment  string  is	 empty,	 the  array  returned  consists	 of  a	single
       TCL_TOKEN_TEXT  token  with a zero size field.  Only the token informa‐
       tion in the Tcl_Parse structure is modified: the commentStart, comment‐
       Size, 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, command‐
       Start, 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_Parse‐
       VarName.

       There are additional fields in the Tcl_Parse structure after the numTo‐
       kens field, but these are for  the  private  use	 of  Tcl_ParseCommand,
       Tcl_ParseExpr,  Tcl_ParseBraces,	 Tcl_ParseQuotedString, and Tcl_Parse‐
       VarName; they should not be referenced by code outside of these	proce‐
       dures.

KEYWORDS
       backslash  substitution,	 braces,  command,  expression,	 parse, token,
       variable substitution

Tcl				      8.3		   Tcl_ParseCommand(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server QNX

List of man pages available for QNX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net