[ < ] [ > ]   [ << ] [ 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] [ ? ]

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