Provided by: libvistaio-dev_1.2.19-1_amd64 bug

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>