Get Teem at SourceForge.net. Fast, secure and Free Open Source software downloads
teem / hest

  Terminology

In order to describe and document hest, first some terminology:

An example (arg = argument, parm = parameter):

                  arg 
   arg    arg  arg |  arg arg arg args    arg     arg   arg
    |      |    |  |   |   |   |    |      |       |     |
composite -verb 3 -bg 255 255 255 *.pgm bingo.pgm -o final.pgm
           |    |  |  \_________/   |      |       |     |
         flag parm flag   parms    parms  parm    flag  parm
         \_______/ \__________/    \_________/    \________/
           option     option         option         option
The fact that "*.pgm bingo.pgm" constitute one option, and a seperate option from "-bg 255 255 255" would be known from the information about options specified by the caller of the hest functions.

hest allows parsing of flagged and unflagged, variable and fixed parameter options. After the flagged options and their associated parameters are parsed, they are removed from the list of command line arguments, and remaining arguments are parsed as the unflagged options. The immediate practical implication of this is that you can have at most one unflagged variable parameter option. You can have any number of flagged variable parameter options. If an option does not appear, information is set according to given default values. Options (specifically, their parameters) can be of type boolean, int, float, double, char, and string (a "char *"). The booleans are actually treated as integers, but "on", "yes", "y", "true", "t", and "1" are all parsed as 1, and "off", "no", "n", "false", "f", and "0" are all parsed as 0.

The different set of possibilities created by having any number of parameters can be organized according to "min" and "max" integers, which are the minimum and maximum number of parameters to be associated with a flag. Fixed parameter options have min == max, variable parameter options have min < max. The grid of possibilities is here:

min=
0
1 2 3 4
max=
0
stand-alone
flag
1 single
variable
parm
single
fixed
parm
2 0-2
variable
parms
1-2
variable
parms
2
fixed
parms
3 0-3
variable
parms
1-3
variable
parms
2-3
variable
parms
3
fixed
parms
4 0-4
variable
parms
1-4
variable
parms
2-4
variable
parms
3-4
variable
parms
4
fixed
parms

There are, then, five different kinds of options which the hest deals with, and treats seperately (the kind is independent of type: boolean, int, float, etc.):

  1. Stand-alone flag: Because there are no parameters associated with a stand-alone flag, whether or not the flag appears on the command line is all that matters.
  2. Single fixed parameter: The option has exactly one parameter.
  3. Multiple fixed parameters: There are a fixed number (greater than 1) of parameters in the option. Specifying a background color (as with "-bg 255 255 255") might fall in this category.
  4. Single variable parameter: This is useful for situations where a user may want to enable some behavior, or enable some behavior to a specified level. For example, verboseness of diagnostic error messages can be controlled with "-v": for no verboseness, "-v" is not given; for some verboseness, "-v" alone can be used; for a specific level of verbosness, "-v 3" (for example) can be used.
  5. Multiple variable parameters: The option can have a varying number of parameters, and the maximum number is greater than 1. The list of filenames resulting from shell expansion (as from "-i *.txt") would fall in this category. The end of a variable parameter list is signalled by another recognized flag, or the end of the command line.
Recall that options can be flagged or unflagged. The only kind of option which cannot be unflagged is the stand-alone flag; all other kinds of options can be either flagged or unflagged. The ability to deal with different combinations of flagged and unflagged, single and multiple, fixed and variable options leads, unfortunately, to somewhat complicated rules on the behavior of the hest functions, such as how the default information is handled, how memory is allocated, and what variables are required and not. The simplest behavior is for kinds 1 through 3 above; things get a little weird for 4 and 5. The usage and behavior will be documented in terms of the different kinds shown above, and in terms of the terminology defined above.