---

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.