SYNOPSIS

#include <vistaio.h>

typedef struct {

VistaIOStringConst keyword;/* keyword signaling option */ VistaIORepnKind repn; /* type of value supplied by option */ int number; /* number of values supplied */ VistaIOPointer value; /* location for storing value(s) */ VistaIOBoolean *found; /* whether optional arg found */ VistaIODictEntry *dict; /* optional dict of value keywords */ VistaIOStringConst blurb;/* on-line help blurb */

} VistaIOOptionDescRec;

typedef struct {

int number; /* number of arguments */ VistaIOPointer vector; /* vector of arguments */

} VistaIOArgVector;

#define VistaIORequiredOpt ((VistaIOBoolean *) ...)
#define VistaIOOptionalOpt ((VistaIOBoolean *) ...)

DESCRIPTION

Routines for parsing command line options and reporting help information on command usage require a description of a program's valid options. That description is a table whose entries are VistaIOOptionDescRec records. Each table entry describes a single option. This manual page describes how table entries should be set up to describe options of various forms.

An option appears in a command line as an argument of the form -keyword; it may be followed by additional arguments that supply values for the option. The keyword field of a VistaIOOptionDescRec contains the keyword used to identify that option (without the leading ``-'' character). On a command line this keyword can be entered in abbreviated form as long as the abbreviation is unambiguous --- i.e., it matches the first characters of only a single option keyword.

An option is used to communicate one or more values to a program. These values are of the type indicated by the repn field, which contains one of the constants VistaIOBitRepn, VistaIOUByteRepn, VistaIOSByteRepn, VistaIOShortRepn, VistaIOLongRepn, VistaIOFloatRepn, VistaIODoubleRepn, VistaIOBooleanRepn, or VistaIOStringRepn.

The number field indicates how many values are to be entered with the option. If number is positive, exactly that many values are to be supplied on the command line. If number is zero, any number of values may be supplied (including none at all).

The value field specifies where the entered values are to be stored. If number is positive, value points to a vector of number entries of the type indicated by the repn field. (E.g., if number is 2 and repn is VistaIOShortRepn then value points to a vector of two VistaIOShort's.)

If number is zero, value points to a variable of type VistaIOArgVector, which is a structure that describes a variable length vector. This structure needn't be initialized prior to parsing a program's command line options; rather, its fields are set during parsing to indicate the number of values actually found and the location of memory allocated to contain those values. The structure's number field specifies the number of values found. Its vector field points to a vector of number elements of the type specified by repn.

The found field of a VistaIOOptionDescRec indicates whether an option is required (must be specified on the command line) or optional (need not be specified). To signal a required option (oxymoron noted), found should contain the value VistaIORequiredOpt. To signal an optional option (redundancy noted), found should contain VistaIOOptionalOpt, or the address of a VistaIOBoolean variable. When a command line is parsed the VistaIOBoolean variable will be set to TRUE if the option is encountered, and FALSE if it is not.

An option's values are entered as command line arguments in a form that depends on the option's repn field:

VistaIOBitRepn through VistaIOLongRepn

Each value may be an integer number with an optional sign. If its first digit is 0, it is assumed to be an octal number. If it begins with 0x or 0X (following any sign), it is assumed to be a hexadecimal number. Otherwise, it is assumed to be a decimal number.

VistaIOFloatRepn or VistaIODoubleRepn

Each value may be a floating-point number.

VistaIOBooleanRepn

Each value may be one of the keywords false, no, or off (representing FALSE), or true, yes, or on (representing TRUE). In addition, if a Boolean option requires a single value and the option keyword is not followed by a recognized value keyword, a value of TRUE is assumed.

VistaIOStringRepn

Each value is any command line argument not starting with a single ``-'' character. However, an argument consisting only of ``-'' is interpreted as a string value, and an argument beginning with at least two ``-'' characters is interpreted as a string value beginning with one fewer ``-''. These conventions allow string values to be distinguished from options while still permitting entry of any string value desired.

One may specify a dictionary of keywords to supplement the recognized forms of option values. Dictionaries are described by the VistaIOdictionary(3) manual page. The dict field of the VistaIOOptionDescRec points to such a dictionary, or it contains NULL if there is no dictionary of keywords for the option's values. The example below demonstrates how a dictionary is supplied.

Finally, the blurb field of the VistaIOOptionDescRec contains a short string describing the purpose of the option or the form of its value arguments. This string will be included when any help information about command usage is printed.

EXAMPLES

Consider a program that accepts the following options:

-in

Optional, and followed by any number of string values.

-out

Optional, and followed by a single string value.

-color

Required, and followed by one of the keywords red, green, or blue.

-scale

Optional, and followed by two floating-point numbers. If not specified, this option's values should both default to 1.0.

-iff

An optional boolean flag.

The following code fragment defines an option table for this program:

static VistaIOArgVector in_args;
static VistaIOString out_arg;
static VistaIOLong color_arg;
static VistaIOFloat scale_args[2] = { 1.0, 1.0 };
static VistaIOBoolean iff_arg = FALSE;
static VistaIOBoolean in_found, out_found;
static VistaIODictEntry dictionary[] = {
{ "red", 0 },
{ "blue", 1 },
{ "green", 2 },
{ NULL }

};
static VistaIOOptionDescRec options[] = {
{ "in", VistaIOStringRepn, 0, & in_args, & in_found, NULL,
    "Image to be processed" },
{ "out", VistaIOStringRepn, 1, & out_arg, & out_found, NULL,
    "File to receive result" },
{ "color", VistaIOLongRepn, 1, & color, VistaIORequiredOpt, & dictionary,
    "Color band" },
{ "scale", VistaIOFloatRepn, 2, scale_args, VistaIOOptionalOpt, NULL,
    "Scaling in each dimension" },
{ "iff", VistaIOBooleanRepn, 1, & iff_arg, VistaIOOptionalOpt, NULL,
    "Output in UBC IFF format" }

};

This program may be invoked with any of the following commands:

program -color red

program -in file1 file2 -color red

program -in - -out file3 -color blue -scale 0.5 0.5

program -color green -iff

program -iff false -color red

AUTHOR

Art Pope <[email protected]>

Adaption to vistaio: Gert Wollny <[email protected]>