| .TH GLIB-MKENUMS 1 "27 Jul 2002" |
| .SH NAME |
| glib-mkenums \- C language enum description generation utility |
| .SH SYNOPSIS |
| |
| \fBglib-mkenums\fP [\fIoptions\fP] [\fIfiles...\fP] |
| |
| .SH DESCRIPTION |
| \fBglib-mkenums\fP is a small perl-script utility that parses C code to extract enum |
| definitions and produces enum descriptions based on text templates specified |
| by the user. Most frequently this script is used to produce C code that contains |
| enum values as strings so programs can provide value name strings for introspection. |
| |
| .SH INVOCATION |
| |
| \fBglib-mkenums\fP takes a list of valid C code files as input. The options |
| specified control the text that is output, certain substitutions are performed |
| on the text templates for keywords enclosed in @ characters. |
| |
| |
| .SS Options |
| .TP |
| \fI--fhead <text> |
| Put out <text> prior to processing input files. |
| .TP |
| \fI--fprod <text> |
| Put out <text> everytime a new input file is being processed. |
| .TP |
| \fI--ftail <text> |
| Put out <text> after all input files have been processed. |
| .TP |
| \fI--eprod <text> |
| Put out <text> everytime an enum is encountered in the input files. |
| .TP |
| \fI--vhead <text> |
| Put out <text> before iterating over the set of values of an enum. |
| .TP |
| \fI--vprod <text> |
| Put out <text> for every value of an enum. |
| .TP |
| \fI--vtail <text> |
| Put out <text> after iterating over all values of an enum. |
| .TP |
| \fI--comments <text> |
| Template for auto-generated comments, the default (for C code generations) is |
| "/* @comment@ */". |
| .TP |
| \fI--template file |
| Read templates from the given file. The templates are enclosed in |
| specially-formatted C comments |
| .PP |
| .RS |
| .nf |
| /*** BEGIN section ***/ |
| /*** END section ***/ |
| .fi |
| .PP |
| where section may be file-header, file-production, file-tail, |
| enumeration-production, value-header, value-production, value-tail or |
| comment. |
| .TP |
| \fI-h, --help\fP |
| Print brief help and exit. |
| .TP |
| \fI-v, --version\fP |
| Print version and exit. |
| .PP |
| |
| |
| .SS Production text substitutions |
| Certain keywords enclosed in @ characters will be substituted in the outputted |
| text. For the substitution examples of the keywords below, the following example |
| enum definition is assumed: |
| .PP |
| .RS |
| .nf |
| typedef enum |
| { |
| PREFIX_THE_XVALUE = 1 << 3, |
| PREFIX_ANOTHER_VALUE = 1 << 4 |
| } PrefixTheXEnum; |
| .fi |
| .RE |
| |
| .TP 12 |
| \fI@EnumName@ |
| The name of the enum currently being processed, enum names are assumed to be |
| properly namespaced and to use mixed capitalization to separate |
| words (e.g. PrefixTheXEnum). |
| .TP 12 |
| \fI@enum_name@ |
| The enum name with words lowercase and word-separated by underscores (e.g. prefix_the_xenum). |
| .TP 12 |
| \fI@ENUMNAME@ |
| The enum name with words uppercase and word-separated by underscores (e.g. PREFIX_THE_XENUM). |
| .TP 12 |
| \fI@ENUMSHORT@ |
| The enum name with words uppercase and word-separated by underscores, prefix stripped (e.g. THE_XENUM). |
| .TP 12 |
| \fI@VALUENAME@ |
| The enum value name currently being processed with words uppercase and word-separated by underscores, |
| this is the assumed literal notation of enum values in the C sources (e.g. PREFIX_THE_XVALUE). |
| .TP 12 |
| \fI@valuenick@ |
| A nick name for the enum value currently being processed, this is usually generated by stripping |
| common prefix words of all the enum values of the current enum, the words are lowercase and |
| underscores are substituted by a minus (e.g. the-xvalue). |
| .TP 12 |
| \fI@type@ |
| This is substituted either by "enum" or "flags", depending on whether the enum value definitions |
| contained bit-shift operators or not (e.g. flags). |
| .TP 12 |
| \fI@Type@ |
| The same as \fI@type@\fP with the first letter capitalized (e.g. Flags). |
| .TP 12 |
| \fI@TYPE@ |
| The same as \fI@type@\fP with all letters uppercased (e.g. FLAGS). |
| .TP 12 |
| \fI@filename@ |
| The name of the input file currently being processed (e.g. foo.h). |
| .TP 12 |
| \fI@basename@ |
| The base name of the input file currently being processed (e.g. foo.h). (Since: 2.22) |
| |
| .SS Trigraph extensions |
| Some C comments are treated specially in the parsed enum definitions, such comments |
| start out with the trigraph sequence "/*<" and end with the trigraph sequence ">*/". |
| .PP |
| Per enum definition, the options "skip" and "flags" can be specified, to indicate |
| this enum definition to be skipped, or for it to be treated as a flags definition, or |
| to specify the common prefix to be stripped from all values to generate value nicknames, |
| respectively. The "underscore_name" option can be used to specify the underscorized name |
| variant used in the *_get_type() function and *_TYPE_* macro. For instance, |
| /*< underscore_name=gnome_vfs_uri_hide_options >*/. |
| .PP |
| Per value definition, the options "skip" and "nick" are supported. The former causes the |
| value to be skipped, and the latter can be used to specify the otherwise auto-generated |
| nickname. |
| Examples: |
| .PP |
| .RS |
| .nf |
| typedef enum /*< skip >*/ |
| { |
| PREFIX_FOO |
| } PrefixThisEnumWillBeSkipped; |
| typedef enum /*< flags,prefix=PREFIX >*/ |
| { |
| PREFIX_THE_ZEROTH_VALUE, /*< skip >*/ |
| PREFIX_THE_FIRST_VALUE, |
| PREFIX_THE_SECOND_VALUE, |
| PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/ |
| } PrefixTheFlagsEnum; |
| .fi |
| .RE |
| |
| .SH SEE ALSO |
| \fB |
| glib-genmarshal(1) |
| \fP |
| |
| .SH BUGS |
| None known yet. |
| |
| .SH AUTHOR |
| .B glib-mkenums |
| was written by Tim Janik <timj@gtk.org> and Owen Taylor <otaylor@redhat.com>. |
| .PP |
| This manual page was provided by Tim Janik <timj@gtk.org>. |
