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

Tcl                                                    8.6                               Tcl_ParseArgsObjv(3tcl)