8.4.2 Strings to Enums and Back

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.

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.