1Tcl_SplitList(3) Tcl Library Procedures Tcl_SplitList(3)
2______________________________________________________________________________
6
8 Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement,
9 Tcl_ScanCountedElement, Tcl_ConvertCountedElement - manipulate Tcl
10 lists
11
13 #include <tcl.h>
14 int
16 Tcl_SplitList(interp, list, argcPtr, argvPtr)
17 char *
19 Tcl_Merge(argc, argv)
20 int
22 Tcl_ScanElement(src, flagsPtr)
23 int
25 Tcl_ScanCountedElement(src, length, flagsPtr)
26 int
28 Tcl_ConvertElement(src, dst, flags)
29 int
31 Tcl_ConvertCountedElement(src, length, dst, flags)
32
34 Tcl_Interp *interp (out) Interpreter to use for error
35 reporting. If NULL, then no
36 error message is left.
37 char *list (in) Pointer to a string with
39 proper list structure.
40 int *argcPtr (out) Filled in with number of
42 elements in list.
43 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 int argc (in) Number of elements in argv.
54 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 const char *src (in) String that is to become an
62 element of a list.
63 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 int length (in) Number of bytes in string
71 src.
72 char *dst (in) Place to copy converted list
74 element. Must contain
75 enough characters to hold
76 converted string.
77 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
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 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 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 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 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 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 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 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 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
176 backslash, convert, element, list, merge, split, strings
177Tcl 8.0 Tcl_SplitList(3)