Aargh -- Automated Argument Helper

Aargh

The StringOpt Element

The StringOpt element defines a string option, i.e. an option that takes an arbitrary character string as an argument. For example:

<StringOpt letter="d" name="sample_dates">
	<Length max="9" min="3"/>
	<Required/>
	<Multiple/>
	<Validator name="val_date" linkage="C"/>
</StringOpt>

Attributes

In addition to the letter and name attributes, a StringOpt element may also carry a default attribute. For example:

<StringOpt letter="h" name="host" default="localhost"/>

If the option is not present on the command line, the generated code will store the value of the default attribute as the argument of the option. If no default attribute is supplied, the default default is an empty string. The default attribute has no effect if the <Required/> or <Multiples/> element is present.

Enclosed Elements

The StringOpt element may enclose any combination of four optional elements, of which each may occur no more than once within a given StringOpt aggregate:

The Length element may carry either or both of two attributes, max and min, whose values must be non-negative integers. The generated code will enforce these values as the maximum and minimum lengths, respectively, of the option's argument. If not otherwise specified, their values default to ULONG_MAX (from limits.h) and zero. For obvious reasons, the value of the max attribute must be equal to or greater than the value of the min attribute.

The Required element has no attributes. When this element is present, the generated code will require that the associated option be present. In other words, the option will not be optional.

The Multiple element also has no attributes. When this element is present, the generated code will accept multiple occurences of the associated option, and store the option arguments in a linked list (for C) or an STL vector (for C++). Otherwise the generated code will not allow the option to occur more than once.

The Validator element carries a single required name attribute and an optional linkage attribute. It identifies a user-defined function to validate the argument of the option. This validation is not applied to the default argument when the option is omitted from the command line.
The value of the name attribute is the name of a validation function of type int. This function should accept a const char * as its parameter, return zero for a valid argument, and return non-zero for an invalid argument. Typically it should issue specific error messages to standard error as needed, since the generated code will issue only a generic error message complaining about an invalid argument. Aargh does not try to verify that the value of the name attribute is a valid function name in the target language.
The linkage attribute is useful only for generating C++. Its value specifies the linkage type of the validating function. In particular, if the value is "C", then the generated header file will declare the validator function as extern "C". If you specify "C++", or if you omit the linkage attribute, aargh will omit the extern qualifier and linkage specification from the generated header file. You can use other linkage types, such as "pascal", if your C++ compiler supports them.

Generated Members

For C, the generated code will provide two members related to a StringOpt:

By default: a character pointer whose name is the name of the option. It points into the original argv[] array to the argument of the option. When multiple occurrences are allowed (see below): a pointer to the first node in a linked list of such pointers. Its name is the name of the option, followed by "_list".

A member of type int whose name is the name of the option followed by "_found". It is used as a boolean to distinguish between an option whose argument is equal to the default value and an option that is omitted and therefore carries the default value.

For C++, the generated code will provide two private data members corresponding to the C members described above, plus two const member functions to access them:

A private data member whose name is the name of the option, followed by an underscore. It is either a string or, if multiple occurrences are allowed, an STL vector of strings.

A public member function returning a const reference to the private data member just described. Its name is the same as the name of the option.

A private data member of type bool, whose name is the name of the option followed by "_found_", indicating whether the option appeared on the command line.

A const boolean public member function whose name is the name of the option followed by "_found". It returns the value of the corresponding boolean data member.

When multiple occurrences are allowed, the generated code C defines a struct similar to the following to serve as a node in a linked list:

struct optionname_node
{
        struct optionname_node * pNext;
        char * value;
};

...where optionname is the name of the option. The nodes are linked in the order in which the options occur. The first node represents the first occurrence, the second represents the second, and so on.

Deallocating Multiples

If any option allows multiple occurrences, the generated C code provides a function that clears all the linked lists and deallocates the nodes. The name of this function is "clear_Opts", or "clear_X" where "X" is the struct name specified by the Structure element. For example:

void clear_Opts( struct Opts * pOpts );

For C++ no such function is necessary. The list of values is stored in an STL vector, which is automatically cleared by the destructor.