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

NAME

8       Tcl_SplitList,    Tcl_Merge,    Tcl_ScanElement,    Tcl_ConvertElement,
9       Tcl_ScanCountedElement,  Tcl_ConvertCountedElement  -  manipulate   Tcl
10       lists
11

SYNOPSIS

13       #include <tcl.h>
14
15       int
16       Tcl_SplitList(interp, list, argcPtr, argvPtr)
17
18       char *
19       Tcl_Merge(argc, argv)
20
21       int
22       Tcl_ScanElement(src, flagsPtr)
23
24       int
25       Tcl_ScanCountedElement(src, length, flagsPtr)
26
27       int
28       Tcl_ConvertElement(src, dst, flags)
29
30       int
31       Tcl_ConvertCountedElement(src, length, dst, flags)
32

ARGUMENTS

34       Tcl_Interp *interp (out)                   Interpreter to use for error
35                                                  reporting.  If NULL, then no
36                                                  error message is left.
37
38       char *list (in)                            Pointer  to  a  string  with
39                                                  proper list structure.
40
41       int *argcPtr (out)                         Filled  in  with  number  of
42                                                  elements in list.
43
44       const char ***argvPtr (out)                *argvPtr  will  be filled in
45                                                  with the address of an array
46                                                  of  pointers  to the strings
47                                                  that are the extracted  ele‐
48                                                  ments  of  list.  There will
49                                                  be *argcPtr valid entries in
50                                                  the  array,  followed  by  a
51                                                  NULL entry.
52
53       int argc (in)                              Number of elements in argv.
54
55       const char *const *argv (in)               Array of  strings  to  merge
56                                                  together into a single list.
57                                                  Each string  will  become  a
58                                                  separate   element   of  the
59                                                  list.
60
61       const char *src (in)                       String that is to become  an
62                                                  element of a list.
63
64       int *flagsPtr (in)                         Pointer  to  word to fill in
65                                                  with information about  src.
66                                                  The  value of *flagsPtr must
67                                                  be passed to Tcl_ConvertEle‐
68                                                  ment.
69
70       int length (in)                            Number  of  bytes  in string
71                                                  src.
72
73       char *dst (in)                             Place to copy converted list
74                                                  element.     Must    contain
75                                                  enough  characters  to  hold
76                                                  converted string.
77
78       int flags (in)                             Information  about src. Must
79                                                  be value returned by  previ‐
80                                                  ous call to Tcl_ScanElement,
81                                                  possibly     OR-ed      with
82                                                  TCL_DONT_USE_BRACES.
83_________________________________________________________________
84
85

DESCRIPTION

