NAME

Opt_Parse, Opt_PrintUsage − Manage command line options

SYNOPSIS

#include <option.h> int Opt_Parse(argc, argv, optionArray, numOptions, flags) void Opt_PrintUsage(commandName, optionArray, numOptions)

ARGUMENTS

int argc   (in) Number of arguments on command line. 

char ∗∗argv   (in/out) Command line arguments passed to main program. 

char ∗commandName   (in) Name of the program being run, usually argv[0]. 

Option ∗optionArray   (in) An array of option descriptions. 

int numOptions   (in) Number of elements in optionArray, usually obtained using the Opt_Number macro, e.g. Opt_Number(optionArray). 

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 only flags currently defined are OPT_ALLOW_CLUSTERING and OPT_OPTIONS_FIRST. 

DESCRIPTION

Opt_Parse parses the command line arguments of a program according to an array of option descriptions.  Starting with argv[1], it parses as many options as it can and returns the rest of the options in the argv array, compacted to the beginning of the array (starting with argv[1]).  The return value indicates how many options are returned in the argv array (including argv[0]).  Opt_Parse returns options that don’t start with “-” unless they are arguments for options that it parses.  Opt_Parse also returns any options following an OPT_REST option (see below for more details). 

Each element of the array optionArray has the following structure: typedef struct Option {
    inttype;
    char∗key;
    char∗valuePtr;
    char∗docMsg; } Option;

The key field is a string that identifies this option.  For example, if key is foo, then this Option will match a −foo command-line option.  If key is the empty string (“”) then it matches a − command-line option.  If key is NULL, the Option will not match any command-line options (this feature is only useful for OPT_DOC options).  DocMsg is a documentation string to print out as part of a help message.  The type field determines what to do when this Option is matched.  It also determines the meaning of the valuePtr field.  Type should always be specified using one of the following macros:

OPT_TRUE
Treats valuePtr as the address of an integer, and stores the value 1 in that integer. 

OPT_FALSE
Treats valuePtr as the address of an integer and stores the value 0 in that integer. 

OPT_CONSTANT(value)
This is a generalized form of OPT_TRUE and OPT_FALSE.  Treats valuePtr as the address of an integer and stores value in that integer.  Value must be a positive integer. 

OPT_INT
The next argument after the one matching key 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).  ValuePtr will be treated as the address of an integer, and the value given by the next argument will be stored there. 

OPT_TIME
The next argument after the one matching key must contain a string that is parsable as a date and time.  Currently, only two formats are recognized: seconds

and yy.mm.dd.hh.mm.ss

The first form is simply the number of seconds since the start of the epoch (1 January 1970, 0 hours GMT).  The second form specifies the year (e.g., 91 or 1991), month (1-12), day of the month, hours (0-23), minutes (0-59), and seconds (0-59).  All fields must be specified.  ValuePtr will be treated as the address of a time_t (defined in <time.h>), and the given time will be stored there.  All times are in terms of the current timezone and daylight savings rules. 

Note that this flavor can clobber the static buffer used by the localtime library routine. 

OPT_FLOAT
The next argument after the one matching key must contain a floating-point number in the format accepted by strtol.  ValuePtr will be treated as the address of an double-precision floating point value, and the value given by the next argument will be stored there. 

OPT_STRING
Treats valuePtr as the address of a (char ∗), and stores a pointer to the next argument in the location pointed to by valuePtr. 

OPT_DOC
This option is intended primarily as a way of printing extra documentation during help message printouts.  It isn’t normally used as an actual option (and normally its key field is NULL).  If it is invoked as an option, then the same thing happens as for the “-?” option:  descriptions get printed for all options in optionArray and Opt_Parse calls exit(0) to terminate the process. 

OPT_REST
This option is used by programs that allow the last several of their options to be the name and/or options for some other program.  If an OPT_REST option is found, then Opt_Parse doesn’t process any of the remaining arguments;  it returns them all at the beginning of argv.  In addition, Opt_Parse treats valuePtr as the address of an integer value, and stores in that value the index of the first of the OPT_REST options in the returned argv.  This allows the program to distinguish the OPT_REST options from other unprocessed options that preceeded the OPT_REST. 

OPT_FUNC
When one of these options is encountered, valuePtr is treated as the address of a function which is then called with the following calling sequence: int func(optString, nextArg)
    char∗optString;
    char∗nextArg; { }

The optString parameter points to the current option, and nextArg points to the next option from argv (or NULL if there aren’t any more options in argv.  If func uses nextArg as an argument to the current option (so that Opt_Parse should skip it), then it should return 1.  Otherwise it should return 0. 

OPT_GENFUNC
Treat valuePtr as the address of a function and pass all of the remaining arguments to it in the following way: int genfunc(optString, argc, argv)
    char∗optString;
    intargc;
    char∗∗argv; { }

Argc and argv refer to all of the options after the one that triggered the call, and optString points to the triggering option.  Genfunc should behave in a fashion similar to Opt_Parse:  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; Opt_Parse will process them. 
 

FLAGS

OPT_ALLOW_CLUSTERING
This will permit several options to be clustered together with a single “-”, e.g., “foo -abc” will be handled the same way as “foo -a -b -c”.  OPT_ALLOW_CLUSTERING is likely to cause confusing behavior unless each option is identified with a single character.

OPT_OPTIONS_FIRST
This causes Opt_Parse to stop parsing the command line anytime something that is not an option is detected.  Thus, a program that takes some options followed by a command to execute (along with that command’s options) can parse its own options using OPT_OPTIONS_FIRST.  When the command to execute is encountered, assuming it does not begin with a hyphen, Opt_Parse will return the command and its arguments starting at argv[1], ignoring any arguments with hyphens following the first non-option. 

USAGE MESSAGE

Opt_PrintUsage may be invoked to print out all the documentation strings (plus option names and default values) for a command’s options.  If Opt_Parse encounters an option “-?” or “-help”, then it will call Opt_PrintUsage and exit.  Note:  in some shells the question-mark must be escaped (e.g., “foo -\?” in csh). 
 

EXAMPLE

Here is an example definition of a set of option descriptions and some sample command lines that use the options.  Note the effect on argc and argv;  command arguments that get interpreted as options or option values are eliminated from argv, and argc is updated to reflect reduced number of arguments.  /∗
 ∗ Define and set default values for globals.
 ∗/ Boolean debugFlag = FALSE; int numReps = 100; char defaultFileName[] = "out"; char ∗fileName = defaultFileName; Boolean exec = FALSE;
 
/∗
 ∗ Define option descriptions.
 ∗/ Option optionArray[] = {
    OPT_TRUE, "X", (char ∗) &debugFlag, "Turn on debugging printfs",
    OPT_INT, "N", (char ∗) &numReps, "Number of repetitions",
    OPT_STRING, "of", (char ∗) &fileName, "Output filename",
    OPT_REST, "x", (char ∗) &exec,
        "File to exec, followed by any arguments (must be last argument).", };
 
main(argc, argv)
    int argc;
    char ∗argv[]; {
    Opt_Parse(argc, argv, optionArray, Opt_Number(optionArray),
            OPT_ALLOW_CLUSTERING);
 
    /∗
     ∗ the rest of the program.
     ∗/ }

Note that default values can be assigned to option variables.  Also, numOptions gets calculated by the compiler in this example.  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, the return value from Opt_Parse will be 2, argv[0] will be “prog”, argv[1] will be “infile”, and argv[2] will be NULL. 
 

KEYWORDS

arguments, command line, options

Sprite version 1.0  —  January 28, 1991