Scroll to navigation

Tk_ParseArgv(3tk) Tk Library Procedures Tk_ParseArgv(3tk) 





NAME


Tk_ParseArgv - process command-line options






SYNOPSIS


#include <tk.h>

int
Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags)






ARGUMENTS



  
Tcl_Interp *interp (in)

  
Interpreter to use for returning error messages.

  
Tk_Window tkwin (in)

  
Window to use when arguments specify Tk options. If NULL, then no Tk
      options will be processed.

  
int argcPtr (in/out)

  
Pointer to number of arguments in argv; gets modified to hold number of
      unprocessed arguments that remain after the call.

  
const char **argv (in/out)

  
Command line arguments passed to main program. Modified to hold
      unprocessed arguments that remain after the call.

  
Tk_ArgvInfo *argTable (in)

  
Array of argument descriptors, terminated by element with type
      TK_ARGV_END.

  
int flags (in)

  
If non-zero, then it specifies one or more flags that control the parsing
      of arguments. Different flags may be OR'ed together. The flags currently
      defined are TK_ARGV_DONT_SKIP_FIRST_ARG, TK_ARGV_NO_ABBREV,
      TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS.
    
    

    

  








DESCRIPTION


Tk_ParseArgv processes an array of command-line arguments
    according to a table describing the kinds of arguments that are expected.
    Each of the arguments in argv is processed in turn: if it matches one
    of the entries in argTable, the argument is processed according to
    that entry and discarded. The arguments that do not match anything in
    argTable are copied down to the beginning of argv (retaining
    their original order) and returned to the caller. At the end of the call
    Tk_ParseArgv sets *argcPtr to hold the number of arguments
    that are left in argv, and argv[*argcPtr] will hold the value
    NULL. Normally, Tk_ParseArgv assumes that argv[0] is a command
    name, so it is treated like an argument that does not match argTable
    and returned to the caller; however, if the
    TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in flags then
    argv[0] will be processed just like the other elements of
    argv.


Tk_ParseArgv normally returns the value TCL_OK. If
    an error occurs while parsing the arguments, then TCL_ERROR is
    returned and Tk_ParseArgv will leave an error message in the result
    of interpreter interp in the standard Tcl fashion. In the event of an
    error return, *argvPtr will not have been modified, but argv
    could have been partially modified. The possible causes of errors are
    explained below.


The argTable array specifies the kinds of arguments that
    are expected; each of its entries has the following structure:




typedef struct {


    const char *key;


    int type;


    void *src;


    void *dst;


    const char *help;
} Tk_ArgvInfo;



The key field is a string such as “-display” or
  “-bg” that is compared with the values in argv.
  Type indicates how to process an argument that matches key (more
  on this below). Src and dst are additional values used in
  processing the argument. Their exact usage depends on type, but
  typically src indicates a value and dst indicates where to store
  the value. The char * declarations for src and dst are
  placeholders: the actual types may be different. Lastly, help is a
  string giving a brief description of this option; this string is printed when
  users ask for help about command-line options.

When processing an argument in argv, Tk_ParseArgv
    compares the argument to each of the key's in argTable.
    Tk_ParseArgv selects the first specifier whose key matches the
    argument exactly, if such a specifier exists. Otherwise Tk_ParseArgv
    selects a specifier for which the argument is a unique abbreviation. If the
    argument is a unique abbreviation for more than one specifier, then an error
    is returned. If there is no matching entry in argTable, then the
    argument is skipped and returned to the caller.


Once a matching argument specifier is found, Tk_ParseArgv
    processes the argument according to the type field of the specifier.
    The argument that matched key is called “the matching
    argument” in the descriptions below. As part of the processing,
    Tk_ParseArgv may also use the next argument in argv after the
    matching argument, which is called “the following argument”.
    The legal values for type, and the processing that they cause, are as
    follows:



  

  
