Tcl_SplitList(3)     Tcl Library Procedures      Tcl_SplitList(3)



     Tcl_SplitList,          Tcl_Merge,          Tcl_ScanElement,
     Tcl_ConvertElement,                  Tcl_ScanCountedElement,
     Tcl_ConvertCountedElement - manipulate Tcl lists


     #include <tcl.h>

     Tcl_SplitList(interp, list, argcPtr, argvPtr)

     char *
     Tcl_Merge(argc, argv)

     Tcl_ScanElement(src, flagsPtr)

     Tcl_ScanCountedElement(src, length, flagsPtr)

     Tcl_ConvertElement(src, dst, flags)

     Tcl_ConvertCountedElement(src, length, dst, flags)


     Tcl_Interp *interp (out)                   Interpreter    to
                                                use   for   error
                                                reporting.     If
                                                NULL,   then   no
                                                error message  is

     char *list (in)                            Pointer   to    a
                                                string       with
                                                proper       list

     int *argcPtr (out)                         Filled  in   with
                                                number   of  ele-
                                                ments in list.

     const char ***argvPtr (out)                *argvPtr will  be
                                                filled   in  with
                                                the address of an
                                                array of pointers
                                                to  the   strings
                                                that    are   the

Tcl                     Last change: 8.0                        1

Tcl_SplitList(3)     Tcl Library Procedures      Tcl_SplitList(3)

                                                elements of list.
                                                There   will   be
                                                *argcPtr    valid
                                                entries  in   the
                                                array,   followed
                                                by a NULL entry.

     int argc (in)                              Number  of   ele-
                                                ments in argv.

     const char *const *argv (in)               Array of  strings
                                                to merge together
                                                into   a   single
                                                list.        Each
                                                string       will
                                                become a separate
                                                element  of   the

     const char *src (in)                       String that is to
                                                become an element
                                                of a list.

     int *flagsPtr (in)                         Pointer  to  word
                                                to  fill  in with
                                                information about
                                                src.   The  value
                                                of *flagsPtr must
                                                be    passed   to

     int length (in)                            Number  of  bytes
                                                in string src.

     char *dst (in)                             Place   to   copy
                                                converted    list
                                                element.     Must
                                                contain    enough
                                                characters     to
                                                hold    converted

     int flags (in)                             Information about
                                                src.    Must   be
                                                value returned by
                                                previous  call to
                                                possibly    OR-ed

Tcl                     Last change: 8.0                        2

Tcl_SplitList(3)     Tcl Library Procedures      Tcl_SplitList(3)


     These procedures may be used to disassemble  and  reassemble
     Tcl  lists.  Tcl_SplitList breaks a list up into its consti-
     tuent elements, returning an array of pointers to  the  ele-
     ments using argcPtr and argvPtr.  While extracting the argu-
     ments, Tcl_SplitList obeys the  usual  rules  for  backslash
     substitutions  and braces.  The area of memory pointed to by
     *argvPtr is dynamically allocated;  in addition to the array
     of  pointers, it also holds copies of all the list elements.
     It is the caller's responsibility to free  up  all  of  this
     storage.    For   example,  suppose  that  you  have  called
     Tcl_SplitList with the following code:
          int argc, code;
          char *string;
          char **argv;
          code = Tcl_SplitList(interp, string, &argc, &argv);
     Then you should eventually free the storage with a call like
     the following:
          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  the  interpreter's
     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  col-
     lection  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 result-
     ing 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

Tcl                     Last change: 8.0                        3

Tcl_SplitList(3)     Tcl Library Procedures      Tcl_SplitList(3)

     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 cannot 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.

     By default, Tcl_ConvertElement will use quoting in its  out-  |
     put  to be sure the first character of an element is not the  |
     hash character ("#".)  This is to be sure the first  element  |
     of  any  list passed to eval is not mis-parsed as the begin-  |
     ning of a comment.  When a list element  is  not  the  first  |
     element  of a list, this quoting is not necessary.  When the  |
     caller can be sure that the element is not the first element  |
     of  a list, it can disable quoting of the leading hash char-  |
     acter by OR-ing the flag value returned  by  Tcl_ScanElement  |

     Tcl_ScanCountedElement and Tcl_ConvertCountedElement are the
     same  as  Tcl_ScanElement and Tcl_ConvertElement, except the
     length of string src is specified by  the  length  argument,
     and the string may contain embedded nulls.

Tcl                     Last change: 8.0                        4

Tcl_SplitList(3)     Tcl Library Procedures      Tcl_SplitList(3)


     backslash, convert, element, list, merge, split, strings

Tcl                     Last change: 8.0                        5

Man(1) output converted with man2html