TclSplitList(3) Tcl Library Procedures TclSplitList(3)

NAME
       TclSplitList,    TclMerge,    TclScanElement,    TclConvertElement,
       TclScanCountedElement,  TclConvertCountedElement  -  manipulate   Tcl
       lists

SYNOPSIS
       ##iinncclluuddee <>

       int
       TTccllSSpplliittLLiisstt(interp, list, argcPtr, argvPtr)

       char *
       TTccllMMeerrggee(argc, argv)

       int
       TTccllSSccaannEElleemmeenntt(src, flagsPtr)

       int
       TTccllSSccaannCCoouunntteeddEElleemmeenntt(src, length, flagsPtr)

       int
       TTccllCCoonnvveerrttEElleemmeenntt(src, dst, flags)

       int
       TTccllCCoonnvveerrttCCoouunntteeddEElleemmeenntt(src, length, dst, flags)

AARRGGUUMMEENNTTSS
       TclInterp           *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.

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

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

       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   TTccllCCoonn-
                                                   vveerrttEElleemmeenntt.

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

       int                  flags        (in)      Information about src. Must
                                                   be value returned by previ-
                                                   ous  call  to  TTccllSSccaannEEllee-
                                                   mmeenntt, possibly  OR-ed  with
                                                   TTCCLLDDOONNTTUUSSEEBBRRAACCEESS.



DESCRIPTION
       These  procedures  may be used to disassemble and reassemble Tcl lists.
       TTccllSSpplliittLLiisstt breaks a list up into its constituent elements, returning
       an  array of pointers to the elements using argcPtr and argvPtr.  While
       extracting the arguments, TTccllSSpplliittLLiisstt 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 TTccllSSpplliittLLiisstt with the following code:
              int argc, code;
              char *string;
              char **argv;
              ...
              code = TclSplitList(interp, string, &argc, &argv);
       Then  you  should eventually free the storage with a call like the fol-
       lowing:
              TclFree((char *) argv);

       TTccllSSpplliittLLiisstt normally returns TTCCLLOOKK, which means the  list  was  suc-
       cessfully  parsed.  If there was a syntax error in list, then TTCCLLEERRRROORR
       is returned and the interpreter's result will point to an error message
       describing  the  problem  (if  interp  was  not NULL).  If TTCCLLEERRRROORR is
       returned then no memory is allocated and *argvPtr is not modified.

       TTccllMMeerrggee is the inverse of TTccllSSpplliittLLiisstt:  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 iinnddeexx may be used
       to  extract the original elements again.  In addition, if the result of
       TTccllMMeerrggee is passed to TTccllEEvvaall, it will  be  parsed  into  argc  words
       whose  values will be the same as the argv strings passed to TTccllMMeerrggee.
       TTccllMMeerrggee 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  TTccllAAlllloocc;   the  caller  must  eventually
       release the space using TTccllFFrreeee.

       If  the  result  of  TTccllMMeerrggee is passed to TTccllSSpplliittLLiisstt, the elements
       returned by TTccllSSpplliittLLiisstt  will  be  identical  to  those  passed  into
       TTccllMMeerrggee.   However,  the  converse  is not true:  if TTccllSSpplliittLLiisstt is
       passed a given string, and the resulting argc and argv  are  passed  to
       TTccllMMeerrggee,  the  resulting  string  may not be the same as the original
       string passed to TTccllSSpplliittLLiisstt.  This  is  because  TTccllMMeerrggee  may  use
       backslashes and braces differently than the original string.

       TTccllSSccaannEElleemmeenntt  and  TTccllCCoonnvveerrttEElleemmeenntt are the procedures that do all
       of the real work of TTccllMMeerrggee.  TTccllSSccaannEElleemmeenntt 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 TTccllCCoonnvveerrttEElleemmeenntt.

       TTccllCCoonnvveerrttEElleemmeenntt is a companion  procedure  to  TTccllSSccaannEElleemmeenntt.   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  TTccllSSccaannEEllee-
       mmeenntt.  TTccllCCoonnvveerrttEElleemmeenntt writes a proper list element to memory start-
       ing at *dst and returns a count of the total number of characters writ-
       ten, which will be no more than the result returned by TTccllSSccaannEElleemmeenntt.
       TTccllCCoonnvveerrttEElleemmeenntt 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.

       TTccllCCoonnvveerrttEElleemmeenntt 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,  TTccllCCoonnvveerrttEElleemmeenntt
       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  TTccllSSccaannEElleemmeenntt  with TTCCLLDDOONNTTUUSSEEBBRRAACCEESS.  Although this
       will produce an uglier result, it is useful in some special situations,
       such  as when TTccllCCoonnvveerrttEElleemmeenntt 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.

       TTccllSSccaannCCoouunntteeddEElleemmeenntt  and  TTccllCCoonnvveerrttCCoouunntteeddEElleemmeenntt  are the same as
       TTccllSSccaannEElleemmeenntt and TTccllCCoonnvveerrttEElleemmeenntt, except the length of string src
       is  specified by the length argument, and the string may contain embed-
       ded nulls.


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



Tcl                                   8.0                     TclSplitList(3)