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

‘str2enum.tpl’

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

• convert a string to an enumeration
• convert an enumeration value into a string
• invoke a function based on the first token name found in a string

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:

‘cmd’

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

FOO_CMD_MUMBLE = 5

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.)

‘prefix’

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.

‘type’

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_.

‘base-name’

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.

‘invalid-val’

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.

‘invalid-name’

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.

‘add-on-text’

Additional text to insert into the code or header file.

‘ao-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”.

‘ao-text’

The text to insert.

8.4.2 Strings to Enums and Back

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

‘no-code’

Do not emit any string to enumeration or enumeration to string code at all. If this is specified, the remainder of the attributes have no effect.

‘no-name’

Do not emit the enumeration to name function.

‘no-case’

When looking up a string, the case of the input string is ignored.

‘alias’

A single punctuation character can be interpreted as a command. The first character of this attribute is the aliased character and the remainder the aliased-to command. e.g. “#comment” makes ’#’ an alias for the comment command. “#comment” must still be listed in the cmd attributes.

‘length’

Specify how lengths are to be handled. Under the covers, gperf(1) is used to map a string to an enumeration value. The code it produces requires the string length to be passed in. You may pass in the length yourself, or the generated code may figure it out, or you may ask for that length to be returned back after being figured out.

You have four choices with the length attribute:

• Do not specify it. You will need to provide the length.
• Specify “provided”. You will need to provide the length.
• Specify “returned”. You must pass a pointer to a size_t object. If the name is found, the length will be put there.
• Specify an empty string. The generated code will compute the length and that computed length will not be returned. The length parameter may be omitted. If the input strings contain only enumeration names, then this would be sufficient.
• Specifying anything else is undefined.

‘partial’

Normally, a name must fully match to be found successfully. This attribute causes the generated code to look for partial matches if the full match gperf function fails. Partial matches must be at least two characters long.

‘undef-str’

by default, the display string for an undefined value is “* UNDEFINED *”. Use this to change that.

‘equate’

A series of punctuation characters considered equivalent. Typically, “-_” but sometimes (Tandem) “-_^”. Do not use ’#’ in the list of characters.

‘dispatch’

A lookup procedure will call a dispatch function for the procedure named after the keyword identified at the start of a string. Other than as specially noted below, for every named “cmd”, must have a handling function, plus another function to handle errors, with “invalid” (or the invalid-name value) as the cmd name. Multiple dispatch definitions will produce multiple dispatching functions, each with (potentially) unique argument lists and return types.

You may also use add-on-text to “#define” one function to another, thus allowing one function to handle multiple keywords or commands. The d-nam and d-ret attributes are required. The d-arg, d-omit and d-only attributes are optional:

‘d-nam’

This must be a printf format string with one formatting element: %s. The %s will be replaced by each cmd name. The %s will be stripped and the result will be combined with the base name to construct the dispatch procedure name.

‘d-ret’

The return type of the dispatched function, even if “void”.

‘d-arg’

If there are additional arguments that are to be passed through to the dispatched function, specify this as though it were part of the procedure header. (It will be glued into the dispatching function as is and sedded into what is needed for the dispatched function.)

‘d-omit’

Instead of providing handling functions for all of the cmd names, the invalid function will be called for omitted command codes.

‘d-only’

You need only provide functions for the names listed by d-only, plus the “invalid” name. All other command values will trigger calls to the invalid handling function. Note that the invalid call can distinguish from a command that could not be found by examining the value of its first (id) argument.

The handler functions will have the command enumeration as its first first argument, a pointer to a constant string that will be the character after the parsed command (keyword) name, plus any d-arg arguments that follow that.

As an example, a file ‘samp-chk.def’ containing this:

AutoGen Definitions str2enum; cmd = one, two; invalid-name = oops; dispatch = { d-nam = 'hdl_%s_cmd'; d-ret = void; };

will produce a header containing:

typedef enum { SAMP_OOPS_CMD = 0, SAMP_CMD_ONE = 1, SAMP_CMD_TWO = 2, SAMP_COUNT_CMD } 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); samp_chk_handler_t 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);

• find_samp_chk_cmd will look up a len byte str and return the corresponding samp_chk_enum_t value. That value is SAMP_OOPS_CMD if the string is not “one” or “two”.
• samp_chk_handler_t is the type of the callback procedures. Three must be provided for the dispatching function to call: hdl_oops_cmd, hdl_one_cmd and hdl_two_cmd. hdl_oops_cmd will receive calls when the string does not match.
• disp_samp_chk this function will call the handler function and return whatever the handler returns. In this case, it is void.
• samp_chk_name will return a string corresponding to the enumeration value argument. If the value is not valid, “* UNDEFINED *” (or the value of undef-str) is used.

8.4.3 Bit Maps and Masks

‘str2mask.tpl’

This template leverages highly off of enumerations (see section Enumerations). It will produce a header file with bit masks defined for each bit specified with a cmd attribute. 63 is the highest legal bit number because this template has not been extended to cope with multiple word masks. (Patches would be welcome.)

There are a few constraints on the names allowed:

• names are constrained to alphanumerics and the underscore
• aliases are not allowed
• dispatch procedures are not allowed

no-code and no-name are honored. dispatch is not. The lookup function will examine each token in an input string, determine which bit is specified and add it into a result. The names may be prefixed with a hyphen (-) or tilde (~) to remove the bit(s) from the cumulative result. If the string begins with a plus (+), hyphen or tilde, a “base value” parameter is used for the starting mask, otherwise the conversion starts with zero.

Beyond the enumeration attributes that are used (or ignored), the ‘str2mask’ template accepts a mask attribute. It takes a few “subattributes”:

‘m-name’

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

‘m-bit’

The name of each previously defined bit(s). If the desired previously defined value is a mask, that m-name must be suffixed with “-mask”.

‘m-invert’

When all done collecting the bits, x-or the value with the mask of all the bits in the collection.

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

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.