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



hest depends on the air library for the airType enum, the airParseStr[] array of parsing functions, the airStrtok() and airStrntok() functions, and the airMop functionality (used for memory management).


The hestOpt struct is the important one: the struct contains all the information and state used to deal with identifying and parsing one command-line option. The last two members of the struct are used by hestParse() for book-keeping, and should be of no interest to hest users.

typedef struct {
  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 */

  /* --------------------- end of user-defined fields */

    kind,               /* what kind of option is this, based on min and max,
			   set by hestParse() (actually _hestPanic()),
			   later used by hestFree():
			   1: min == max == 0
			      a binary flag, no parameters
			   2: min == max == 1
                              one required parameter
			   3: min == max >= 2
                              multiple required parameters
			   4: min == 0; max == 1;
                              one optional parameter
			   5: max - min >= 1; max >= 2 
                              multiple optional parameter */
    alloc;              /* information about whether flag is non-NULL, and what
			   parameters were used, that determines whether or
			   not memory was allocated by hestParse(); info
			   later used by hestParseFree():
			   0: no free()ing needed
			   1: free(*valueP), either because it is a single
			      string, or because was a dynamically allocated
			      array of non-strings
			   2: free((*valueP)[i]), because they are elements
			      of a fixed-length array of strings
			   3: free((*valueP)[i]) and free(*valueP), because
 			      it is a dynamically allocated array of strings */
} hestOpt;
All the hest functions which take a hestOpt* has one of their arguments expect an array of these structs (and not an array of pointers to the structs). Such an array can be created statically or dynamically, see usage basics. The hest functions assume that the array is terminated by a struct who's tag and name are both NULL, and who's type is zero (not a valid type value in the airType enum).

The hestParm struct contains various parameters affecting the behavior of the hest functions, is the place for future customizations and extra control. If you are happy with the defaults, you can always pass NULL instead of a hestParm pointer.

typedef struct {
  int verbosity,        /* verbose diagnostic messages to stdout */
    respFileEnable,     /* whether or not to use response files */
    columns;            /* number of printable columns in output */
  char respFileFlag,    /* the character at the beginning of an argument
			   indicating that this is a response file name */
    respFileComment,    /* comment character for the repose files */
    varParamStopFlag;   /* prefixed by '-' to form the flag which signals
			   the end of a flagged variable parameter option
			   (single or multiple) */
} hestParm;


These define the default behavior that you get by passing a NULL hestParm to any of the hest functions. When a hestParmNew() creates a new hestParm, the fields are initialized to the values shown below. This is an extract from the defaults.c file which defines these variables:

int hestVerbosity = 0;
int hestRespFileEnable = AIR_FALSE;
int hestColumns = 80;
char hestRespFileFlag = '@';
char hestRespFileComment = '#';
char hestVarParamStopFlag = '-';
Note that response files are not enabled by default. The hestColumns variable controls word wrap-around in the printing that hestInfo(), hestUsage() and hestGlossary do. The hestRespFileFlag character should be chosen to be a very very unlikely first character of any unflagged parameters.
The Important Functions:

Note: See the examples page for demonstrations of the output of the functions below for a variety of different options.

int hestParse(hestOpt *opt, int argc, char **argv,
              char **errP, hestParm *parm);

void hestParseFree(hestOpt *opt);

void hestUsage(FILE *file, hestOpt *opt,
               char *argv0, hestParm *parm);

void hestGlossary(FILE *file, hestOpt *opt,
                  hestParm *parm);

void hestInfo(FILE *file, char *argv0,
              char *info, hestParm *parm);

Utility Functions:

hestParm *hestParmNew();
hestParm *hestParmFree(hestParm *parm);

void hestOptAdd(hestOpt **optP, char *flag, char *name,
                int type, int min, int max,
                void *valueP, char *dflt, char *info, ...);

int hestOptCheck(hestOpt *opt, char **errP);

hestOpt *hestOptFree(hestOpt *opt);