Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

       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  er-
					      ror reporting; must not be NULL.

       const char *start (in)		      Pointer  to  first  character in
					      string to	parse.

       int numBytes (in)		      Number of	 bytes	in  string  to
					      parse,  not including any	termi-
					      nating null character.  If  less
					      than  0 then the script consists
					      of  all	characters   following
					      start up to the first null char-
					      acter.

       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  ap-
					      pended 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 er-
       ror occurs then they return TCL_ERROR, leave an error  message  in  in-
       terp'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 er-
       ror occurred in parsing the command then	TCL_ERROR is returned, an  er-
       ror  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 ex-
       pression	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	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	infor-
       mation 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	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 start argument.   The
       first character of start	must be	$.  If a variable name was parsed suc-
       cessfully, 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	 pars-
       ing the command then TCL_ERROR is returned, an error message is left in
       interp's	result (if interp is not 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	 start	argument.   The	 first
       character  of start 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 in-
       clude 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 be-
       ing 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  re-
       quested	by  the	tokens and concatenates	the resulting values.  The re-
       turn 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 value returned as result  has  been	 incremented,  so  the
       caller must invoke Tcl_DecrRefCount when	it is finished with the	value.
       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 ar-
       ray.   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_TO-
       KEN_WORD	 and  TCL_TOKEN_VARIABLE, consist of several component tokens,
       which immediately follow	the parent token; the numComponents field  de-
       scribes	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_EXPAND_WORD
			   This	 token has the same meaning as TCL_TOKEN_WORD,
			   except that the command parser notes	this word  be-
			   gan	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, in-
			   cluding 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 to-
			   ken is a TCL_TOKEN_TEXT token that gives the	 vari-
			   able	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_TO-
			   KEN_BS,  TCL_TOKEN_COMMAND,	and TCL_TOKEN_VARIABLE
			   tokens that must be concatenated to produce the ar-
			   ray	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 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  de-
			   scribe  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	opera-
			   tor	has no operands, the subexpression consists of
			   just	the TCL_TOKEN_OPERATOR token.  Each operand is
			   described  by  a  TCL_TOKEN_SUB_EXPR	token.	Other-
			   wise, 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_VARI-
			   ABLE,  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.	 A 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 bi-
			   nary	operator such as * is followed by two  TCL_TO-
			   KEN_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 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_TO-
			   KEN_OPERATOR	token is always	0.

       After Tcl_ParseCommand returns, the first token pointed to by  the  to-
       kenPtr  field of	the Tcl_Parse structure	always has type	TCL_TOKEN_WORD
       or TCL_TOKEN_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 token 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
       tokenPtr	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 to-
       kens 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  en-
       sures  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 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 argu-
       ment  start  is	empty, the array returned consists of a	single TCL_TO-
       KEN_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  to-
       kenPtr field of the Tcl_Parse structure always has type TCL_TOKEN_VARI-
       ABLE.  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_Parse-
       VarName:	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	characters in the start	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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | TCL_PARSE STRUCTURE | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_EvalTokens.tcl86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help