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.

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