Tcl_ScanElement man page on UnixWare

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

Tcl_SplitList(3)	    Tcl Library Procedures	      Tcl_SplitList(3)

______________________________________________________________________________

NAME
       Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement - manipu‐
       late 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.

       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.

       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_ConvertElement.		       │

       int	    length	 (in)					       │
					   Number of bytes in string src.

       char	    *dst	 (in)	   Place to copy converted  list  ele‐
					   ment.   Must contain enough charac‐
					   ters to hold converted string.

       int	    flags	 (in)	   Information	about  src.  Must   be
					   value  returned by previous 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:
	      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 interp->result will point to an error message  describ‐
       ing  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				      7.5		      Tcl_SplitList(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server UnixWare

List of man pages available for UnixWare

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