Provided by: libvistaio-dev_1.2.19-1_amd64 
NAME
VistaIOoption - table describing command line options
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
SEE ALSO
VistaIOParseCommand(3), VistaIOPrintOptions(3), VistaIOPrintOptionValue(3),
VistaIOReportBadArgs(3), VistaIOReportUsage(3), VistaIOIdentifyFiles(3),
VistaIOdictionary(3),
AUTHOR
Art Pope <pope@cs.ubc.ca>
Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>