VistaIOoption - table describing command line options

       Art Pope <pope@cs.ubc.ca>

       Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

VistaIO Version 1.2.14                             6 June 1994                                  VistaIOoption(3)

       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.

       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:

              staticVistaIOArgVectorin_args;staticVistaIOStringout_arg;staticVistaIOLongcolor_arg;staticVistaIOFloatscale_args[2]={1.0,1.0};staticVistaIOBooleaniff_arg=FALSE;staticVistaIOBooleanin_found,out_found;staticVistaIODictEntrydictionary[]={{"red",0},{"blue",1},{"green",2},{NULL}};staticVistaIOOptionDescRecoptions[]={{"in",VistaIOStringRepn,0,&in_args,&in_found,NULL,"Imagetobeprocessed"},{"out",VistaIOStringRepn,1,&out_arg,&out_found,NULL,"Filetoreceiveresult"},{"color",VistaIOLongRepn,1,&color,VistaIORequiredOpt,&dictionary,"Colorband"},{"scale",VistaIOFloatRepn,2,scale_args,VistaIOOptionalOpt,NULL,"Scalingineachdimension"},{"iff",VistaIOBooleanRepn,1,&iff_arg,VistaIOOptionalOpt,NULL,"OutputinUBCIFFformat"}};

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

              program-colorredprogram-infile1file2-colorredprogram-in--outfile3-colorblue-scale0.50.5program-colorgreen-iffprogram-ifffalse-colorred

       VistaIOoption - table describing command line options

VistaIOParseCommand(3), VistaIOPrintOptions(3), VistaIOPrintOptionValue(3), VistaIOReportBadArgs(3),
       VistaIOReportUsage(3), VistaIOIdentifyFiles(3),
       VistaIOdictionary(3),

#include<vistaio.h>typedefstruct{VistaIOStringConstkeyword;/*keywordsignalingoption*/VistaIORepnKindrepn;/*typeofvaluesuppliedbyoption*/intnumber;/*numberofvaluessupplied*/VistaIOPointervalue;/*locationforstoringvalue(s)*/VistaIOBoolean*found;/*whetheroptionalargfound*/VistaIODictEntry*dict;/*optionaldictofvaluekeywords*/VistaIOStringConstblurb;/*on-linehelpblurb*/}VistaIOOptionDescRec;typedefstruct{intnumber;/*numberofarguments*/VistaIOPointervector;/*vectorofarguments*/}VistaIOArgVector;#defineVistaIORequiredOpt((VistaIOBoolean*) ...)#defineVistaIOOptionalOpt((VistaIOBoolean*) ...)