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

FreeBSD Manual Pages

  
 
  

home | help
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)

       Tcl_Size
       Tcl_ScanElement(src, flagsPtr)

       Tcl_Size
       Tcl_ScanCountedElement(src, length, flagsPtr)

       Tcl_Size
       Tcl_ConvertElement(src, dst, flags)

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

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

       Tcl_Size	| int *argcPtr (out)		  Filled in with number	of el-
						  ements  in  list.   May   be
						  (Tcl_Size  *)NULL  when  not
						  used.	 If  it	 points	 to  a
						  variable  which  type	is not
						  Tcl_Size, a compiler warning
						  will be generated.  If  your
						  extensions  is compiled with
						  -DTCL_8_API,	this  function
						  will	return	TCL_ERROR  for
						  lists	with more than INT_MAX
						  elements (which should trig-
						  ger proper  error-handling),
						  otherwise   expect   it   to
						  crash.

       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.

       Tcl_Size	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_ConvertEle-
						  ment.

       Tcl_Size	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_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:

	      Tcl_Size argc;
	      int 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(argv);

       Tcl_SplitList normally returns TCL_OK, which means the  list  was  suc-
       cessfully  parsed.  If sizePtr points to	a variable of type int and the
       list contains more than 2**31 key/value pairs, or 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 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.

SEE ALSO
       Tcl_ListObjGetElements(3)

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

Tcl				      8.0		      Tcl_SplitList(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_ScanCountedElement.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help