Tcl_Merge man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



Tcl_SplitList(3)      Tcl Library Procedures	 Tcl_SplitList(3)

_________________________________________________________________

NAME
       Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertEle-
       ment - 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_ConvertElement(src, 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.

Tcl			       7.5				1

Tcl_SplitList(3)      Tcl Library Procedures	 Tcl_SplitList(3)

       char	    *src	 (in)	   String   that   is  to
					   become an element of a
					   list.

       int	    *flagsPtr	 (in)	   Pointer   to	 word  to
					   fill in with	 informa-
					   tion	 about	src.  The
					   value   of	*flagsPtr
					   must	  be   passed  to
					   Tcl_ConvertElement.

       char	    *dst	 (in)	   Place  to  copy   con-
					   verted  list	 element.
					   Must	 contain   enough
					   characters	to   hold
					   converted string.

       int	    flags	 (in)	   Information about src.
					   Must be value returned
					   by  previous	 call  to
					   Tcl_ScanElement,  pos-
					   sibly    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  con-
       stituent	 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 addi-
       tion to the array of pointers, 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 following:					  |
	      Tcl_Free((char *) argv);				  |

       Tcl_SplitList normally returns  TCL_OK,	which  means  the
       list was successfully parsed.  If there was a syntax error
       in list, then TCL_ERROR	is  returned  and  interp->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			       7.5				2

Tcl_SplitList(3)      Tcl Library Procedures	 Tcl_SplitList(3)

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

       Tcl_ScanElement and Tcl_ConvertElement are the  procedures
       that  do	 all of the real work of Tcl_Merge.  Tcl_ScanEle-
       ment scans its src argument  and	 determines  how  to  use
       backslashes  and	 braces when converting it to a list ele-
       ment.  It returns an overestimate of the number of charac-
       ters  required  to represent src as a list element, and it
       stores information in *flagsPtr that is needed by Tcl_Con-
       vertElement.

       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_ScanElement.	 Tcl_Con-
       vertElement  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_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  characters by surrounding the string
       with braces.   This  produces  clean-looking  output,  but
       can't  be  used	in some situations, such as when src con-
       tains unmatched braces.	 In  these  situations,	 Tcl_Con-
       vertElement handles special characters by generating back-
       slash 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

Tcl			       7.5				3

Tcl_SplitList(3)      Tcl Library Procedures	 Tcl_SplitList(3)

       will  produce  an uglier result, it is useful in some spe-
       cial situations, such as when Tcl_ConvertElement is  being
       used  to	 generate a portion of an argument for a Tcl com-
       mand.  In this case, surrounding	 src  with  curly  braces
       would cause the command not to be parsed correctly.

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

Tcl			       7.5				4

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net