| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>glib-mkenums: GObject Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GObject Reference Manual"> |
| <link rel="up" href="rn02.html" title="Tools Reference"> |
| <link rel="prev" href="rn02.html" title="Tools Reference"> |
| <link rel="next" href="glib-genmarshal.html" title="glib-genmarshal"> |
| <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="rn02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="rn02.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="glib-genmarshal.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div lang="en" class="refentry"> |
| <a name="glib-mkenums"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle">glib-mkenums</span></h2> |
| <p>glib-mkenums — C language enum description generation utility</p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsynopsisdiv"> |
| <h2>Synopsis</h2> |
| <div class="cmdsynopsis"><p><code class="command">glib-mkenums</code> [OPTION...] [FILE...]</p></div> |
| </div> |
| <div class="refsect1"> |
| <a name="id-1.5.2.5"></a><h2>Description</h2> |
| <p><span class="command"><strong>glib-mkenums</strong></span> 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. |
| </p> |
| <p><span class="command"><strong>glib-mkenums</strong></span> 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. |
| </p> |
| <div class="refsect2"> |
| <a name="id-1.5.2.5.4"></a><h3>Production text substitutions</h3> |
| <p> |
| 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: |
| </p> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2 |
| 3 |
| 4 |
| 5</pre></td> |
| <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">enum</span> |
| <span class="cbracket">{</span> |
| <span class="normal"> PREFIX_THE_XVALUE </span><span class="symbol">=</span><span class="normal"> </span><span class="number">1</span><span class="normal"> </span><span class="symbol"><<</span><span class="normal"> </span><span class="number">3</span><span class="symbol">,</span> |
| <span class="normal"> PREFIX_ANOTHER_VALUE </span><span class="symbol">=</span><span class="normal"> </span><span class="number">1</span><span class="normal"> </span><span class="symbol"><<</span><span class="normal"> </span><span class="number">4</span> |
| <span class="cbracket">}</span><span class="normal"> PrefixTheXEnum</span><span class="symbol">;</span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <p> |
| </p> |
| <div class="variablelist"><table border="0" class="variablelist"> |
| <colgroup> |
| <col align="left" valign="top"> |
| <col> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td><p><span class="term">@EnumName@</span></p></td> |
| <td><p> |
| 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). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@enum_name@</span></p></td> |
| <td><p> |
| The enum name with words lowercase and word-separated by underscores |
| (e.g. prefix_the_xenum). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@ENUMNAME@</span></p></td> |
| <td><p> |
| The enum name with words uppercase and word-separated by underscores |
| (e.g. PREFIX_THE_XENUM). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@ENUMSHORT@</span></p></td> |
| <td><p> |
| The enum name with words uppercase and word-separated by underscores, |
| prefix stripped (e.g. THE_XENUM). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@ENUMPREFIX@</span></p></td> |
| <td><p> |
| The prefix of the enum name (e.g. PREFIX). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@VALUENAME@</span></p></td> |
| <td><p> |
| 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). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@valuenick@</span></p></td> |
| <td><p> |
| 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). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@valuenum@</span></p></td> |
| <td><p> |
| The integer value for the enum value currently being processed. This is |
| calculated by using <span class="command"><strong>perl</strong></span> to attempt to evaluate the |
| expression as it appears in the C source code. If evaluation fails then |
| <span class="command"><strong>glib-mkenums</strong></span> will exit with an error status, but this |
| only happens if <code class="literal">@valuenum@</code> appears in your value |
| production template. (Since: 2.26) |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@type@</span></p></td> |
| <td><p> |
| This is substituted either by "enum" or "flags", depending on whether the |
| enum value definitions contained bit-shift operators or not (e.g. flags). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@Type@</span></p></td> |
| <td><p> |
| The same as <code class="literal">@type@</code> with the first letter capitalized (e.g. Flags). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@TYPE@</span></p></td> |
| <td><p> |
| The same as <code class="literal">@type@</code> with all letters uppercased (e.g. FLAGS). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@filename@</span></p></td> |
| <td><p> |
| The name of the input file currently being processed (e.g. foo.h). |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">@basename@</span></p></td> |
| <td><p> |
| The base name of the input file currently being processed (e.g. foo.h). (Since: 2.22) |
| </p></td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p> |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.5.2.5.5"></a><h3>Trigraph extensions</h3> |
| <p> |
| Some C comments are treated specially in the parsed enum definitions, |
| such comments start out with the trigraph sequence <code class="literal">/*<</code> |
| and end with the trigraph sequence <code class="literal">>*/</code>. |
| 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 >*/. |
| </p> |
| <p> |
| 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: |
| </p> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2 |
| 3 |
| 4 |
| 5 |
| 6 |
| 7 |
| 8 |
| 9 |
| 10 |
| 11</pre></td> |
| <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">enum</span><span class="normal"> </span><span class="comment">/*< skip >*/</span> |
| <span class="cbracket">{</span> |
| <span class="normal"> PREFIX_FOO</span> |
| <span class="cbracket">}</span><span class="normal"> PrefixThisEnumWillBeSkipped</span><span class="symbol">;</span> |
| <span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">enum</span><span class="normal"> </span><span class="comment">/*< flags,prefix=PREFIX >*/</span> |
| <span class="cbracket">{</span> |
| <span class="normal"> PREFIX_THE_ZEROTH_VALUE</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/*< skip >*/</span> |
| <span class="normal"> PREFIX_THE_FIRST_VALUE</span><span class="symbol">,</span> |
| <span class="normal"> PREFIX_THE_SECOND_VALUE</span><span class="symbol">,</span> |
| <span class="normal"> PREFIX_THE_THIRD_VALUE</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/*< nick=the-last-value >*/</span> |
| <span class="cbracket">}</span><span class="normal"> PrefixTheFlagsEnum</span><span class="symbol">;</span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="id-1.5.2.6"></a><h2>Options</h2> |
| <div class="variablelist"><table border="0" class="variablelist"> |
| <colgroup> |
| <col align="left" valign="top"> |
| <col> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td><p><span class="term"><code class="option">--fhead</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Put out <em class="replaceable"><code>TEXT</code></em> prior to processing input files. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--fprod</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Put out <em class="replaceable"><code>TEXT</code></em> everytime a new input file |
| is being processed. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--ftail</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Put out <em class="replaceable"><code>TEXT</code></em> after all input files have been |
| processed. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--eprod</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Put out <em class="replaceable"><code>TEXT</code></em> everytime an enum is encountered |
| in the input files. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--vhead</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Put out <em class="replaceable"><code>TEXT</code></em> before iterating over the set of |
| values of an enum. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--vprod</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Put out <em class="replaceable"><code>TEXT</code></em> for every value of an enum. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--vtail</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Put out <em class="replaceable"><code>TEXT</code></em> after iterating over all values |
| of an enum. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--comments</code> <em class="replaceable"><code>TEXT</code></em></span></p></td> |
| <td><p> |
| Template for auto-generated comments, the default (for C code generations) is |
| <code class="literal">"/* @comment@ */"</code>. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--template</code> <em class="replaceable"><code>FILE</code></em></span></p></td> |
| <td> |
| <p> |
| Read templates from the given file. The templates are enclosed in |
| specially-formatted C comments |
| </p> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2</pre></td> |
| <td class="listing_code"><pre class="programlisting"><span class="comment">/*** BEGIN section ***/</span> |
| <span class="comment">/*** END section ***/</span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <p> |
| where section may be <code class="literal">file-header</code>, |
| <code class="literal">file-production</code>, <code class="literal">file-tail</code>, |
| <code class="literal">enumeration-production</code>, <code class="literal">value-header</code>, |
| <code class="literal">value-production</code>, <code class="literal">value-tail</code> or |
| <code class="literal">comment</code>. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--identifier-prefix</code> <em class="replaceable"><code>PREFIX</code></em></span></p></td> |
| <td><p> |
| Indicates what portion of the enum name should be intepreted as the |
| prefix (eg, the "<code class="literal">Gtk</code>" in |
| "<code class="literal">GtkDirectionType</code>"). Normally this will be figured |
| out automatically, but you may need to override the default if your |
| namespace is capitalized oddly. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--symbol-prefix</code> <em class="replaceable"><code>PREFIX</code></em></span></p></td> |
| <td><p> |
| Indicates what prefix should be used to correspond to the identifier |
| prefix in related C function names (eg, the "<code class="literal">gtk</code>" |
| in "<code class="literal">gtk_direction_type_get_type</code>". Equivalently, |
| this is the lowercase version of the prefix component of the enum |
| value names (eg, the "<code class="literal">GTK</code>" in |
| "<code class="literal">GTK_DIR_UP</code>". The default value is the identifier |
| prefix, converted to lowercase. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--help</code></span></p></td> |
| <td><p> |
| Print brief help and exit. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><code class="option">--version</code></span></p></td> |
| <td><p> |
| Print version and exit. |
| </p></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="id-1.5.2.7"></a><h2>See also</h2> |
| <p> |
| <span class="citerefentry"><span class="refentrytitle">glib-genmarshal</span>(1)</span> |
| </p> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25.1</div> |
| </body> |
| </html> |
