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

  Usage Details

Knowing the terminology and usage basics, here is a detailed description of each of the different kinds of options which hest can deal with. This is the information you'd need to set the elements of a hestOpt struct, either by static initialization, or by a call to hestOptAdd(). Essentially, this page describes in detail the somewhat complicated behavior of the hestParse() function.

  1. The first thing that happens in hestParse() is to verify that the hestOpt array itself is valid. This is the same check that hestOptCheck() does.
  2. The response file arguments are parsed. But if the respFileEnable flag of the hestParm struct is zero (false), then no response files are parsed, and this step is skipped. Otherwise, any argument that starts with the "@" character is assumed to be a response file name (But the role of @ is not set in stone; you can alter either the respFileFlag field in the hestParm struct, or you can alter the hestRespFileFlag global.) You can have as many response file arguments on the command line as you want, where ever you want. The response files are parsed as follows:
  3. The flagged options (the flag and its parameters) are extracted from the command line. hestParse() has to decide which arguments belong to which flagged options, so that it can extract what it should. For stand-alone flags, single fixed parameter options, and multiple fixed parameter options, this is simple. For single and multiple variable parameter options, it uses four ways to find the end of the parameter list: A flagged option can appear multiple times on the command-line, or in a response file and the command-line. Only the last occurance will be used. Because the arguments found in response files are effectively inserted into the command line at the point the response file is named, this means that the original command line can over-ride, or can be over-ridden by, arguments in the response files, depending on the ordering.
  4. The remaining arguments are parsed as the unflagged options. Unlike with flagged options, the order of the unflaged options in the hestOpt array is significant: the hestOpt array will be traversed, and each unflagged option will cause some arguments to be extracted from the command line. Again, there is the same problem of determining which arguments belong to which options. Currently, for simplicity's sake, there is a simple rule: you can have only one variable parameter unflagged option. This means there is an unambiguous way to parse the remaining arguments into parameters for the different options.
All the actions described above are performed on copies of the given argc, argv arguments passed to hestParse(). They are left untouched.

Once values have been parsed and hestParse() has returned, there is no way of knowing whether the values set came from the command-line or the given default information.

The strings from the comman-line are parsed into values using the airParseStr[] array of functions. These are essentially wrappers around the system's sscanf function, with two exceptions:

  1. When parsing floats or doubles, these will recognize a strings containing "nan", "inf", "+inf", and "-inf" as the IEEE 754 special floating point values.
  2. The booleans are actually treated as integers, but "on", "yes", "y", "true", "t", and "1" are all parsed (in a case-insensitive manner) as 1, and "off", "no", "n", "false", "f", and "0" are all parsed as 0.

For reference, here again is the relevent section of the hestOpt struct definition (from hest.h):

  char *flag,           /* how the option is identified on the cmd line */
    *name;              /* simple description of option's parameter(s) */
  int type,             /* type of option (from airType enum) */
    min, max;           /* min and max # of parameters for option */
  void *valueP;         /* storage of parsed values */
  char *dflt,           /* default value written out as string */
    *info;              /* description to be printed with "glossary" info */
  int *sawP,            /* used ONLY for multiple variable parameter options
                           (min < max > 2): storage of # of parsed values */
Some of the fields in the hestOpt struct are the same regardless of the kind of option, or are the same for nearly all kinds of options. They are described here, and not in the detailed explanation of each kind (below). Exceptions to these general rules are noted below.
Stand-alone flags: (min == 0; max == 0)

Single fixed parameter: (min == 1; max == 1)

Multiple fixed parameters: (min == max; max > 1)

Single variable parameter: (min == 0; max == 1)

Multiple variable parameters: (min < max; max > 1)

Note: If you know ahead of time that you want at most, say, five parameters for an option, then you can set max as 5. However, if there is no obvious upper limit to the number of parameters, then set max to -1. hest internally interprets this as INT_MAX, from /usr/include/limits.h. Setting min to 1 and max to -1 is the best way to support parsing the output of command-line filename expansion, as from "*.txt"