1@ignore 2 3This file is part of AutoGen. 4AutoGen is free software. 5AutoGen is Copyright (C) 1992-2018 by Bruce Korb - all rights reserved 6 7AutoGen is free software: you can redistribute it and/or modify it 8under the terms of the GNU General Public License as published by the 9Free Software Foundation, either version 3 of the License, or 10(at your option) any later version. 11 12AutoGen is distributed in the hope that it will be useful, but 13WITHOUT ANY WARRANTY; without even the implied warranty of 14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 15See the GNU General Public License for more details. 16 17You should have received a copy of the GNU General Public License along 18with this program. If not, see <http://www.gnu.org/licenses/>. 19 20This file has the following md5sum: 21 2243b91e8ca915626ed3818ffb1b71248b COPYING.gplv3 23 24@end ignore 25@node Bit Maps 26@section Bit Maps and Enumerations 27 28AutoGen provides two templates for managing enumerations and bit maps 29(flag words). They produce an enumeration of the enum or @code{#define}s 30for the bit maps, plus conversion functions for converting a string into 31one of these values or converting one of these values into a human readable 32string. Finally, for enumerations, you may specify one or more sets of 33dispatching functions that will be selected by identifying a keyword 34prefix of a string (@pxref{enum-code, the @i{dispatch} attribute in 35Strings to Enums and Back}). 36 37There is a separate project that produces a GDB add-on that 38will add these capabilities into GDB for bit masks. (GDB does just fine 39with enumerations.) 40 41@menu 42* enums:: Enumerations 43* enum-code:: Strings to Enums and Back 44* masks:: Bit Maps and Masks 45@end menu 46 47@node enums 48@subsection Enumerations 49 50@file{str2enum.tpl} 51 52Produce an enumeration for a list of input ``cmd''s (names). 53Optionally, produce functions to: 54 55@itemize @bullet 56@item 57convert a string to an enumeration 58@item 59convert an enumeration value into a string 60@item 61invoke a function based on the first token name found in a string 62@end itemize 63 64The header file produced will contain the enumeration and declarations 65for the optional procedures. The code (@file{.c}) file will contain 66these optional procedures, but can be omitted if the @code{no-code} 67attribute is specified. 68 69The following attributes are recognized with the @code{str2enum} template: 70 71@table @samp 72@item cmd 73You must provide a series of these attributes: they specify the list of 74names used in the enumeration. Specific values for the names may be 75specified by specifying a numeric index for these attributes. 76e.g. @code{cmd[5] = mumble;} will cause 77@example 78FOO_CMD_MUMBLE = 5 79@end example 80@noindent 81to be inserted into the enumeration. 82Do not specify a value of ``@t{invalid}'', unless you specify the 83@code{invalid-name} attribute. (In that case, do not specify a 84@code{cmd} value that matches the @code{invalid-name} value.) 85 86@item prefix 87This specifies the first segment of each enumeration name. 88If not specified, the first segment of the enumeration definition file name 89will be used. e.g. @file{foo-bar.def} will default to a @code{FOO} prefix. 90 91@item type 92Normally, there is a second constant segment following the prefix. If not 93specified, it will be @code{CMD}, so if both @code{prefix} and @code{type} 94were to default from @file{foo-bar.def}, you will have enumeration values 95prefixed with @code{FOO_CMD_}. If specified as the empty string, there will 96be no ``type'' component to the name and the default constant prefix will 97thus be @code{FOO_}. 98 99@item base-name 100This specifies the base name of the output files, enumeration type and the 101translation functions. The default is to use the @code{basename(3)} of 102the definition file. e.g. @file{foo-bar.def} results in a @code{base-name} 103of @code{foo-bar}. 104 105@item invalid-val 106The default invalid value is zero. Sometimes, it is useful for zero to be 107valid. If so, you can specify @t{~0} or the empty string to be invalid. 108The empty string will cause the enumeration count (maximum value plus 1) to 109be the invalid value. 110 111@item invalid-name 112By default, the invalid value is emitted into the enumeration as 113@code{FOO_INVALID_CMD}. Specifying this attribute will replace 114@code{INVALID} with whatever you place in this attribute. 115 116@item add-on-text 117Additional text to insert into the code or header file. 118 119@table @samp 120@item ao-file 121Which file to insert the text into. There are four choices, 122only two of which are relevant for the @file{str2enum} template: 123``@t{enum-header}'', ``@t{enum-code}'', ``@t{mask-header}'' or ``@t{mask-code}''. 124 125@item ao-text 126The text to insert. 127@end table 128@end table 129 130@c 131@c * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 132@c 133@node enum-code 134@subsection Strings to Enums and Back 135 136A continuation of the attributes for the @file{str2enum.tpl} template. 137 138@table @samp 139@item no-code 140Do not emit any string to enumeration or enumeration to string code at all. 141If this is specified, the remainder of the attributes have no effect. 142 143@item no-name 144Do not emit the enumeration to name function. 145 146@item no-case 147When looking up a string, the case of the input string is ignored. 148 149@item alias 150A single punctuation character can be interpreted as a command. The first 151character of this attribute is the aliased character and the remainder the 152aliased-to command. e.g. ``@t{#comment}'' makes '@t{#}' an alias for the 153@command{comment} command. ``@t{#comment}'' must still be listed in the 154@code{cmd} attributes. 155 156@item length 157Specify how lengths are to be handled. Under the covers, @command{gperf(1)} 158is used to map a string to an enumeration value. The code it produces 159requires the string length to be passed in. You may pass in the length 160yourself, or the generated code may figure it out, or you may ask for that 161length to be returned back after being figured out. 162 163You have four choices with the @code{length} attribute: 164 165@itemize @bullet 166@item 167Do not specify it. You will need to provide the length. 168@item 169Specify ``@t{provided}''. You will need to provide the length. 170@item 171Specify ``@t{returned}''. You must pass a pointer to a @t{size_t} object. 172If the name is found, the length will be put there. 173@item 174Specify an empty string. The generated code will compute the length and 175that computed length will not be returned. The length parameter may be 176omitted. If the input strings contain only enumeration names, then this 177would be sufficient. 178@item 179Specifying anything else is undefined. 180@end itemize 181 182@item partial 183Normally, a name must fully match to be found successfully. This attribute 184causes the generated code to look for partial matches if the full match 185@command{gperf} function fails. Partial matches must be at least two 186characters long. 187 188@item undef-str 189by default, the display string for an undefined value is 190``@t{* UNDEFINED *}''. Use this to change that. 191 192@item equate 193A series of punctuation characters considered equivalent. 194Typically, ``@t{-_}'' but sometimes (Tandem) ``@t{-_^}''. 195Do not use '@t{#}' in the list of characters. 196 197@item dispatch 198A lookup procedure will call a dispatch function for the procedure named 199after the keyword identified at the start of a string. Other than as 200specially noted below, for every named ``cmd'', must have a handling 201function, plus another function to handle errors, with ``invalid'' (or the 202@code{invalid-name} value) as the @code{cmd} name. Multiple @code{dispatch} 203definitions will produce multiple dispatching functions, each with 204(potentially) unique argument lists and return types. 205 206You may also use @code{add-on-text} to ``@t{#define}'' one function to 207another, thus allowing one function to handle multiple keywords or commands. 208The @code{d-nam} and @code{d-ret} attributes are required. The @code{d-arg}, 209@code{d-omit} and @code{d-only} attributes are optional: 210 211@table @samp 212@item d-nam 213This must be a printf format string with one formatting element: @code{%s}. 214The @code{%s} will be replaced by each @code{cmd} name. The @code{%s} will 215be stripped and the result will be combined with the base name to construct 216the dispatch procedure name. 217 218@item d-ret 219The return type of the dispatched function, even if ``@t{void}''. 220 221@item d-arg 222If there are additional arguments that are to be passed through to the 223dispatched function, specify this as though it were part of the procedure 224header. (It will be glued into the dispatching function as is and sedded 225into what is needed for the dispatched function.) 226 227@item d-omit 228Instead of providing handling functions for all of the @code{cmd} names, 229the invalid function will be called for omitted command codes. 230 231@item d-only 232You need only provide functions for the names listed by @code{d-only}, plus 233the ``invalid'' name. All other command values will trigger calls to 234the invalid handling function. Note that the invalid call can distinguish 235from a command that could not be found by examining the value of its 236first (@code{id}) argument. 237@end table 238 239The handler functions will have the command enumeration as its first first 240argument, a pointer to a constant string that will be the character 241@i{after} the parsed command (keyword) name, plus any @code{d-arg} arguments 242that follow that. 243 244@noindent 245As an example, a file @file{samp-chk.def} containing this: 246@example 247AutoGen Definitions str2enum; 248cmd = one, two; invalid-name = oops; 249dispatch = @{ d-nam = 'hdl_%s_cmd'; d-ret = void; @}; 250@end example 251@noindent 252will produce a header containing: 253@example 254typedef enum @{ 255 SAMP_OOPS_CMD = 0, 256 SAMP_CMD_ONE = 1, 257 SAMP_CMD_TWO = 2, 258 SAMP_COUNT_CMD 259@} samp_chk_enum_t; 260 261extern samp_chk_enum_t 262find_samp_chk_cmd(char const * str, size_t len); 263 264typedef void(samp_chk_handler_t)( 265 samp_chk_enum_t id, char const * str); 266 267samp_chk_handler_t 268 hdl_oops_cmd, hdl_one_cmd, hdl_two_cmd; 269 270extern void 271disp_samp_chk(char * str, size_t len); 272 273extern char const * 274samp_chk_name(samp_chk_enum_t id); 275@end example 276 277@itemize @bullet 278@item 279@code{find_samp_chk_cmd} will look up a @code{len} byte @code{str} and 280return the corresponding @code{samp_chk_enum_t} value. That value is 281@code{SAMP_OOPS_CMD} if the string is not ``one'' or ``two''. 282@item 283@code{samp_chk_handler_t} is the type of the callback procedures. 284Three must be provided for the dispatching function to call: 285@code{hdl_oops_cmd}, @code{hdl_one_cmd} and @code{hdl_two_cmd}. 286@code{hdl_oops_cmd} will receive calls when the string does not match. 287@item 288@code{disp_samp_chk} this function will call the handler function 289and return whatever the handler returns. In this case, it is void. 290@item 291@code{samp_chk_name} will return a string corresponding to the enumeration 292value argument. If the value is not valid, ``* UNDEFINED *'' (or the 293value of @code{undef-str}) is used. 294@end itemize 295@end table 296 297@c 298@c * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 299@c 300@node masks 301@subsection Bit Maps and Masks 302 303@file{str2mask.tpl} 304 305This template leverages highly off of enumerations (@pxref{enums}). It will 306produce a header file with bit masks defined for each bit specified with a 307@code{cmd} attribute. 63 is the highest legal bit number because this 308template has not been extended to cope with multiple word masks. (Patches 309would be welcome.) 310 311There are a few constraints on the names allowed: 312 313@itemize @bullet 314@item 315names are constrained to alphanumerics and the underscore 316@item 317aliases are not allowed 318@item 319dispatch procedures are not allowed 320@end itemize 321 322@code{no-code} and @code{no-name} are honored. @code{dispatch} is not. The 323lookup function will examine each token in an input string, determine which 324bit is specified and add it into a result. The names may be prefixed with a 325hyphen (@t{-}) or tilde (@t{~}) to remove the bit(s) from the cumulative 326result. If the string begins with a plus (@t{+}), hyphen or tilde, a ``base 327value'' parameter is used for the starting mask, otherwise the conversion 328starts with zero. 329 330Beyond the enumeration attributes that are used (or ignored), the 331@file{str2mask} template accepts a @code{mask} attribute. It takes a few 332``subattributes'': 333 334@table @samp 335@item m-name 336a special name for a sub-collection of the mask bits 337 338@item m-bit 339The name of each previously defined bit(s). If the desired previously 340defined value is a mask, that @code{m-name} must be suffixed with ``@t{-mask}''. 341 342@item m-invert 343When all done collecting the bits, x-or the value with the mask 344of all the bits in the collection. 345@end table 346 347@noindent 348A mask of all bits in the collection is always generated. 349