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
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 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‐
103 lowing:
104 Tcl_Free((char *) argv);
106 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
111 returned then no memory is allocated and *argvPtr is not modified.
112 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
122 release the space using Tcl_Free.
123 If the result of Tcl_Merge is passed to Tcl_SplitList, the elements
125 returned 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 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 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 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 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 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
177 Tcl_ListObjGetElements(3)
178
180 backslash, convert, element, list, merge, split, strings
181Tcl 8.0 Tcl_SplitList(3)