In order to describe and document hest, first some
- 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
- 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
An example (arg = argument, parm = parameter):
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
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
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.):
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
- 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.
- Single fixed parameter: The option has exactly one parameter.
- 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.
- 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.
- 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