ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tcl_SplitList

Tcl_SplitList(3)            Tcl Library Procedures            Tcl_SplitList(3)



______________________________________________________________________________

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

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_SplitList(interp, list, argcPtr, argvPtr)

       char *
       Tcl_Merge(argc, argv)

       int
       Tcl_ScanElement(src, flagsPtr)

       int
       Tcl_ScanCountedElement(src, length, flagsPtr)

       int
       Tcl_ConvertElement(src, dst, flags)

       int
       Tcl_ConvertCountedElement(src, length, dst, flags)

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

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

       int          *argcPtr     (out)     Filled in with number  of  elements
                                           in list.

       char         ***argvPtr   (out)     *argvPtr will be filled in with the
                                           address of an array of pointers  to
                                           the  strings that are the extracted
                                           elements of list.   There  will  be
                                           *argcPtr   valid   entries  in  the
                                           array, followed by a NULL entry.

       int          argc         (in)      Number of elements in argv.

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

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

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

       char         *dst         (in)      Place  to  copy converted list ele-
                                           ment.  Must contain enough  charac-
                                           ters to hold converted string.

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


DESCRIPTION
       These procedures may be used to disassemble and reassemble  Tcl  lists.
       Tcl_SplitList breaks a list up into its constituent elements, returning
       an array of pointers to the elements using argcPtr and argvPtr.   While
       extracting the arguments, Tcl_SplitList obeys the usual rules for back-
       slash substitutions and braces.  The  area  of  memory  pointed  to  by
       *argvPtr  is dynamically allocated;  in addition to the array of point-
       ers, 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  fol-
       lowing:
              Tcl_Free((char *) argv);

       Tcl_SplitList  normally  returns  TCL_OK, which means the list was suc-
       cessfully 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 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_ScanEle-
       ment.  Tcl_ConvertElement writes a proper list element to memory start-
       ing  at  *dst  and  returns  a  count of the total number of characters
       written, which will be no more than the result returned by Tcl_ScanEle-
       ment.  Tcl_ConvertElement writes out only the actual list element with-
       out 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 char-
       acters  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.

       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  embed-
       ded nulls.


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



Tcl                                   8.0                     Tcl_SplitList(3)