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>