[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.4.1 Enumerations

str2enum.tpl

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:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Bruce Korb on October 16, 2013 using texi2html 1.82.