1Tcl_ParseCommand(3)         Tcl Library Procedures         Tcl_ParseCommand(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_ParseCommand,   Tcl_ParseExpr,   Tcl_ParseBraces,  Tcl_ParseQuoted‐
9       String, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse,  Tcl_EvalTokens,
10       Tcl_EvalTokensStandard - parse Tcl scripts and expressions
11

SYNOPSIS

13       #include <tcl.h>
14
15       int
16       Tcl_ParseCommand(interp, start, numBytes, nested, parsePtr)
17
18       int
19       Tcl_ParseExpr(interp, start, numBytes, parsePtr)
20
21       int
22       Tcl_ParseBraces(interp, start, numBytes, parsePtr, append, termPtr)
23
24       int
25       Tcl_ParseQuotedString(interp, start, numBytes, parsePtr, append, termPtr)
26
27       int
28       Tcl_ParseVarName(interp, start, numBytes, parsePtr, append)
29
30       const char *
31       Tcl_ParseVar(interp, start, termPtr)
32
33       Tcl_FreeParse(usedParsePtr)
34
35       Tcl_Obj *
36       Tcl_EvalTokens(interp, tokenPtr, numTokens)
37
38       int
39       Tcl_EvalTokensStandard(interp, tokenPtr, numTokens)
40

ARGUMENTS

42       Tcl_Interp *interp (out)               For    procedures   other   than
43                                              Tcl_FreeParse,    Tcl_EvalTokens
44                                              and Tcl_EvalTokensStandard, used
45                                              only  for  error  reporting;  if
46                                              NULL, then no error messages are
47                                              left    after    errors.     For
48                                              Tcl_EvalTokens  and  Tcl_EvalTo‐
49                                              kensStandard,   determines   the
50                                              context   for   evaluating   the
51                                              script  and  also  is  used  for
52                                              error  reporting;  must  not  be
53                                              NULL.
54
55       const char *start (in)                 Pointer to  first  character  in
56                                              string to parse.
57
58       int numBytes (in)                      Number  of  bytes  in  string to
59                                              parse, not including any  termi‐
60                                              nating  null character.  If less
61                                              than 0 then the script  consists
62                                              of   all   characters  following
63                                              start up to the first null char‐
64                                              acter.
65
66       int nested (in)                        Non-zero  means  that the script
67                                              is part of a  command  substitu‐
68                                              tion   so   an   unquoted  close
69                                              bracket should be treated  as  a
70                                              command  terminator.   If  zero,
71                                              close brackets have  no  special
72                                              meaning.
73
74       int append (in)                        Non-zero  means  that  *parsePtr
75                                              already contains  valid  tokens;
76                                              the   new   tokens   should   be
77                                              appended   to   those    already
78                                              present.     Zero   means   that
79                                              *parsePtr is uninitialized;  any
80                                              information  in  it  is ignored.
81                                              This argument is normally 0.
82
83       Tcl_Parse *parsePtr (out)              Points to structure to  fill  in
84                                              with   information   about   the
85                                              parsed   command,    expression,
86                                              variable  name, etc.  Any previ‐
87                                              ous information in  this  struc‐
88                                              ture  is  ignored, unless append
89                                              is  non-zero  in   a   call   to
90                                              Tcl_ParseBraces,  Tcl_ParseQuot‐
91                                              edString, or Tcl_ParseVarName.
92
93       const char **termPtr (out)             If not NULL, points to  a  loca‐
94                                              tion    where   Tcl_ParseBraces,
95                                              Tcl_ParseQuotedString,       and
96                                              Tcl_ParseVar    will   store   a
97                                              pointer to  the  character  just
98                                              after  the terminating character
99                                              (the close-brace, the last char‐
100                                              acter  of  the variable name, or
101                                              the close-quote  (respectively))
102                                              if the parse was successful.
103
104       Tcl_Parse *usedParsePtr (in)           Points  to  structure  that  was
105                                              filled in by a previous call  to
106                                              Tcl_ParseCommand, Tcl_ParseExpr,
107                                              Tcl_ParseVarName, etc.
108______________________________________________________________________________
109

DESCRIPTION

111       These procedures parse Tcl commands or portions of Tcl commands such as
112       expressions or references to variables.  Each procedure takes a pointer
113       to a script (or portion thereof) and fills in the structure pointed  to
114       by parsePtr with a collection of tokens describing the information that
115       was parsed.  The procedures normally return  TCL_OK.   However,  if  an
116       error  occurs  then  they  return  TCL_ERROR, leave an error message in
117       interp's result (if interp is not NULL), and leave nothing in parsePtr.
118
119       Tcl_ParseCommand is a procedure  that  parses  Tcl  scripts.   Given  a
120       pointer  to  a script, it parses the first command from the script.  If
121       the command was parsed successfully,  Tcl_ParseCommand  returns  TCL_OK
122       and  fills  in  the  structure  pointed to by parsePtr with information
123       about the structure of the command (see  below  for  details).   If  an
124       error  occurred  in  parsing the command then TCL_ERROR is returned, an
125       error message is left in interp's result, and no information is left at
126       *parsePtr.
127
128       Tcl_ParseExpr parses Tcl expressions.  Given a pointer to a script con‐
129       taining an expression, Tcl_ParseExpr parses  the  expression.   If  the
130       expression  was  parsed  successfully, Tcl_ParseExpr returns TCL_OK and
131       fills in the structure pointed to by parsePtr  with  information  about
132       the  structure  of the expression (see below for details).  If an error
133       occurred in parsing the command then TCL_ERROR is  returned,  an  error
134       message  is  left  in  interp's  result,  and no information is left at
135       *parsePtr.
136
137       Tcl_ParseBraces parses a string or command argument enclosed in  braces
138       such  as  {hello} or {string \t with \t tabs} from the beginning of its
139       argument start.  The first character of start must be {.  If the braced
140       string  was  parsed successfully, Tcl_ParseBraces returns TCL_OK, fills
141       in the structure pointed to by  parsePtr  with  information  about  the
142       structure  of  the string (see below for details), and stores a pointer
143       to the character just after the terminating } in the location given  by
144       *termPtr.   If  an error occurs while parsing the string then TCL_ERROR
145       is returned, an error message is left in interp's result, and no infor‐
146       mation is left at *parsePtr or *termPtr.
147
148       Tcl_ParseQuotedString  parses  a  double-quoted  string such as "sum is
149       [expr {$a+$b}]" from the beginning of the argument  start.   The  first
150       character  of  start must be ".  If the double-quoted string was parsed
151       successfully, Tcl_ParseQuotedString returns TCL_OK, fills in the struc‐
152       ture pointed to by parsePtr with information about the structure of the
153       string (see below for details), and stores a pointer to  the  character
154       just  after the terminating " in the location given by *termPtr.  If an
155       error occurs while parsing the string then TCL_ERROR  is  returned,  an
156       error message is left in interp's result, and no information is left at
157       *parsePtr or *termPtr.
158
159       Tcl_ParseVarName parses a  Tcl  variable  reference  such  as  $abc  or
160       $x([expr  {$index + 1}]) from the beginning of its start argument.  The
161       first character of start must be $.  If a variable name was parsed suc‐
162       cessfully,  Tcl_ParseVarName  returns TCL_OK and fills in the structure
163       pointed to by parsePtr with information  about  the  structure  of  the
164       variable  name (see below for details).  If an error occurs while pars‐
165       ing the command then TCL_ERROR is returned, an error message is left in
166       interp's  result (if interp is not NULL), and no information is left at
167       *parsePtr.
168
169       Tcl_ParseVar parse a Tcl variable reference such as  $abc  or  $x([expr
170       {$index  +  1}])  from  the beginning of its start argument.  The first
171       character of start must be $.  If the variable name is parsed  success‐
172       fully,  Tcl_ParseVar returns a pointer to the string value of the vari‐
173       able.  If an error occurs while parsing, then NULL is returned  and  an
174       error message is left in interp's result.
175
176       The  information  left at *parsePtr by Tcl_ParseCommand, Tcl_ParseExpr,
177       Tcl_ParseBraces,  Tcl_ParseQuotedString,   and   Tcl_ParseVarName   may
178       include dynamically allocated memory.  If these five parsing procedures
179       return TCL_OK then the caller must invoke Tcl_FreeParse to release  the
180       storage at *parsePtr.  These procedures ignore any existing information
181       in *parsePtr (unless append is non-zero),  so  if  repeated  calls  are
182       being made to any of them then Tcl_FreeParse must be invoked once after
183       each call.
184
185       Tcl_EvalTokensStandard evaluates a sequence  of  parse  tokens  from  a
186       Tcl_Parse structure.  The tokens typically consist of all the tokens in
187       a word or all the tokens that make up the index for a reference  to  an
188       array  variable.   Tcl_EvalTokensStandard  performs  the  substitutions
189       requested by the tokens and concatenates  the  resulting  values.   The
190       return  value from Tcl_EvalTokensStandard is a Tcl completion code with
191       one of the values TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CON‐
192       TINUE,  or  possibly  some other integer value originating in an exten‐
193       sion.  In addition, a result value or error message is left in interp's
194       result; it can be retrieved using Tcl_GetObjResult.
195
196       Tcl_EvalTokens  differs  from Tcl_EvalTokensStandard only in the return
197       convention used: it returns the result in a new Tcl_Obj.  The reference
198       count  of  the  value  returned  as result has been incremented, so the
199       caller must invoke Tcl_DecrRefCount when it is finished with the value.
200       If an error or other exception occurs while evaluating the tokens (such
201       as a reference to a non-existent variable) then  the  return  value  is
202       NULL  and  an  error  message  is  left  in interp's result. The use of
203       Tcl_EvalTokens is deprecated.
204

TCL_PARSE STRUCTURE

206       Tcl_ParseCommand,  Tcl_ParseExpr,   Tcl_ParseBraces,   Tcl_ParseQuoted‐
207       String,  and  Tcl_ParseVarName  return  parse  information  in two data
208       structures, Tcl_Parse and Tcl_Token:
209
210              typedef struct Tcl_Parse {
211                  const char *commentStart;
212                  int commentSize;
213                  const char *commandStart;
214                  int commandSize;
215                  int numWords;
216                  Tcl_Token *tokenPtr;
217                  int numTokens;
218                  ...
219              } Tcl_Parse;
220
221              typedef struct Tcl_Token {
222                  int type;
223                  const char *start;
224                  int size;
225                  int numComponents;
226              } Tcl_Token;
227
228       The first five fields of a Tcl_Parse structure are filled  in  only  by
229       Tcl_ParseCommand.   These fields are not used by the other parsing pro‐
230       cedures.
231
232       Tcl_ParseCommand fills in a Tcl_Parse structure with  information  that
233       describes  one  Tcl  command and any comments that precede the command.
234       If there are comments, the commentStart field points to the # character
235       that  begins  the first comment and commentSize indicates the number of
236       bytes in all of the comments preceding the command, including the  new‐
237       line character that terminates the last comment.  If the command is not
238       preceded by any comments, commentSize is 0.  Tcl_ParseCommand also sets
239       the  commandStart  field  to  point to the first character of the first
240       word in the command (skipping any comments and leading space) and  com‐
241       mandSize  gives the total number of bytes in the command, including the
242       character pointed to by commandStart up to and including  the  newline,
243       close bracket, or semicolon character that terminates the command.  The
244       numWords field gives the total number of words in the command.
245
246       All parsing procedures set the remaining fields,  tokenPtr  and  numTo‐
247       kens.   The tokenPtr field points to the first in an array of Tcl_Token
248       structures that describe the components of  the  entity  being  parsed.
249       The  numTokens  field  gives  the total number of tokens present in the
250       array.  Each token contains four fields.  The type field selects one of
251       several  token  types that are described below.  The start field points
252       to the first character in the token and the size field gives the  total
253       number  of  characters  in  the  token.   Some  token  types,  such  as
254       TCL_TOKEN_WORD and TCL_TOKEN_VARIABLE,  consist  of  several  component
255       tokens,  which  immediately  follow the parent token; the numComponents
256       field describes how many of these there are.  The type field has one of
257       the following values:
258
259       TCL_TOKEN_WORD      This  token ordinarily describes one word of a com‐
260                           mand but it may also describe a  quoted  or  braced
261                           string  in  an  expression.   The token describes a
262                           component of the script that is the result of  con‐
263                           catenating  together  a  sequence of subcomponents,
264                           each described by a separate subtoken.   The  token
265                           starts  with  the  first non-blank character of the
266                           component (which may  be  a  double-quote  or  open
267                           brace) and includes all characters in the component
268                           up to but not including the space, semicolon, close
269                           bracket,  close  quote,  or close brace that termi‐
270                           nates  the  component.   The  numComponents   field
271                           counts  the total number of sub-tokens that make up
272                           the word, including sub-tokens  of  TCL_TOKEN_VARI‐
273                           ABLE and TCL_TOKEN_BS tokens.
274
275       TCL_TOKEN_SIMPLE_WORD
276                           This  token has the same meaning as TCL_TOKEN_WORD,
277                           except that the word is guaranteed to consist of  a
278                           single TCL_TOKEN_TEXT sub-token.  The numComponents
279                           field is always 1.
280
281       TCL_TOKEN_EXPAND_WORD
282                           This token has the same meaning as  TCL_TOKEN_WORD,
283                           except  that  the  command  parser  notes this word
284                           began with the  expansion  prefix  {*},  indicating
285                           that  after  substitution,  the  list value of this
286                           word should be expanded to form multiple  arguments
287                           in command evaluation.  This token type can only be
288                           created by Tcl_ParseCommand.
289
290       TCL_TOKEN_TEXT      The token describes a range of literal text that is
291                           part  of a word.  The numComponents field is always
292                           0.
293
294       TCL_TOKEN_BS        The token describes a backslash sequence such as \n
295                           or \0xa3.  The numComponents field is always 0.
296
297       TCL_TOKEN_COMMAND   The  token describes a command whose result must be
298                           substituted into the word.  The token includes  the
299                           square  brackets  that  surround  the command.  The
300                           numComponents field is always 0 (the nested command
301                           is not parsed; call Tcl_ParseCommand recursively if
302                           you want to see its tokens).
303
304       TCL_TOKEN_VARIABLE  The  token  describes  a   variable   substitution,
305                           including the $, variable name, and array index (if
306                           there is one) up through the close parenthesis that
307                           terminates  the  index.   This token is followed by
308                           one or more additional  tokens  that  describe  the
309                           variable  name  and  array index.  If numComponents
310                           is 1 then the variable is a  scalar  and  the  next
311                           token  is  a  TCL_TOKEN_TEXT  token  that gives the
312                           variable name.  If numComponents is greater than  1
313                           then  the variable is an array: the first sub-token
314                           is a TCL_TOKEN_TEXT token giving the array name and
315                           the   remaining   sub-tokens   are  TCL_TOKEN_TEXT,
316                           TCL_TOKEN_BS,        TCL_TOKEN_COMMAND,         and
317                           TCL_TOKEN_VARIABLE tokens that must be concatenated
318                           to produce the array index. The numComponents field
319                           includes   nested   sub-tokens  that  are  part  of
320                           TCL_TOKEN_VARIABLE tokens in the array index.
321
322       TCL_TOKEN_SUB_EXPR  The token describes one subexpression of an expres‐
323                           sion  (or  an  entire expression).  A subexpression
324                           may consist of a value such as an integer  literal,
325                           variable  substitution, or parenthesized subexpres‐
326                           sion; it may also consist of an  operator  and  its
327                           operands.   The  token  starts  with the first non-
328                           blank character of the subexpression up to but  not
329                           including the space, brace, close-paren, or bracket
330                           that terminates the subexpression.  This  token  is
331                           followed  by  one  or  more  additional tokens that
332                           describe the subexpression.  If the first sub-token
333                           after    the    TCL_TOKEN_SUB_EXPR   token   is   a
334                           TCL_TOKEN_OPERATOR token,  the  subexpression  con‐
335                           sists  of  an  operator and its token operands.  If
336                           the operator has  no  operands,  the  subexpression
337                           consists  of  just  the  TCL_TOKEN_OPERATOR  token.
338                           Each operand is described by  a  TCL_TOKEN_SUB_EXPR
339                           token.   Otherwise,  the  subexpression  is a value
340                           described by one of the token types TCL_TOKEN_WORD,
341                           TCL_TOKEN_TEXT,   TCL_TOKEN_BS,  TCL_TOKEN_COMMAND,
342                           TCL_TOKEN_VARIABLE,  and  TCL_TOKEN_SUB_EXPR.   The
343                           numComponents field counts the total number of sub-
344                           tokens  that  make  up  the   subexpression;   this
345                           includes    the    sub-tokens    for   any   nested
346                           TCL_TOKEN_SUB_EXPR tokens.
347
348       TCL_TOKEN_OPERATOR  The token describes one operator of  an  expression
349                           such as && or hypot.  A TCL_TOKEN_OPERATOR token is
350                           always preceded by a TCL_TOKEN_SUB_EXPR token  that
351                           describes   the  operator  and  its  operands;  the
352                           TCL_TOKEN_SUB_EXPR token's numComponents field  can
353                           be  used  to  determine  the number of operands.  A
354                           binary operator  such  as  *  is  followed  by  two
355                           TCL_TOKEN_SUB_EXPR  tokens  that describe its oper‐
356                           ands.  A unary operator like -  is  followed  by  a
357                           single  TCL_TOKEN_SUB_EXPR  token  for its operand.
358                           If the operator is a math function such  as  log10,
359                           the TCL_TOKEN_OPERATOR token will give its name and
360                           the  following   TCL_TOKEN_SUB_EXPR   tokens   will
361                           describe its operands; if there are no operands (as
362                           with rand), no  TCL_TOKEN_SUB_EXPR  tokens  follow.
363                           There  is  one trinary operator, ?, that appears in
364                           if-then-else subexpressions such as x?y:z; in  this
365                           case, the ? TCL_TOKEN_OPERATOR token is followed by
366                           three TCL_TOKEN_SUB_EXPR tokens for the operands x,
367                           y,   and   z.    The   numComponents  field  for  a
368                           TCL_TOKEN_OPERATOR token is always 0.
369
370       After Tcl_ParseCommand returns, the  first  token  pointed  to  by  the
371       tokenPtr   field   of   the   Tcl_Parse   structure   always  has  type
372       TCL_TOKEN_WORD or TCL_TOKEN_SIMPLE_WORD or  TCL_TOKEN_EXPAND_WORD.   It
373       is  followed by the sub-tokens that must be concatenated to produce the
374       value  of  that  word.   The  next  token  is  the  TCL_TOKEN_WORD   or
375       TCL_TOKEN_SIMPLE_WORD  of  TCL_TOKEN_EXPAND_WORD  token  for the second
376       word, followed by sub-tokens for that word, and so on  until  all  num‐
377       Words have been accounted for.
378
379       After Tcl_ParseExpr returns, the first token pointed to by the tokenPtr
380       field of the Tcl_Parse structure always  has  type  TCL_TOKEN_SUB_EXPR.
381       It  is followed by the sub-tokens that must be evaluated to produce the
382       value of the expression.  Only the token information in  the  Tcl_Parse
383       structure is modified: the commentStart, commentSize, commandStart, and
384       commandSize fields are not modified by Tcl_ParseExpr.
385
386       After Tcl_ParseBraces returns, the array of tokens pointed  to  by  the
387       tokenPtr  field  of  the  Tcl_Parse  structure  will  contain  a single
388       TCL_TOKEN_TEXT token if the braced string does not  contain  any  back‐
389       slash-newlines.   If  the  string  does contain backslash-newlines, the
390       array of tokens will contain one or more TCL_TOKEN_TEXT or TCL_TOKEN_BS
391       sub-tokens  that  must  be  concatenated  to  produce  the value of the
392       string.  If the braced string was just {}  (that  is,  the  string  was
393       empty), the single TCL_TOKEN_TEXT token will have a size field contain‐
394       ing zero; this ensures that at least one token appears to describe  the
395       braced  string.   Only the token information in the Tcl_Parse structure
396       is modified: the commentStart, commentSize, commandStart, and  command‐
397       Size fields are not modified by Tcl_ParseBraces.
398
399       After  Tcl_ParseQuotedString returns, the array of tokens pointed to by
400       the tokenPtr field of the Tcl_Parse structure depends on  the  contents
401       of  the  quoted string.  It will consist of one or more TCL_TOKEN_TEXT,
402       TCL_TOKEN_BS,  TCL_TOKEN_COMMAND,  and  TCL_TOKEN_VARIABLE  sub-tokens.
403       The array always contains at least one token; for example, if the argu‐
404       ment  start  is  empty,  the  array  returned  consists  of  a   single
405       TCL_TOKEN_TEXT  token  with a zero size field.  Only the token informa‐
406       tion in the Tcl_Parse structure is modified: the commentStart, comment‐
407       Size, commandStart, and commandSize fields are not modified.
408
409       After  Tcl_ParseVarName  returns,  the  first  token  pointed to by the
410       tokenPtr  field  of   the   Tcl_Parse   structure   always   has   type
411       TCL_TOKEN_VARIABLE.   It is followed by the sub-tokens that make up the
412       variable name as described above.  The total  length  of  the  variable
413       name  is  contained  in  the  size  field  of  the  first token.  As in
414       Tcl_ParseExpr, only the token information in the Tcl_Parse structure is
415       modified  by  Tcl_ParseVarName: the commentStart, commentSize, command‐
416       Start, and commandSize fields are not modified.
417
418       All of the character pointers in the Tcl_Parse and Tcl_Token structures
419       refer  to  characters in the start argument passed to Tcl_ParseCommand,
420       Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString,  and  Tcl_Parse‐
421       VarName.
422
423       There are additional fields in the Tcl_Parse structure after the numTo‐
424       kens field, but these are for  the  private  use  of  Tcl_ParseCommand,
425       Tcl_ParseExpr,  Tcl_ParseBraces,  Tcl_ParseQuotedString, and Tcl_Parse‐
426       VarName; they should not be referenced by code outside of these  proce‐
427       dures.
428

KEYWORDS

430       backslash  substitution,  braces,  command,  expression,  parse, token,
431       variable substitution
432
433
434
435Tcl                                   8.3                  Tcl_ParseCommand(3)
Impressum