Provided by: tcl8.6-doc_8.6.13+dfsg-2_all bug

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

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

       int *objcPtr (in/out)                       A   pointer  to  variable  holding  number  of
                                                   arguments in objv. Will be  modified  to  hold
                                                   number  of  arguments  left in the unprocessed
                                                   argument list stored in remObjv.

       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  unprocessed  arguments.  Should be NULL if
                                                   no  return   of   unprocessed   arguments   is
                                                   required.  If objcPtr is updated 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 interpreter 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 terminated by an entry with the type
       field set  to  TCL_ARGV_END.  As  convenience,  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 argument, 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 argument 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 handler 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
              following 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  argument,  but  instead
              causes  Tcl_ParseArgsObjv  to  generate  an  error message describing the arguments
              supported. All other fields except 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 argument, but instead marks
              all  following  arguments to be left unprocessed. 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 representation 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(3tcl), Tcl_Main(3tcl), Tcl_CreateObjCommand(3tcl)

KEYWORDS

       argument, parse