docs/reference/gobject/html/glib-mkenums.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>glib-mkenums</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="rn02.html" title="Tools Reference">
   9 <link rel="prev" href="rn02.html" title="Tools Reference">
  10 <link rel="next" href="glib-genmarshal.html" title="glib-genmarshal">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="preface" href="pr01.html" title="Introduction">
  14 <link rel="part" href="pt01.html" title="Part I. Concepts">
  15 <link rel="chapter" href="chapter-intro.html" title="Background">
  16 <link rel="chapter" href="chapter-gtype.html" title="The GLib Dynamic Type System">
  17 <link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
  18 <link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
  19 <link rel="reference" href="rn01.html" title="API Reference">
  20 <link rel="reference" href="rn02.html" title="Tools Reference">
  21 <link rel="part" href="pt02.html" title="Part IV. Tutorial">
  22 <link rel="chapter" href="howto-gobject.html" title="How to define and implement a new GObject">
  23 <link rel="chapter" href="howto-interface.html" title="How to define and implement interfaces">
  24 <link rel="chapter" href="howto-signals.html" title="How to create and use signals">
  25 <link rel="part" href="pt03.html" title="Part V. Related Tools">
  26 <link rel="chapter" href="tools-vala.html" title="Vala">
  27 <link rel="chapter" href="tools-gob.html" title="GObject builder">
  28 <link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of GObjects">
  29 <link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
  30 <link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
  31 <link rel="index" href="api-index-full.html" title="Index">
  32 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  33 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  34 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  35 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  36 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  37 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  38 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  39 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  40 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  41 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  42 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  43 </head>
  44 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  45 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  46 <td><a accesskey="p" href="rn02.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  47 <td><a accesskey="u" href="rn02.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  48 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  49 <th width="100%" align="center">GObject Reference Manual</th>
  50 <td><a accesskey="n" href="glib-genmarshal.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  51 </tr></table>
  52 <div class="refentry" title="glib-mkenums">
  53 <a name="glib-mkenums"></a><div class="titlepage"></div>
  54 <div class="refnamediv"><table width="100%"><tr>
  55 <td valign="top">
  56 <h2><span class="refentrytitle">glib-mkenums</span></h2>
  57 <p>glib-mkenums — C language enum description generation utility</p>
  58 </td>
  59 <td valign="top" align="right"></td>
  60 </tr></table></div>
  61 <div class="refsynopsisdiv" title="Synopsis">
  62 <h2>Synopsis</h2>
  63 <div class="cmdsynopsis"><p><code class="command">glib-mkenums</code>  [options...] [files...]</p></div>
  64 </div>
  65 <div class="refsect1" title="Description">
  66 <a name="id568789"></a><h2>Description</h2>
  67 <p><span class="command"><strong>glib-mkenums</strong></span> is a small perl-script utility that parses C
  68 code to extract enum definitions and produces enum descriptions based on text
  69 templates specified by the user. Most frequently this script is used to
  70 produce C code that contains enum values as strings so programs can provide
  71 value name strings for introspection.
  72 </p>
  73 </div>
  74 <div class="refsect1" title="Invocation">
  75 <a name="id620529"></a><h2>Invocation</h2>
  76 <p><span class="command"><strong>glib-mkenums</strong></span> takes a list of valid C code files as
  77 input. The options specified control the text that is output, certain
  78 substitutions are performed on the text templates for keywords enclosed
  79 in @ characters.
  80 </p>
  81 <div class="refsect2" title="Options">
  82 <a name="id590584"></a><h3>Options</h3>
  83 <div class="variablelist"><table border="0">
  84 <col align="left" valign="top">
  85 <tbody>
  86 <tr>
  87 <td><p><span class="term"><code class="option">--fhead</code> <em class="replaceable"><code>text</code></em></span></p></td>
  88 <td><p>
  89 Put out <em class="replaceable"><code>text</code></em> prior to processing input files.
  90 </p></td>
  91 </tr>
  92 <tr>
  93 <td><p><span class="term"><code class="option">--fprod</code> <em class="replaceable"><code>text</code></em></span></p></td>
  94 <td><p>
  95 Put out <em class="replaceable"><code>text</code></em> everytime a new input file
  96 is being processed.
  97 </p></td>
  98 </tr>
  99 <tr>
 100 <td><p><span class="term"><code class="option">--ftail</code> <em class="replaceable"><code>text</code></em></span></p></td>
 101 <td><p>
 102 Put out <em class="replaceable"><code>text</code></em> after all input files have been
 103 processed.
 104 </p></td>
 105 </tr>
 106 <tr>
 107 <td><p><span class="term"><code class="option">--eprod</code> <em class="replaceable"><code>text</code></em></span></p></td>
 108 <td><p>
 109 Put out <em class="replaceable"><code>text</code></em> everytime an enum is encountered
 110 in the input files.
 111 </p></td>
 112 </tr>
 113 <tr>
 114 <td><p><span class="term"><code class="option">--vhead</code> <em class="replaceable"><code>text</code></em></span></p></td>
 115 <td><p>
 116 Put out <em class="replaceable"><code>text</code></em> before iterating over the set of
 117 values of an enum.
 118 </p></td>
 119 </tr>
 120 <tr>
 121 <td><p><span class="term"><code class="option">--vprod</code> <em class="replaceable"><code>text</code></em></span></p></td>
 122 <td><p>
 123 Put out <em class="replaceable"><code>text</code></em> for every value of an enum.
 124 </p></td>
 125 </tr>
 126 <tr>
 127 <td><p><span class="term"><code class="option">--vtail</code> <em class="replaceable"><code>text</code></em></span></p></td>
 128 <td><p>
 129 Put out <em class="replaceable"><code>text</code></em> after iterating over all values
 130 of an enum.
 131 </p></td>
 132 </tr>
 133 <tr>
 134 <td><p><span class="term"><code class="option">--comments</code> <em class="replaceable"><code>text</code></em></span></p></td>
 135 <td><p>
 136 Template for auto-generated comments, the default (for C code generations) is
 137 <code class="literal">"/* @comment@ */"</code>.
 138 </p></td>
 139 </tr>
 140 <tr>
 141 <td><p><span class="term"><code class="option">--template</code> <em class="replaceable"><code>file</code></em></span></p></td>
 142 <td>
 143 <p>
 144 Read templates from the given file. The templates are enclosed in
 145 specially-formatted C comments
 146 </p>
 147 <pre class="programlisting">
 148 /*** BEGIN section ***/
 149 /*** END section ***/
 150 </pre>
 151 <p>
 152 where section may be <code class="literal">file-header</code>,
 153 <code class="literal">file-production</code>, <code class="literal">file-tail</code>,
 154 <code class="literal">enumeration-production</code>, <code class="literal">value-header</code>,
 155 <code class="literal">value-production</code>, <code class="literal">value-tail</code> or
 156 <code class="literal">comment</code>.
 157 </p>
 158 </td>
 159 </tr>
 160 <tr>
 161 <td><p><span class="term"><code class="option">--help</code></span></p></td>
 162 <td><p>
 163 Print brief help and exit.
 164 </p></td>
 165 </tr>
 166 <tr>
 167 <td><p><span class="term"><code class="option">--version</code></span></p></td>
 168 <td><p>
 169 Print version and exit.
 170 </p></td>
 171 </tr>
 172 </tbody>
 173 </table></div>
 174 </div>
 175 <hr>
 176 <div class="refsect2" title="Production text substitutions">
 177 <a name="id574325"></a><h3>Production text substitutions</h3>
 178 <p>
 179 Certain keywords enclosed in @ characters will be substituted in the
 180 emitted text. For the substitution examples of the keywords below,
 181 the following example enum definition is assumed:
 182 </p>
 183 <pre class="programlisting">
 184 typedef enum
 185 {
 186   PREFIX_THE_XVALUE    = 1 &lt;&lt; 3,
 187   PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
 188 } PrefixTheXEnum;
 189 </pre>
 190 <p>
 191 </p>
 192 <div class="variablelist"><table border="0">
 193 <col align="left" valign="top">
 194 <tbody>
 195 <tr>
 196 <td><p><span class="term">@EnumName@</span></p></td>
 197 <td><p>
 198 The name of the enum currently being processed, enum names are assumed to be
 199 properly namespaced and to use mixed capitalization to separate
 200 words (e.g. PrefixTheXEnum).
 201 </p></td>
 202 </tr>
 203 <tr>
 204 <td><p><span class="term">@enum_name@</span></p></td>
 205 <td><p>
 206 The enum name with words lowercase and word-separated by underscores
 207 (e.g. prefix_the_xenum).
 208 </p></td>
 209 </tr>
 210 <tr>
 211 <td><p><span class="term">@ENUMNAME@</span></p></td>
 212 <td><p>
 213 The enum name with words uppercase and word-separated by underscores
 214 (e.g. PREFIX_THE_XENUM).
 215 </p></td>
 216 </tr>
 217 <tr>
 218 <td><p><span class="term">@ENUMSHORT@</span></p></td>
 219 <td><p>
 220 The enum name with words uppercase and word-separated by underscores,
 221 prefix stripped (e.g. THE_XENUM).
 222 </p></td>
 223 </tr>
 224 <tr>
 225 <td><p><span class="term">@VALUENAME@</span></p></td>
 226 <td><p>
 227 The enum value name currently being processed with words uppercase and
 228 word-separated by underscores,
 229 this is the assumed literal notation of enum values in the C sources
 230 (e.g. PREFIX_THE_XVALUE).
 231 </p></td>
 232 </tr>
 233 <tr>
 234 <td><p><span class="term">@valuenick@</span></p></td>
 235 <td><p>
 236 A nick name for the enum value currently being processed, this is usually
 237 generated by stripping common prefix words of all the enum values of the
 238 current enum, the words are lowercase and underscores are substituted by a
 239 minus (e.g. the-xvalue).
 240 </p></td>
 241 </tr>
 242 <tr>
 243 <td><p><span class="term">@type@</span></p></td>
 244 <td><p>
 245 This is substituted either by "enum" or "flags", depending on whether the
 246 enum value definitions contained bit-shift operators or not (e.g. flags).
 247 </p></td>
 248 </tr>
 249 <tr>
 250 <td><p><span class="term">@Type@</span></p></td>
 251 <td><p>
 252 The same as <code class="literal">@type@</code> with the first letter capitalized (e.g. Flags).
 253 </p></td>
 254 </tr>
 255 <tr>
 256 <td><p><span class="term">@TYPE@</span></p></td>
 257 <td><p>
 258 The same as <code class="literal">@type@</code> with all letters uppercased (e.g. FLAGS).
 259 </p></td>
 260 </tr>
 261 <tr>
 262 <td><p><span class="term">@filename@</span></p></td>
 263 <td><p>
 264 The name of the input file currently being processed (e.g. foo.h).
 265 </p></td>
 266 </tr>
 267 <tr>
 268 <td><p><span class="term">@basename@</span></p></td>
 269 <td><p>
 270 The base name of the input file currently being processed (e.g. foo.h). (Since: 2.22)
 271 </p></td>
 272 </tr>
 273 </tbody>
 274 </table></div>
 275 <p>
 276 </p>
 277 </div>
 278 <hr>
 279 <div class="refsect2" title="Trigraph extensions">
 280 <a name="id612404"></a><h3>Trigraph extensions</h3>
 281 <p>
 282 Some C comments are treated specially in the parsed enum definitions,
 283 such comments start out with the trigraph sequence <code class="literal">/*&lt;</code>
 284 and end with the trigraph sequence <code class="literal">&gt;*/</code>.
 285 Per enum definition, the options "skip" and "flags" can be specified, to
 286 indicate this enum definition to be skipped, or for it to be treated as
 287 a flags definition, or to specify the common prefix to be stripped from
 288 all values to generate value nicknames, respectively. The "lowercase_name"
 289 option can be used to specify the word separation used in the *_get_type()
 290 function. For instance, /*&lt; lowercase_name=gnome_vfs_uri_hide_options &gt;*/.
 291 </p>
 292 <p>
 293 Per value definition, the options "skip" and "nick" are supported.
 294 The former causes the value to be skipped, and the latter can be used to
 295 specify the otherwise auto-generated nickname.
 296 Examples:
 297 </p>
 298 <pre class="programlisting">
 299 typedef enum /*&lt; skip &gt;*/
 300 {
 301   PREFIX_FOO
 302 } PrefixThisEnumWillBeSkipped;
 303 typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
 304 {
 305   PREFIX_THE_ZEROTH_VALUE,      /*&lt; skip &gt;*/
 306   PREFIX_THE_FIRST_VALUE,
 307   PREFIX_THE_SECOND_VALUE,
 308   PREFIX_THE_THIRD_VALUE,       /*&lt; nick=the-last-value &gt;*/
 309 } PrefixTheFlagsEnum;
 310 </pre>
 311 <p>
 312 </p>
 313 </div>
 314 </div>
 315 <div class="refsect1" title="See also">
 316 <a name="id583130"></a><h2>See also</h2>
 317 <p><span class="command"><strong>glib-genmarshal</strong></span>(1)
 318 </p>
 319 </div>
 320 </div>
 321 <div class="footer">
 322 <hr>
 323           Generated by GTK-Doc V1.13</div>
 324 </body>
 325 </html>