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
110

DESCRIPTION

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

TCL_PARSE STRUCTURE

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

KEYWORDS

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