Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tcl_SplitList(3)	    Tcl	Library	Procedures	      Tcl_SplitList(3)


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

       #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 left.

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

       int *argcPtr (out)			  Filled in with number	of el-
						  ements 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  ele-
						  ments	 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

       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_ConvertEle-

       int length (in)				  Number  of  bytes  in	string

       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_ScanElement,
						  possibly     OR-ed	  with

       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-
	      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 re-
       turned 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  re-
       lease the space using Tcl_Free.

       If the result of	Tcl_Merge is passed to Tcl_SplitList, the elements re-
       turned  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 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 output 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 beginning 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 character by OR-ing the flag |
       value returned by Tcl_ScanElement with TCL_DONT_QUOTE_HASH.

       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.

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

Tcl				      8.0		      Tcl_SplitList(3)


Want to link to this manual page? Use this URL:

home | help