DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

Tcl_SplitList(3tcl)




______________________________________________________________________________


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.

       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   Tcl_Con-
                                                   vertElement.

       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  Tcl_ScanEle-
                                                   ment, 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 writ-
       ten, 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 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)

Man(1) output converted with man2html