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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       Tcl_ParseArgsObjv - parse arguments according to	a tabular description

SYNOPSIS
       #include	<tcl.h>

       int
       Tcl_ParseArgsObjv(interp, argTable, objcPtr, objv, remObjv)

ARGUMENTS
       Tcl_Interp *interp (out)			   Where  to  store error mes-
						   sages.

       const Tcl_ArgvInfo *argTable (in)	   Pointer to array of	option
						   descriptors.

       int *objcPtr (in/out)			   A pointer to	variable hold-
						   ing number of arguments  in
						   objv.  Will	be modified to
						   hold	 number	 of  arguments
						   left	in the unprocessed ar-
						   gument list stored  in  re-
						   mObjv.

       Tcl_Obj *const *objv (in)		   The	array  of arguments to
						   be parsed.

       Tcl_Obj ***remObjv (out)			   Pointer to a	variable  that
						   will	 hold the array	of un-
						   processed	    arguments.
						   Should be NULL if no	return
						   of unprocessed arguments is
						   required. If	objcPtr	is up-
						   dated to a non-zero	value,
						   the	array returned through
						   this	 must  be  deallocated
						   using ckfree.
______________________________________________________________________________

DESCRIPTION
       The  Tcl_ParseArgsObjv  function	provides a system for parsing argument
       lists of	the form "-someName someValue ...".  Such argument  lists  are
       commonly	 found both in the arguments to	a program and in the arguments
       to an individual	Tcl command. This parser assumes that the order	of the
       arguments  does	not  matter, other than	in so far as later copies of a
       duplicated option overriding earlier ones.

       The argument array is described by the objcPtr and objv parameters, and
       an  array  of unprocessed arguments is returned through the objcPtr and
       remObjv parameters; if no return	of unprocessed arguments  is  desired,
       the remObjv parameter should be NULL. If	any problems happen, including
       if the "generate	help" option is	selected, an error message is left  in
       the interpreter result and TCL_ERROR is returned. Otherwise, the	inter-
       preter result is	left unchanged and TCL_OK is returned.

       The collection of arguments to be parsed	is described by	 the  argTable
       parameter. This points to a table of descriptor structures that is ter-
       minated by an entry with	the type field set to TCL_ARGV_END. As	conve-
       nience, the following prototypical entries are provided:

       TCL_ARGV_AUTO_HELP
	      Enables  the  argument processor to provide help when passed the
	      argument "-help".

       TCL_ARGV_AUTO_REST
	      Instructs	the argument processor that arguments after  "--"  are
	      to be unprocessed.

       TCL_ARGV_TABLE_END
	      Marks the	end of the table of argument descriptors.

   ARGUMENT DESCRIPTOR ENTRIES
       Each entry of the argument descriptor table must	be a structure of type
       Tcl_ArgvInfo. The structure is defined as this:

	      typedef struct {
		  int type;
		  const	char *keyStr;
		  void *srcPtr;
		  void *dstPtr;
		  const	char *helpStr;
		  ClientData clientData;
	      }	Tcl_ArgvInfo;

       The keyStr field	contains the name of the option; by  convention,  this
       will  normally begin with a "-" character. The type, srcPtr, dstPtr and
       clientData fields describe the interpretation of	the value of the argu-
       ment,  as  described  below.  The helpStr field gives some text that is
       used to provide help to users when they request it.

       As noted	above, the type	field is used to describe  the	interpretation
       of the argument's value.	The following values are acceptable values for
       type:

       TCL_ARGV_CONSTANT
	      The argument does	not take any following value argument. If this
	      argument	is present, the	(integer) value	of the srcPtr field is
	      copied to	the variable pointed  to  by  the  dstPtr  field.  The
	      clientData field is ignored.

       TCL_ARGV_END
	      This value marks the end of all option descriptors in the	table.
	      All other	fields are ignored.

       TCL_ARGV_FLOAT
	      This argument takes a following floating point  value  argument.
	      The  value  (once	parsed by Tcl_GetDoubleFromObj)	will be	stored
	      as a double-precision value in the variable pointed  to  by  the
	      dstPtr field. The	srcPtr and clientData fields are ignored.

       TCL_ARGV_FUNC
	      This argument optionally takes a following value argument; it is
	      up to the	handler	callback function passed in srcPtr to  decide.
	      That function will have the following signature:

		     typedef int (Tcl_ArgvFuncProc)(
			     ClientData	clientData,
			     Tcl_Obj *objPtr,
			     void *dstPtr);

	      The  result is a boolean value indicating	whether	to consume the
	      following	argument. The clientData is the	value from  the	 table
	      entry, the objPtr	is the value that represents the following ar-
	      gument or	NULL if	there are no following arguments at  all,  and
	      the  dstPtr  argument to the Tcl_ArgvFuncProc is the location to
	      write the	parsed value to.

       TCL_ARGV_GENFUNC
	      This argument takes zero or more following arguments;  the  han-
	      dler  callback  function passed in srcPtr	returns	how many (or a
	      negative number to signal	an error, in which case	it should also
	      set  the interpreter result). The	function will have the follow-
	      ing signature:

		     typedef int (Tcl_ArgvGenFuncProc)(
			     ClientData	clientData,
			     Tcl_Interp	*interp,
			     int objc,
			     Tcl_Obj *const *objv,
			     void *dstPtr);

	      The clientData is	the value from the table entry,	the interp  is
	      where to store any error messages, the keyStr is the name	of the
	      argument,	objc and objv describe an array	of all	the  remaining
	      arguments, and dstPtr argument to	the Tcl_ArgvGenFuncProc	is the
	      location to write	the parsed value (or values) to.

       TCL_ARGV_HELP
	      This special argument does not take any  following  value	 argu-
	      ment,  but instead causes	Tcl_ParseArgsObjv to generate an error
	      message describing the arguments supported. All other fields ex-
	      cept the helpStr field are ignored.

       TCL_ARGV_INT
	      This  argument  takes  a	following  integer value argument. The
	      value (once parsed by Tcl_GetIntFromObj) will be	stored	as  an
	      int  in  the variable pointed to by the dstPtr field. The	srcPtr
	      field is ignored.

       TCL_ARGV_REST
	      This special argument does not take any  following  value	 argu-
	      ment,  but  instead marks	all following arguments	to be left un-
	      processed. The srcPtr, dstPtr and	clientData fields are ignored.

       TCL_ARGV_STRING
	      This argument takes a following string value argument. A pointer
	      to  the  string will be stored at	dstPtr;	the string inside will
	      have a lifetime linked to	the lifetime of	the string representa-
	      tion  of	the argument value that	it came	from, and so should be
	      copied if	it needs to be retained.  The  srcPtr  and  clientData
	      fields are ignored.

SEE ALSO
       Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3)

KEYWORDS
       argument, parse

Tcl				      8.6		  Tcl_ParseArgsObjv(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_ParseArgsObjv.tcl86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help