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

DESCRIPTION

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

TCL_PARSE STRUCTURE

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

KEYWORDS

427       backslash substitution,  braces,  command,  expression,  parse,  token,
428       variable substitution
429
430
431
432Tcl                                   8.3                  Tcl_ParseCommand(3)
Impressum