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
35 error reporting. If NULL,
36 then no error message is
37 left.
38 char *list (in) Pointer to a string with
40 proper list structure.
41 int *argcPtr (out) Filled in with number of
43 elements in list.
44 CONST char ***argvPtr (out) *argvPtr will be filled in
46 with the address of an
47 array of pointers to the
48 strings that are the
49 extracted elements of list.
50 There will be *argcPtr
51 valid entries in the array,
52 followed by a NULL entry.
53 int argc (in) Number of elements in argv.
55 CONST char * CONST *argv (in) Array of strings to merge
57 together into a single
58 list. Each string will
59 become a separate element
60 of the list.
61 CONST char *src (in) String that is to become an
63 element of a list.
64 int *flagsPtr (in) Pointer to word to fill in
66 with information about src.
67 The value of *flagsPtr must
68 be passed to Tcl_Con‐
69 vertElement.
70 int length (in) Number of bytes in string
72 src.
73 char *dst (in) Place to copy converted
75 list element. Must contain
76 enough characters to hold
77 converted string.
78 int flags (in) Information about src. Must
80 be value returned by previ‐
81 ous call to Tcl_ScanEle‐
82 ment, possibly OR-ed with
83 TCL_DONT_USE_BRACES.
84_________________________________________________________________
85
88 These procedures may be used to disassemble and reassemble Tcl lists.
89 Tcl_SplitList breaks a list up into its constituent elements, returning
90 an array of pointers to the elements using argcPtr and argvPtr. While
91 extracting the arguments, Tcl_SplitList obeys the usual rules for back‐
92 slash substitutions and braces. The area of memory pointed to by
93 *argvPtr is dynamically allocated; in addition to the array of point‐
94 ers, it also holds copies of all the list elements. It is the caller's
95 responsibility to free up all of this storage. For example, suppose
96 that you have called Tcl_SplitList with the following code:
97 int argc, code;
98 char *string;
99 char **argv;
100 ...
101 code = Tcl_SplitList(interp, string, &argc, &argv);
102 Then you should eventually free the storage with a call like the fol‐
103 lowing:
104 Tcl_Free((char *) argv);
105 Tcl_SplitList normally returns TCL_OK, which means the list was suc‐
107 cessfully parsed. If there was a syntax error in list, then TCL_ERROR
108 is returned and the interpreter's result will point to an error message
109 describing the problem (if interp was not NULL). If TCL_ERROR is
110 returned then no memory is allocated and *argvPtr is not modified.
111 Tcl_Merge is the inverse of Tcl_SplitList: it takes a collection of
113 strings given by argc and argv and generates a result string that has
114 proper list structure. This means that commands like index may be used
115 to extract the original elements again. In addition, if the result of
116 Tcl_Merge is passed to Tcl_Eval, it will be parsed into argc words
117 whose values will be the same as the argv strings passed to Tcl_Merge.
118 Tcl_Merge will modify the list elements with braces and/or backslashes
119 in order to produce proper Tcl list structure. The result string is
120 dynamically allocated using Tcl_Alloc; the caller must eventually
121 release the space using Tcl_Free.
122 If the result of Tcl_Merge is passed to Tcl_SplitList, the elements
124 returned by Tcl_SplitList will be identical to those passed into
125 Tcl_Merge. However, the converse is not true: if Tcl_SplitList is
126 passed a given string, and the resulting argc and argv are passed to
127 Tcl_Merge, the resulting string may not be the same as the original
128 string passed to Tcl_SplitList. This is because Tcl_Merge may use
129 backslashes and braces differently than the original string.
130 Tcl_ScanElement and Tcl_ConvertElement are the procedures that do all
132 of the real work of Tcl_Merge. Tcl_ScanElement scans its src argument
133 and determines how to use backslashes and braces when converting it to
134 a list element. It returns an overestimate of the number of characters
135 required to represent src as a list element, and it stores information
136 in *flagsPtr that is needed by Tcl_ConvertElement.
137 Tcl_ConvertElement is a companion procedure to Tcl_ScanElement. It
139 does the actual work of converting a string to a list element. Its
140 flags argument must be the same as the value returned by Tcl_ScanEle‐
141 ment. Tcl_ConvertElement writes a proper list element to memory start‐
142 ing at *dst and returns a count of the total number of characters writ‐
143 ten, which will be no more than the result returned by Tcl_ScanElement.
144 Tcl_ConvertElement writes out only the actual list element without any
145 leading or trailing spaces: it is up to the caller to include spaces
146 between adjacent list elements.
147 Tcl_ConvertElement uses one of two different approaches to handle the
149 special characters in src. Wherever possible, it handles special char‐
150 acters by surrounding the string with braces. This produces clean-
151 looking output, but can't be used in some situations, such as when src
152 contains unmatched braces. In these situations, Tcl_ConvertElement
153 handles special characters by generating backslash sequences for them.
154 The caller may insist on the second approach by OR-ing the flag value
155 returned by Tcl_ScanElement with TCL_DONT_USE_BRACES. Although this
156 will produce an uglier result, it is useful in some special situations,
157 such as when Tcl_ConvertElement is being used to generate a portion of
158 an argument for a Tcl command. In this case, surrounding src with
159 curly braces would cause the command not to be parsed correctly.
160 Tcl_ScanCountedElement and Tcl_ConvertCountedElement are the same as
162 Tcl_ScanElement and Tcl_ConvertElement, except the length of string src
163 is specified by the length argument, and the string may contain embed‐
164 ded nulls.
165
168 backslash, convert, element, list, merge, split, strings
169Tcl 8.0 Tcl_SplitList(3)