Marks the end of the table. The last entry in argTable must have
      this type; all of its other fields are ignored and it will never match any
      arguments.

  

  
Src is treated as an integer and dst is treated as a pointer
      to an integer. Src is stored at *dst. The matching argument
      is discarded.

  

  
The following argument must contain an integer string in the format
      accepted by strtol (e.g. “0” and “0x”
      prefixes may be used to specify octal or hexadecimal numbers,
      respectively). Dst is treated as a pointer to an integer; the
      following argument is converted to an integer value and stored at
      *dst. Src is ignored. The matching and following arguments
      are discarded from argv.

  

  
The following argument must contain a floating-point number in the format
      accepted by strtol. Dst is treated as the address of a
      double-precision floating point value; the following argument is converted
      to a double-precision value and stored at *dst. The matching and
      following arguments are discarded from argv.

  

  
In this form, dst is treated as a pointer to a (char *);
      Tk_ParseArgv stores at *dst a pointer to the following
      argument, and discards the matching and following arguments from
      argv. Src is ignored.

  

  
This form is similar to TK_ARGV_STRING, except that the argument is
      turned into a Tk_Uid by calling Tk_GetUid. Dst is treated as
      a pointer to a Tk_Uid; Tk_ParseArgv stores at *dst the
      Tk_Uid corresponding to the following argument, and discards the matching
      and following arguments from argv. Src is ignored.

  

  
This form causes a Tk option to be set (as if the option command
      had been invoked). The src field is treated as a pointer to a
      string giving the value of an option, and dst is treated as a
      pointer to the name of the option. The matching argument is discarded. If
      tkwin is NULL, then argument specifiers of this type are ignored
      (as if they did not exist).

  

  
This form is similar to TK_ARGV_CONST_OPTION, except that the value
      of the option is taken from the following argument instead of from
      src. Dst is used as the name of the option. Src is
      ignored. The matching and following arguments are discarded. If
      tkwin is NULL, then argument specifiers of this type are ignored
      (as if they did not exist).

  

  
In this case the following argument is taken as the name of a Tk option
      and the argument after that is taken as the value for that option. Both
      src and dst are ignored. All three arguments are discarded
      from argv. If tkwin is NULL, then argument specifiers of
      this type are ignored (as if they did not exist).

  

  
When this kind of option is encountered, Tk_ParseArgv uses the
      help fields of argTable to format a message describing all
      the valid arguments. The message is placed in interpreter interp's
      result and Tk_ParseArgv returns TCL_ERROR. When this
      happens, the caller normally prints the help message and aborts. If the
      key field of a TK_ARGV_HELP specifier is NULL, then the
      specifier will never match any arguments; in this case the specifier
      simply provides extra documentation, which will be included when some
      other TK_ARGV_HELP entry causes help information to be
    returned.

  

  
This option is used by programs or commands that allow the last several of
      their options to be the name and/or options for some other program. If a
      TK_ARGV_REST argument is found, then Tk_ParseArgv does not
      process any of the remaining arguments; it returns them all at the
      beginning of argv (along with any other unprocessed arguments). In
      addition, Tk_ParseArgv treats dst as the address of an
      integer value, and stores at *dst the index of the first of the
      TK_ARGV_REST options in the returned argv. This allows the
      program to distinguish the TK_ARGV_REST options from other
      unprocessed options that preceded the TK_ARGV_REST.

  

  
For this kind of argument, src is treated as the address of a
      procedure, which is invoked to process the following argument. The
      procedure should have the following structure:








int
func(dst, key, nextArg)


    char *dst;


    char *key;


    char *nextArg;
{
}



The dst and key parameters will contain the corresponding fields
  from the argTable entry, and nextArg will point to the following
  argument from argv (or NULL if there are not any more arguments left in
  argv). If func uses nextArg (so that Tk_ParseArgv
  should discard it), then it should return 1. Otherwise it should return 0 and
  TkParseArgv will process the following argument in the normal fashion.
  In either event the matching argument is discarded.



  

  
