Tcl_ConvertCountedElement man page on OpenDarwin

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

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)

       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)
[top]

List of man pages available for OpenDarwin

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