--- name: "VistaIOoption" section: "3" platform: "linux" package: "libvistaio-dev" version: "1.2.19-3+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/VistaIOoption" --- # VistaIOoption(3) table describing command line options ## NAME VistaIOoption - table describing command line options ## SYNOPSIS ``` #include ``` ``` 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)](/VistaIOdictionary/3.md)** **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)](/VistaIOParseCommand/3.md), [**VistaIOPrintOptions**(3)](/VistaIOPrintOptions/3.md), **VistaIOPrintOptionValue**(3), [**VistaIOReportBadArgs**(3)](/VistaIOReportBadArgs/3.md), [**VistaIOReportUsage**(3)](/VistaIOReportUsage/3.md), [**VistaIOIdentifyFiles**(3)](/VistaIOIdentifyFiles/3.md),\ [**VistaIOdictionary**(3)](/VistaIOdictionary/3.md), ## AUTHOR **Art Pope \** **Adaption to vistaio: Gert Wollny \**