Aargh
The IntOpt Element
The IntOpt element defines a integer option, i.e. an option that takes a
non-negative integer as an argument. For example:
<IntOpt letter="i" name="sample_int">
<Range min="1" max="6"/>
<Required/>
</IntOpt>
Attributes
In addition to the letter and name attributes, an IntOpt element may
also carry a default attribute. For example:
<IntOpt letter="u" name="universe" default="42"/>
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 zero. The
default attribute has no effect if the <Required/> or
<Multiples/> element is present.
Enclosed Elements
The IntOpt element may enclose any combination of three optional elements,
of which each may occur no more than once within a given IntOpt aggregate:
-
The Range 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 values,
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.
Generated Members
For C, the generated code will provide two members related to an
IntOpt:
-
By default: an unsigned long whose name is the name of the option,
populated with the value of the options argument. If multiple occurrences
of the option are allowed (see below): a pointer to the first node in a
singly-linked list of unsigned longs. 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 indicate whether the option
is present on the command line. This member enables you to distinguish
between an option with an argument equal to the default value and an absent
option that has defaulted.
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 an unsigned long or, if multiple occurrences
of the option are allowed (see below), an STL vector of unsigned longs.
-
A const public member function returning the data member just described,
either by value (for a single unsigned long) or by const reference
(for a vector of unsigned longs). 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;
unsigned long 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.
