mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 19:36:18 +01:00
297 lines
8.6 KiB
XML
297 lines
8.6 KiB
XML
<refentry id="glib-mkenums" lang="en">
|
|
|
|
<refmeta>
|
|
<refentrytitle>glib-mkenums</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">User Commands</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>glib-mkenums</refname>
|
|
<refpurpose>C language enum description generation utility</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>glib-mkenums</command>
|
|
<arg choice="opt" rep="repeat">options</arg>
|
|
<arg choice="opt" rep="repeat">files</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1><title>Description</title>
|
|
<para><command>glib-mkenums</command> 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.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1><title>Invocation</title>
|
|
<para><command>glib-mkenums</command> 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.
|
|
</para>
|
|
|
|
<refsect2><title>Options</title>
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--fhead</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Put out <replaceable>text</replaceable> prior to processing input files.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--fprod</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Put out <replaceable>text</replaceable> everytime a new input file
|
|
is being processed.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--ftail</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Put out <replaceable>text</replaceable> after all input files have been
|
|
processed.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--eprod</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Put out <replaceable>text</replaceable> everytime an enum is encountered
|
|
in the input files.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--vhead</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Put out <replaceable>text</replaceable> before iterating over the set of
|
|
values of an enum.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--vprod</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Put out <replaceable>text</replaceable> for every value of an enum.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--vtail</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Put out <replaceable>text</replaceable> after iterating over all values
|
|
of an enum.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--comments</option> <replaceable>text</replaceable></term>
|
|
<listitem><para>
|
|
Template for auto-generated comments, the default (for C code generations) is
|
|
<literal>"/* @comment@ */"</literal>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--template</option> <replaceable>file</replaceable></term>
|
|
<listitem><para>
|
|
Read templates from the given file. The templates are enclosed in
|
|
specially-formatted C comments
|
|
<programlisting>
|
|
/*** BEGIN section ***/
|
|
/*** END section ***/
|
|
</programlisting>
|
|
where section may be <literal>file-header</literal>,
|
|
<literal>file-production</literal>, <literal>file-tail</literal>,
|
|
<literal>enumeration-production</literal>, <literal>value-header</literal>,
|
|
<literal>value-production</literal>, <literal>value-tail</literal> or
|
|
<literal>comment</literal>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--help</option></term>
|
|
<listitem><para>
|
|
Print brief help and exit.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--version</option></term>
|
|
<listitem><para>
|
|
Print version and exit.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2><title>Production text substitutions</title>
|
|
<para>
|
|
Certain keywords enclosed in @ characters will be substituted in the
|
|
emitted text. For the substitution examples of the keywords below,
|
|
the following example enum definition is assumed:
|
|
<programlisting>
|
|
typedef enum
|
|
{
|
|
PREFIX_THE_XVALUE = 1 << 3,
|
|
PREFIX_ANOTHER_VALUE = 1 << 4
|
|
} PrefixTheXEnum;
|
|
</programlisting>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>@EnumName@</term>
|
|
<listitem><para>
|
|
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).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@enum_name@</term>
|
|
<listitem><para>
|
|
The enum name with words lowercase and word-separated by underscores
|
|
(e.g. prefix_the_xenum).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@ENUMNAME@</term>
|
|
<listitem><para>
|
|
The enum name with words uppercase and word-separated by underscores
|
|
(e.g. PREFIX_THE_XENUM).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@ENUMSHORT@</term>
|
|
<listitem><para>
|
|
The enum name with words uppercase and word-separated by underscores,
|
|
prefix stripped (e.g. THE_XENUM).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@VALUENAME@</term>
|
|
<listitem><para>
|
|
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).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@valuenick@</term>
|
|
<listitem><para>
|
|
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).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@valuenum@</term>
|
|
<listitem><para>
|
|
The integer value for the enum value currently being processed. This is
|
|
calculated by using <command>perl</command> to attempt to evaluate the
|
|
expression as it appears in the C source code. If evaluation fails then
|
|
<command>glib-mkenums</command> will exit with an error status, but this
|
|
only happens if <literal>@valuenum@</literal> appears in your value
|
|
production template. (Since: 2.26)
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@type@</term>
|
|
<listitem><para>
|
|
This is substituted either by "enum" or "flags", depending on whether the
|
|
enum value definitions contained bit-shift operators or not (e.g. flags).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@Type@</term>
|
|
<listitem><para>
|
|
The same as <literal>@type@</literal> with the first letter capitalized (e.g. Flags).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@TYPE@</term>
|
|
<listitem><para>
|
|
The same as <literal>@type@</literal> with all letters uppercased (e.g. FLAGS).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@filename@</term>
|
|
<listitem><para>
|
|
The name of the input file currently being processed (e.g. foo.h).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>@basename@</term>
|
|
<listitem><para>
|
|
The base name of the input file currently being processed (e.g. foo.h). (Since: 2.22)
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect2>
|
|
<refsect2><title>Trigraph extensions</title>
|
|
<para>
|
|
Some C comments are treated specially in the parsed enum definitions,
|
|
such comments start out with the trigraph sequence <literal>/*<</literal>
|
|
and end with the trigraph sequence <literal>>*/</literal>.
|
|
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 word separation used in the *_get_type()
|
|
function. For instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/.
|
|
</para>
|
|
<para>
|
|
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:
|
|
<programlisting>
|
|
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;
|
|
</programlisting>
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
<refsect1><title>See also</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>glib-genmarshal</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|