mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-14 05:16:18 +01:00
49eacae2a3
Tue Oct 10 12:06:08 2006 Tim Janik <timj@gtk.org>
* glib-mkenums.in:
* glib-mkenums.1: applied patch from David Necas which introduces
an underscore_name option and fixes #358734.
167 lines
5.0 KiB
Groff
167 lines
5.0 KiB
Groff
.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).
|
|
|
|
.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>.
|