Tcl_ParseCommand man page on OpenMandriva

Man page or keyword search:  
man Server   8135 pages
apropos Keyword Search (all sections)
Output format
OpenMandriva 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, 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
					      error  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
					      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 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
       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  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
       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_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 $, 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.	 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
			   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 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  num‐
       Words 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  start  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 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)
[top]

List of man pages available for OpenMandriva

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