| <refentry id="glib-mkenums" lang="en"> |
| |
| <refentryinfo> |
| <title>gdbus</title> |
| <productname>GObject</productname> |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>Owen</firstname> |
| <surname>Taylor</surname> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <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">OPTION</arg> |
| <arg choice="opt" rep="repeat">FILE</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> |
| |
| <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>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: |
| <informalexample><programlisting> |
| typedef enum |
| { |
| PREFIX_THE_XVALUE = 1 << 3, |
| PREFIX_ANOTHER_VALUE = 1 << 4 |
| } PrefixTheXEnum; |
| </programlisting></informalexample> |
| <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>@ENUMPREFIX@</term> |
| <listitem><para> |
| The prefix of the enum name (e.g. PREFIX). |
| </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: |
| <informalexample><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></informalexample> |
| </para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1><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 |
| <informalexample><programlisting> |
| /*** BEGIN section ***/ |
| /*** END section ***/ |
| </programlisting></informalexample> |
| 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>--identifier-prefix</option> <replaceable>PREFIX</replaceable></term> |
| <listitem><para> |
| Indicates what portion of the enum name should be intepreted as the |
| prefix (eg, the "<literal>Gtk</literal>" in |
| "<literal>GtkDirectionType</literal>"). Normally this will be figured |
| out automatically, but you may need to override the default if your |
| namespace is capitalized oddly. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--symbol-prefix</option> <replaceable>PREFIX</replaceable></term> |
| <listitem><para> |
| Indicates what prefix should be used to correspond to the identifier |
| prefix in related C function names (eg, the "<literal>gtk</literal>" |
| in "<literal>gtk_direction_type_get_type</literal>". Equivalently, |
| this is the lowercase version of the prefix component of the enum |
| value names (eg, the "<literal>GTK</literal>" in |
| "<literal>GTK_DIR_UP</literal>". The default value is the identifier |
| prefix, converted to lowercase. |
| </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> |
| </refsect1> |
| |
| <refsect1><title>See also</title> |
| <para> |
| <citerefentry> |
| <refentrytitle>glib-genmarshal</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry> |
| </para> |
| </refsect1> |
| </refentry> |