

8.4 Bit Maps and Enumerations

AutoGen provides two templates for managing enumerations and bit maps (flag words). They produce an enumeration of the enum or #defines for the bit maps, plus conversion functions for converting a string into one of these values or converting one of these values into a human readable string. Finally, for enumerations, you may specify one or more sets of dispatching functions that will be selected by identifying a keyword prefix of a string (see section the dispatch attribute in Strings to Enums and Back).

There is a separate project that produces a GDB add-on that will add these capabilities into GDB for bit masks. (GDB does just fine with enumerations.)


8.4.1 Enumerations


Produce an enumeration for a list of input “cmd”s (names). Optionally, produce functions to:

The header file produced will contain the enumeration and declarations for the optional procedures. The code (‘.c’) file will contain these optional procedures, but can be omitted if the no-code attribute is specified.

The following attributes are recognized with the str2enum template:


You must provide a series of these attributes: they specify the list of names used in the enumeration. Specific values for the names may be specified by specifying a numeric index for these attributes. e.g. cmd[5] = mumble; will cause


to be inserted into the enumeration. Do not specify a value of “invalid”, unless you specify the invalid-name attribute. (In that case, do not specify a cmd value that matches the invalid-name value.)


This specifies the first segment of each enumeration name. If not specified, the first segment of the enumeration definition file name will be used. e.g. ‘foo-bar.def’ will default to a FOO prefix.


Normally, there is a second constant segment following the prefix. If not specified, it will be CMD, so if both prefix and type were to default from ‘foo-bar.def’, you will have enumeration values prefixed with FOO_CMD_. If specified as the empty string, there will be no “type” component to the name and the default constant prefix will thus be FOO_.


This specifies the base name of the output files, enumeration type and the translation functions. The default is to use the basename(3) of the definition file. e.g. ‘foo-bar.def’ results in a base-name of foo-bar.


The default invalid value is zero. Sometimes, it is useful for zero to be valid. If so, you can specify ~0 or the empty string to be invalid. The empty string will cause the enumeration count (maximum value plus 1) to be the invalid value.


By default, the invalid value is emitted into the enumeration as FOO_INVALID_CMD. Specifying this attribute will replace INVALID with whatever you place in this attribute.


Additional text to insert into the code or header file.


Which file to insert the text into. There are four choices, only two of which are relevant for the ‘str2enum’ template: “enum-header”, “enum-code”, “mask-header” or “mask-code”.


The text to insert.


8.4.2 Strings to Enums and Back

A continuation of the attributes for the ‘str2enum.tpl’ template.




Do not emit the enumeration to name function.







You have four choices with the length attribute:






















AutoGen Definitions str2enum;
cmd = one, two; invalid-name = oops;

will produce a header containing:

typedef enum {
    SAMP_OOPS_CMD = 0,
    SAMP_CMD_ONE      = 1,
    SAMP_CMD_TWO      = 2,
} samp_chk_enum_t;

extern samp_chk_enum_t
find_samp_chk_cmd(char const * str, size_t len);

typedef void(samp_chk_handler_t)(
    samp_chk_enum_t id, char const * str);

        hdl_oops_cmd, hdl_one_cmd,  hdl_two_cmd;

extern void
disp_samp_chk(char * str, size_t len);

extern char const *
samp_chk_name(samp_chk_enum_t id);


8.4.3 Bit Maps and Masks



There are a few constraints on the names allowed:




a special name for a sub-collection of the mask bits





A mask of all bits in the collection is always generated.

