#include <tcl.h> int Tcl_SplitList(interp, list, argcPtr, argvPtr) char * Tcl_Merge(argc, argv) int Tcl_ScanElement(src, flagsPtr) int Tcl_ConvertElement(src, dst, flags)
Then you should eventually free the storage with a call like the following:int argc, code; char *string; char **argv; ... code = Tcl_SplitList(interp, string, &argc, &argv);
Tcl_Free((char *) argv);
Tcl_SplitList normally returns TCL_OK, which means the list was successfully parsed. If there was a syntax error in list, then TCL_ERROR is returned and interp->result will point to an error message describing the problem (if interp was not NULL). If TCL_ERROR is returned then no memory is allocated and *argvPtr is not modified.
Tcl_Merge is the inverse of Tcl_SplitList: it takes a collection of strings given by argc and argv and generates a result string that has proper list structure. This means that commands like index may be used to extract the original elements again. In addition, if the result of Tcl_Merge is passed to Tcl_Eval, it will be parsed into argc words whose values will be the same as the argv strings passed to Tcl_Merge. Tcl_Merge will modify the list elements with braces and/or backslashes in order to produce proper Tcl list structure. The result string is dynamically allocated using Tcl_Alloc; the caller must eventually release the space using Tcl_Free.
If the result of Tcl_Merge is passed to Tcl_SplitList, the elements returned by Tcl_SplitList will be identical to those passed into Tcl_Merge. However, the converse is not true: if Tcl_SplitList is passed a given string, and the resulting argc and argv are passed to Tcl_Merge, the resulting string may not be the same as the original string passed to Tcl_SplitList. This is because Tcl_Merge may use backslashes and braces differently than the original string.
Tcl_ScanElement and Tcl_ConvertElement are the procedures that do all of the real work of Tcl_Merge. Tcl_ScanElement scans its src argument and determines how to use backslashes and braces when converting it to a list element. It returns an overestimate of the number of characters required to represent src as a list element, and it stores information in *flagsPtr that is needed by Tcl_ConvertElement.
Tcl_ConvertElement is a companion procedure to Tcl_ScanElement. It does the actual work of converting a string to a list element. Its flags argument must be the same as the value returned by Tcl_ScanElement. Tcl_ConvertElement writes a proper list element to memory starting at *dst and returns a count of the total number of characters written, which will be no more than the result returned by Tcl_ScanElement. Tcl_ConvertElement writes out only the actual list element without any leading or trailing spaces: it is up to the caller to include spaces between adjacent list elements.
Tcl_ConvertElement uses one of two different approaches to handle the special characters in src. Wherever possible, it handles special characters by surrounding the string with braces. This produces clean-looking output, but can't be used in some situations, such as when src contains unmatched braces. In these situations, Tcl_ConvertElement handles special characters by generating backslash sequences for them. The caller may insist on the second approach by OR-ing the flag value returned by Tcl_ScanElement with TCL_DONT_USE_BRACES. Although this will produce an uglier result, it is useful in some special situations, such as when Tcl_ConvertElement is being used to generate a portion of an argument for a Tcl command. In this case, surrounding src with curly braces would cause the command not to be parsed correctly.
Copyright © 1989-1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.