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       const char *list (in)                      Pointer  to  a  string  with
39                                                  proper list structure.
40
41       int *argcPtr (out)                         Filled in with number of el‐
42                                                  ements 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

DESCRIPTION

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

SEE ALSO

177       Tcl_ListObjGetElements(3)
178

KEYWORDS

180       backslash, convert, element, list, merge, split, strings
181
182
183
184Tcl                                   8.0                     Tcl_SplitList(3)
Impressum