teem	/	hest	Terminology

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

• The entire command line is a list of arguments. Each element of the argv[] array is an argument.
• The things like "-v" and "-size", by which you indicate what information you're giving, are called flags.
• The set of arguments following the flag, and logically associated with it, are the flag's parameters. Flags can have zero, one, or more parameters.
• The flag, and its associated parameters, are together called an option. The unfortunate aspect of this word choice is that options can be either mandatory or, well, optional.
• Not all options start with a flag; the parameters for an option can just start at some assumed position along the command line. These are unflagged options. Obviously, unflagged options must have one or more parameters.
• Some options (both flagged and unflagged) can have a variable number of parameters. These are variable parameter options. If an option's number of parameters is not variable, it is a fixed parameter option.

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

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:

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.