This form provides a more general procedural escape. It treats src
      as the address of a procedure, and passes that procedure all of the
      remaining arguments. The procedure should have the following form:








int
genfunc(dst, interp, key, argc, argv)


    char *dst;


    Tcl_Interp *interp;


    char *key;


    int argc;


    char **argv;
{
}



The dst and key parameters will contain the corresponding fields
  from the argTable entry. Interp will be the same as the
  interp argument to Tcl_ParseArgv. Argc and argv
  refer to all of the options after the matching one. Genfunc should
  behave in a fashion similar to Tk_ParseArgv: parse as many of the
  remaining arguments as it can, then return any that are left by compacting
  them to the beginning of argv (starting at argv[0]).
  Genfunc should return a count of how many arguments are left in
  argv; Tk_ParseArgv will process them. If genfunc
  encounters an error then it should leave an error message in interpreter
  interp's result, in the usual Tcl fashion, and return -1; when this
  happens Tk_ParseArgv will abort its processing and return
  TCL_ERROR.




FLAGS



  

  
Tk_ParseArgv normally treats argv[0] as a program or command
      name, and returns it to the caller just as if it had not matched
      argTable. If this flag is given, then argv[0] is not given
      special treatment.

  

  
Normally, Tk_ParseArgv accepts unique abbreviations for key
      values in argTable. If this flag is given then only exact matches
      will be acceptable.

  

  
Normally, Tk_ParseArgv returns unrecognized arguments to the
      caller. If this bit is set in flags then Tk_ParseArgv will
      return an error if it encounters any argument that does not match
      argTable. The only exception to this rule is argv[0], which
      will be returned to the caller with no errors as long as
      TK_ARGV_DONT_SKIP_FIRST_ARG is not specified.

  

  
Normally, Tk_ParseArgv searches an internal table of standard
      argument specifiers in addition to argTable. If this bit is set in
      flags, then Tk_ParseArgv will use only argTable and
      not its default table.










EXAMPLE


Here is an example definition of an argTable and some
    sample command lines that use the options. Note the effect on argc
    and argv; arguments processed by Tk_ParseArgv are eliminated
    from argv, and argc is updated to reflect reduced number of
    arguments.




/*


 * Define and set default values for globals.


 */
int debugFlag = 0;
int numReps = 100;
char defaultFileName[] = "out";
char *fileName = defaultFileName;
Boolean exec = FALSE;
/*


 * Define option descriptions.


 */
Tk_ArgvInfo argTable[] = {


    {"-X", TK_ARGV_CONSTANT, (char *) 1, &debugFlag,


        "Turn on debugging printfs"},


    {"-N", TK_ARGV_INT, NULL, &numReps,


        "Number of repetitions"},


    {"-of", TK_ARGV_STRING, NULL, &fileName,


        "Name of file for output"},


    {"x", TK_ARGV_REST, NULL, &exec,


        "File to exec, followed by any arguments (must be last argument)."},


    {NULL, TK_ARGV_END, NULL, NULL,


        NULL}
};
int main(int argc, char *argv[])
{


    ...


    if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {


        fprintf(stderr, "%s\n", Tcl_GetString(Tcl_GetObjResult(interp)));


        exit(1);


    }


    /*


     * Remainder of the program.


     */
}




Note that default values can be assigned to variables named in
    argTable: the variables will only be overwritten if the particular
    arguments are present in argv. Here are some example command lines
    and their effects.




prog -N 200 infile        # just sets the numReps variable to 200
prog -of out200 infile    # sets fileName to reference "out200"
prog -XN 10 infile        # sets the debug flag, also sets numReps



In all of the above examples, argc will be set by Tk_ParseArgv to
  2, argv[0] will be “prog”, argv[1] will be
  “infile”, and argv[2] will be NULL.





KEYWORDS


arguments, command line, options







  

    
    Tk