'\" te
.TH glib-mkenums 1 "7 Apr 2003" "SunOS 5.11" "User Commands"
.SH "NAME"
glib-mkenums \- generate C language \fBenum\fR description
.SH "SYNOPSIS"
.PP
\fBglib-mkenums\fR [-\fB-comments \fItext\fR\fR] [-\fB-eprod \fItext\fR\fR] [-\fB-fhead \fItext\fR\fR] [-\fB-fprod \fItext\fR\fR] [-\fB-ftail \fItext\fR\fR] [-\fB-help\fR] [-\fB-template \fIfile\fR\fR] [-\fB-version\fR] [-\fB-vhead \fItext\fR\fR] [-\fB-vprod \fItext\fR\fR] [-\fB-vtail \fItext\fR\fR] [\fB\fIfile\fR\fR\&...]
.SH "DESCRIPTION"
.PP
\fBglib-mkenums\fR parses C code to extract \fBenum\fR
definitions, and produces \fBenum\fR descriptions based on text
templates specified by the user\&. \fBglib-mkenums\fR produces C code
that contains \fBenum\fR values as strings, which allows programs
to provide value name strings for introspection\&.
.PP
\fBglib-mkenums\fR 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\&.
.SH "EXTENDED DESCRIPTION"
.PP
This section provides more information about text substitution and trigraph
extensions\&.
.SS "Text Substitution"
.PP
\fBglib-mkenums\fR substitutes certain keywords, which are enclosed in
@ characters, when creating the output text\&. For the substitution examples of
the keywords in this section, the following example \fBenum\fR
definition is assumed:
.PP
.nf
typedef enum
{
  PREFIX_THE_XVALUE    = 1 << 3,
  PREFIX_ANOTHER_VALUE = 1 << 4
} PrefixTheXEnum;
.fi
.PP
\fBglib-mkenums\fR substitutes the following keywords:
.sp
.ne 2
.mk
\fB\fB@EnumName@\fR\fR
.in +16n
.rt
The name of the \fBenum\fR currently being
processed\&. \fBenum\fR names are assumed to be properly namespaced
and to use mixed capitalization to separate words (for example,
\fBPrefixTheXEnum\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@enum_name@\fR\fR
.in +16n
.rt
The \fBenum\fR name with words in lowercase and each word
separated by underscores (for example, \fBprefix_the_xenum\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@ENUMNAME@\fR\fR
.in +16n
.rt
The \fBenum\fR name with words in uppercase and each word
separated by underscores (for example, \fBPREFIX_THE_XENUM\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@ENUMSHORT@\fR\fR
.in +16n
.rt
The \fBenum\fR name with words in uppercase and each word separated
by underscores, and with the prefix stripped (for example, \fBTHE_XENUM\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@VALUENAME@\fR\fR
.in +16n
.rt
The \fBenum\fR value name currently being processed, with words
in uppercase and each word separated by underscores\&. This is the assumed literal
notation of \fBenum\fR values in the C sources (for example,
\fBPREFIX_THE_XVALUE\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@valuenick@\fR\fR
.in +16n
.rt
A nickname for the \fBenum\fR value currently being processed\&.
This is usually generated by stripping the common prefix words of all of the
\fBenum\fR values of the current \fBenum\fR, with
words in lowercase and underscores substituted by hyphens (for example,
\fBthe-xvalue\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@type@\fR\fR
.in +16n
.rt
This is substituted either by "\fBenum\fR" or
"\fBflags\fR", depending on whether the \fBenum\fR
value definitions contain bit-shift operators or not (for example,
\fBflags\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@Type@\fR\fR
.in +16n
.rt
Same as \fB@type@\fR, but with the first letter capitalized (for
example, \fBFlags\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@TYPE@\fR\fR
.in +16n
.rt
Same as \fB@type@\fR, but with all letters in uppercase (for
example, \fBFLAGS\fR)\&.
.sp
.sp 1
.in -16n
.sp
.ne 2
.mk
\fB\fB@filename@\fR\fR
.in +16n
.rt
The name of the input file currently being processed (for example,
\fBfoo\&.h\fR)\&.
.sp
.sp 1
.in -16n
.SS "Trigraph Extensions"
.PP
Some C comments in the parsed \fBenum\fR definitions are treated
as special\&. Such comments start with the trigraph sequence
\fB/*<\fR and end with the trigraph sequence
\fB>*/\fR\&. 
.PP
Per \fBenum\fR definition, the "\fBskip\fR" and
"\fBflags\fR" options are supported\&. The \fBskip\fR
option indicates that this \fBenum\fR definition should be
skipped\&.  The \fBflags\fR option specifies that this
\fBenum\fR definition should be treated as a flags definition, or
specifies the common prefix to be stripped from all values to generate value
nicknames\&.  The "\fBunderscore_name\fR" option can be used to
specify the underscorized name variant used in the *_get_type() function and
*_TYPE_* macro\&.  For instance:
.PP
.nf
/*< underscore_name=gnome_vfs_uri_hide_options >*/
.fi
.PP
Per value definition, the "\fBskip\fR" and
"\fBnick\fR" options are supported\&. The \fBskip\fR
option causes the value to be skipped\&. The \fBnick\fR option
specifies the otherwise autogenerated nickname\&.
.SH "OPTIONS"
.PP
The following options are supported:
.sp
.ne 2
.mk
\fB-\fB-comments \fI text\fR\fR\fR
.in +24n
.rt
Template \fItext\fR for auto-generated comments, the
default (for C code generation) is 
.nf
.sp
"/* @comment@ */"
.fi
.sp
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-eprod \fItext\fR\fR\fR
.in +24n
.rt
Output \fItext\fR every time an \fBenum\fR
occurs in the input files\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-fhead \fItext\fR\fR\fR
.in +24n
.rt
Output \fItext\fR prior to processing input files\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-fprod \fItext\fR\fR\fR
.in +24n
.rt
Output \fItext\fR every time a new input file is
processed\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-ftail \fItext\fR\fR\fR
.in +24n
.rt
Output \fItext\fR after all input files have been
processed\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB\fB-h\fR, -\fB-help\fR\fR
.in +24n
.rt
Show usage and basic help information\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-template \fIfile\fR\fR\fR
.in +24n
.rt
Read template from the given \fIfile\fR\&.  The templates
are enclosed in specially-formatted C comments
.sp
.nf
.sp
/*** BEGIN \fIsection\fR ***/
/*** END \fIsection\fR ***/
.fi
.sp
.sp
where \fIsection\fR may be file-header, file-production,
file-tail, enumeration-production, value-header, value-production, value-tail,
or comment\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB\fB-v\fR, -\fB-version\fR\fR
.in +24n
.rt
Show version information\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-vhead \fItext\fR\fR\fR
.in +24n
.rt
Output \fItext\fR before iterating the set of values of an
\fBenum\fR\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-vprod \fItext\fR\fR\fR
.in +24n
.rt
Output \fItext\fR for every value of an
\fBenum\fR\&.
.sp
.sp 1
.in -24n
.sp
.ne 2
.mk
\fB-\fB-vtail \fItext\fR\fR\fR
.in +24n
.rt
Output \fItext\fR after iterating all values of an
\fBenum\fR\&.
.sp
.sp 1
.in -24n
.SH "OPERANDS"
.PP
The following operands are supported:
.sp
.ne 2
.mk
\fB\fB\fIfile\fR\fR\fR
.in +24n
.rt
Specifies a valid C code file\&.
.sp
.sp 1
.in -24n
.SH "EXAMPLES"
.PP
\fBExample 1: Examples of Trigraph Extensions\fR
.PP
.PP
.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
.SH "EXIT STATUS"
.PP
The following exit values are returned:
.sp
.ne 2
.mk
\fB\fB0\fR\fR
.in +9n
.rt
Application exited successfully
.sp
.sp 1
.in -9n
.sp
.ne 2
.mk
\fB\fB>0\fR\fR
.in +9n
.rt
Application exited with failure
.sp
.sp 1
.in -9n
.SH "FILES"
.PP
The following files are used by this application:
.sp
.ne 2
.mk
\fB\fB/usr/bin/glib-mkenums\fR\fR
.in +32n
.rt
The command-line executable for the application\&.
.sp
.sp 1
.in -32n
.sp
.ne 2
.mk
\fB\fB/usr/share/gtk-doc/html/glib\fR\fR
.in +32n
.rt
Location of developer documentation
.sp
.sp 1
.in -32n
.SH "ATTRIBUTES"
.PP
See
\fBattributes\fR(5)
for descriptions of the following attributes:
.sp
.TS
tab() allbox;
cw(2.750000i)| cw(2.750000i)
lw(2.750000i)| lw(2.750000i).
ATTRIBUTE TYPEATTRIBUTE VALUE
AvailabilitySUNWglib2-devel
Interface stabilityCommitted
.TE
.sp
.SH "SEE ALSO"
.PP
\fBgdk-pixbuf-source\fR(1),
\fBgdk-pixbuf-query-loaders\fR(1),
\fBglib-genmarshal\fR(1),
\fBglib-gettextize\fR(1),
\fBgobject-query\fR(1),
\fBgtk-query-immodules-2\&.0\fR(1),
\fBgtk-update-icon-cache\fR(1),
\fBlibglib-2\&.0\fR(3),
\fBattributes\fR(5),
\fBgnome-interfaces\fR(5)
.SH "NOTES"
.PP
Written by Tim Janik\&.  Updated by Brian Cameron, Sun Microsystems Inc\&., 2003,
2006\&.
...\" created by instant / solbook-to-man, Thu 20 Mar 2014, 02:30
...\" LSARC 2001/384 Gtk+ 2.0 / glib 2.0
...\" LSARC 2001/781 location of GTK/Glib
...\" PSARC 2001/804 GTK/Glib becomes Contracted External