87       These  procedures  may be used to disassemble and reassemble Tcl lists.
88       Tcl_SplitList breaks a list up into its constituent elements, returning
89       an  array of pointers to the elements using argcPtr and argvPtr.  While
90       extracting the arguments, Tcl_SplitList obeys the usual rules for back‐
91       slash  substitutions  and  braces.   The  area  of memory pointed to by
92       *argvPtr is dynamically allocated;  in addition to the array of  point‐
93       ers, it also holds copies of all the list elements.  It is the caller's
94       responsibility to free up all of this storage.   For  example,  suppose
95       that you have called Tcl_SplitList with the following code:
96              int argc, code;
97              char *string;
98              char **argv;
99              ...
100              code = Tcl_SplitList(interp, string, &argc, &argv);
101       Then  you  should eventually free the storage with a call like the fol‐
102       lowing:
103              Tcl_Free((char *) argv);
104
105       Tcl_SplitList normally returns TCL_OK, which means the  list  was  suc‐
106       cessfully  parsed.  If there was a syntax error in list, then TCL_ERROR
107       is returned and the interpreter's result will point to an error message
108       describing  the  problem  (if  interp  was  not NULL).  If TCL_ERROR is
109       returned then no memory is allocated and *argvPtr is not modified.
110
111       Tcl_Merge is the inverse of Tcl_SplitList:  it takes  a  collection  of
112       strings  given  by argc and argv and generates a result string that has
113       proper list structure.  This means that commands like index may be used
114       to  extract the original elements again.  In addition, if the result of
115       Tcl_Merge is passed to Tcl_Eval, it will  be  parsed  into  argc  words
116       whose  values will be the same as the argv strings passed to Tcl_Merge.
117       Tcl_Merge will modify the list elements with braces and/or  backslashes
118       in  order  to  produce proper Tcl list structure.  The result string is
119       dynamically allocated using  Tcl_Alloc;   the  caller  must  eventually
120       release the space using Tcl_Free.
121
122       If  the  result  of  Tcl_Merge is passed to Tcl_SplitList, the elements
123       returned by Tcl_SplitList  will  be  identical  to  those  passed  into
124       Tcl_Merge.   However,  the  converse  is not true:  if Tcl_SplitList is
125       passed a given string, and the resulting argc and argv  are  passed  to
126       Tcl_Merge,  the  resulting  string  may not be the same as the original
127       string passed to Tcl_SplitList.  This  is  because  Tcl_Merge  may  use
128       backslashes and braces differently than the original string.
129
130       Tcl_ScanElement  and  Tcl_ConvertElement are the procedures that do all
131       of the real work of Tcl_Merge.  Tcl_ScanElement scans its src  argument
132       and  determines how to use backslashes and braces when converting it to
133       a list element.  It returns an overestimate of the number of characters
134       required  to represent src as a list element, and it stores information
135       in *flagsPtr that is needed by Tcl_ConvertElement.
136
137       Tcl_ConvertElement is a companion  procedure  to  Tcl_ScanElement.   It
138       does  the  actual  work  of converting a string to a list element.  Its
139       flags argument must be the same as the value returned  by  Tcl_ScanEle‐
140       ment.  Tcl_ConvertElement writes a proper list element to memory start‐
141       ing at *dst and returns a count of the total number of characters writ‐
142       ten, which will be no more than the result returned by Tcl_ScanElement.
143       Tcl_ConvertElement writes out only the actual list element without  any
144       leading  or  trailing  spaces: it is up to the caller to include spaces
145       between adjacent list elements.
146
147       Tcl_ConvertElement uses one of two different approaches to  handle  the
148       special characters in src.  Wherever possible, it handles special char‐
149       acters by surrounding the string with  braces.   This  produces  clean-
150       looking output, but cannot be used in some situations, such as when src
151       contains unmatched braces.   In  these  situations,  Tcl_ConvertElement
152       handles  special characters by generating backslash sequences for them.
153       The caller may insist on the second approach by OR-ing the  flag  value
154       returned  by  Tcl_ScanElement  with TCL_DONT_USE_BRACES.  Although this
155       will produce an uglier result, it is useful in some special situations,
156       such  as when Tcl_ConvertElement is being used to generate a portion of
157       an argument for a Tcl command.  In  this  case,  surrounding  src  with
158       curly braces would cause the command not to be parsed correctly.
159
160       By  default,  Tcl_ConvertElement  will  use quoting in its output to be │
161       sure the first character of an element is not the hash character (“#”.) │
162       This  is to be sure the first element of any list passed to eval is not │
163       mis-parsed as the beginning of a comment.  When a list element  is  not │
164       the  first  element of a list, this quoting is not necessary.  When the │
165       caller can be sure that the element is not the first element of a list, │
166       it can disable quoting of the leading hash character by OR-ing the flag │
167       value returned by Tcl_ScanElement with TCL_DONT_QUOTE_HASH.
168
169       Tcl_ScanCountedElement and Tcl_ConvertCountedElement are  the  same  as
170       Tcl_ScanElement and Tcl_ConvertElement, except the length of string src
171       is specified by the length argument, and the string may contain  embed‐
172       ded nulls.
173
174

KEYWORDS

176       backslash, convert, element, list, merge, split, strings
177
178
179
180Tcl                                   8.0                     Tcl_SplitList(3)
Impressum