Scroll to navigation

Tcl_ParseArgsObjv(3tcl) Tcl Library Procedures Tcl_ParseArgsObjv(3tcl) 





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.

  
Tcl_Size | 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. May be (Tcl_Size *)NULL when not used. If it
      points to a variable which type is not Tcl_Size, a compiler warning
      will be generated. If your extensions is compiled with -DTCL_8_API, this
      function will return NULL for argument lists with more than INT_MAX
      elements (which should trigger proper error-handling), otherwise expect it
      to crash.

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

    

  








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:



  

  
Enables the argument processor to provide help when passed the argument
      “-help”.

  

  
Instructs the argument processor that arguments after
      “--” are to be unprocessed.

  

  
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;


    void *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:



  

  
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.

  

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

  

  
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.

  

  
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)(


        void *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.





  

  
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 Tcl_Size (Tcl_ArgvGenFuncProc)(


        void *clientData,


        Tcl_Interp *interp,


        Tcl_Size 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, 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.





  

  
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.

  

  
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.

  

  
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.

  

  
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.










REFERENCE COUNT MANAGEMENT


The values in the objv argument to Tcl_ParseArgsObjv
    will not have their reference counts modified by this function. The
    interpreter result may be modified on error; the values passed should not be
    the interpreter result with no further reference added.






SEE ALSO


Tcl_GetIndexFromObj(3tcl), Tcl_Main(3tcl),
    Tcl_CreateObjCommand(3tcl)






KEYWORDS


argument, parse







  

    8.6
    Tcl