docs/reference/gobject/glib-mkenums.xml

   1 <refentry id="glib-mkenums" lang="en">
   2
   3 <refentryinfo>
   4   <title>gdbus</title>
   5   <productname>GObject</productname>
   6   <authorgroup>
   7     <author>
   8       <contrib>Developer</contrib>
   9       <firstname>Owen</firstname>
  10       <surname>Taylor</surname>
  11     </author>
  12   </authorgroup>
  13 </refentryinfo>
  14
  15 <refmeta>
  16 <refentrytitle>glib-mkenums</refentrytitle>
  17 <manvolnum>1</manvolnum>
  18 <refmiscinfo class="manual">User Commands</refmiscinfo>
  19 </refmeta>
  20
  21 <refnamediv>
  22 <refname>glib-mkenums</refname>
  23 <refpurpose>C language enum description generation utility</refpurpose>
  24 </refnamediv>
  25
  26 <refsynopsisdiv>
  27 <cmdsynopsis>
  28 <command>glib-mkenums</command>
  29 <arg choice="opt" rep="repeat">OPTION</arg>
  30 <arg choice="opt" rep="repeat">FILE</arg>
  31 </cmdsynopsis>
  32 </refsynopsisdiv>
  33
  34 <refsect1><title>Description</title>
  35 <para><command>glib-mkenums</command> is a small perl-script utility that
  36 parses C code to extract enum definitions and produces enum descriptions based
  37 on text templates specified by the user. Most frequently this script is used to
  38 produce C code that contains enum values as strings so programs can provide
  39 value name strings for introspection.
  40 </para>
  41
  42 <para><command>glib-mkenums</command> takes a list of valid C code files as
  43 input. The options specified control the text that is output, certain
  44 substitutions are performed on the text templates for keywords enclosed
  45 in @ characters.
  46 </para>
  47
  48 <refsect2><title>Production text substitutions</title>
  49 <para>
  50 Certain keywords enclosed in @ characters will be substituted in the
  51 emitted text. For the substitution examples of the keywords below,
  52 the following example enum definition is assumed:
  53 <informalexample><programlisting>
  54 typedef enum
  55 {
  56   PREFIX_THE_XVALUE    = 1 &lt;&lt; 3,
  57   PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
  58 } PrefixTheXEnum;
  59 </programlisting></informalexample>
  60 <variablelist>
  61 <varlistentry>
  62 <term>@EnumName@</term>
  63 <listitem><para>
  64 The name of the enum currently being processed, enum names are assumed to be
  65 properly namespaced and to use mixed capitalization to separate
  66 words (e.g. PrefixTheXEnum).
  67 </para></listitem>
  68 </varlistentry>
  69
  70 <varlistentry>
  71 <term>@enum_name@</term>
  72 <listitem><para>
  73 The enum name with words lowercase and word-separated by underscores
  74 (e.g. prefix_the_xenum).
  75 </para></listitem>
  76 </varlistentry>
  77
  78 <varlistentry>
  79 <term>@ENUMNAME@</term>
  80 <listitem><para>
  81 The enum name with words uppercase and word-separated by underscores
  82 (e.g. PREFIX_THE_XENUM).
  83 </para></listitem>
  84 </varlistentry>
  85
  86 <varlistentry>
  87 <term>@ENUMSHORT@</term>
  88 <listitem><para>
  89 The enum name with words uppercase and word-separated by underscores,
  90 prefix stripped (e.g. THE_XENUM).
  91 </para></listitem>
  92 </varlistentry>
  93
  94 <varlistentry>
  95 <term>@ENUMPREFIX@</term>
  96 <listitem><para>
  97 The prefix of the enum name (e.g. PREFIX).
  98 </para></listitem>
  99 </varlistentry>
 100
 101 <varlistentry>
 102 <term>@VALUENAME@</term>
 103 <listitem><para>
 104 The enum value name currently being processed with words uppercase and
 105 word-separated by underscores,
 106 this is the assumed literal notation of enum values in the C sources
 107 (e.g. PREFIX_THE_XVALUE).
 108 </para></listitem>
 109 </varlistentry>
 110
 111 <varlistentry>
 112 <term>@valuenick@</term>
 113 <listitem><para>
 114 A nick name for the enum value currently being processed, this is usually
 115 generated by stripping common prefix words of all the enum values of the
 116 current enum, the words are lowercase and underscores are substituted by a
 117 minus (e.g. the-xvalue).
 118 </para></listitem>
 119 </varlistentry>
 120
 121 <varlistentry>
 122 <term>@valuenum@</term>
 123 <listitem><para>
 124 The integer value for the enum value currently being processed.  This is
 125 calculated by using <command>perl</command> to attempt to evaluate the
 126 expression as it appears in the C source code.  If evaluation fails then
 127 <command>glib-mkenums</command> will exit with an error status, but this
 128 only happens if <literal>@valuenum@</literal> appears in your value
 129 production template.  (Since: 2.26)
 130 </para></listitem>
 131 </varlistentry>
 132
 133 <varlistentry>
 134 <term>@type@</term>
 135 <listitem><para>
 136 This is substituted either by "enum" or "flags", depending on whether the
 137 enum value definitions contained bit-shift operators or not (e.g. flags).
 138 </para></listitem>
 139 </varlistentry>
 140
 141 <varlistentry>
 142 <term>@Type@</term>
 143 <listitem><para>
 144 The same as <literal>@type@</literal> with the first letter capitalized (e.g. Flags).
 145 </para></listitem>
 146 </varlistentry>
 147
 148 <varlistentry>
 149 <term>@TYPE@</term>
 150 <listitem><para>
 151 The same as <literal>@type@</literal> with all letters uppercased (e.g. FLAGS).
 152 </para></listitem>
 153 </varlistentry>
 154
 155 <varlistentry>
 156 <term>@filename@</term>
 157 <listitem><para>
 158 The name of the input file currently being processed (e.g. foo.h).
 159 </para></listitem>
 160 </varlistentry>
 161
 162 <varlistentry>
 163 <term>@basename@</term>
 164 <listitem><para>
 165 The base name of the input file currently being processed (e.g. foo.h). (Since: 2.22)
 166 </para></listitem>
 167 </varlistentry>
 168 </variablelist>
 169 </para>
 170 </refsect2>
 171 <refsect2><title>Trigraph extensions</title>
 172 <para>
 173 Some C comments are treated specially in the parsed enum definitions,
 174 such comments start out with the trigraph sequence <literal>/*&lt;</literal>
 175 and end with the trigraph sequence <literal>&gt;*/</literal>.
 176 Per enum definition, the options "skip" and "flags" can be specified, to
 177 indicate this enum definition to be skipped, or for it to be treated as
 178 a flags definition, or to specify the common prefix to be stripped from
 179 all values to generate value nicknames, respectively. The "underscore_name"
 180 option can be used to specify the word separation used in the *_get_type()
 181 function. For instance, /*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/.
 182 </para>
 183 <para>
 184 Per value definition, the options "skip" and "nick" are supported.
 185 The former causes the value to be skipped, and the latter can be used to
 186 specify the otherwise auto-generated nickname.
 187 Examples:
 188 <informalexample><programlisting>
 189 typedef enum /*&lt; skip &gt;*/
 190 {
 191   PREFIX_FOO
 192 } PrefixThisEnumWillBeSkipped;
 193 typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
 194 {
 195   PREFIX_THE_ZEROTH_VALUE,      /*&lt; skip &gt;*/
 196   PREFIX_THE_FIRST_VALUE,
 197   PREFIX_THE_SECOND_VALUE,
 198   PREFIX_THE_THIRD_VALUE,       /*&lt; nick=the-last-value &gt;*/
 199 } PrefixTheFlagsEnum;
 200 </programlisting></informalexample>
 201 </para>
 202 </refsect2>
 203 </refsect1>
 204
 205 <refsect1><title>Options</title>
 206 <variablelist>
 207
 208 <varlistentry>
 209 <term><option>--fhead</option> <replaceable>TEXT</replaceable></term>
 210 <listitem><para>
 211 Put out <replaceable>TEXT</replaceable> prior to processing input files.
 212 </para></listitem>
 213 </varlistentry>
 214
 215 <varlistentry>
 216 <term><option>--fprod</option> <replaceable>TEXT</replaceable></term>
 217 <listitem><para>
 218 Put out <replaceable>TEXT</replaceable> everytime a new input file
 219 is being processed.
 220 </para></listitem>
 221 </varlistentry>
 222
 223 <varlistentry>
 224 <term><option>--ftail</option> <replaceable>TEXT</replaceable></term>
 225 <listitem><para>
 226 Put out <replaceable>TEXT</replaceable> after all input files have been
 227 processed.
 228 </para></listitem>
 229 </varlistentry>
 230
 231 <varlistentry>
 232 <term><option>--eprod</option> <replaceable>TEXT</replaceable></term>
 233 <listitem><para>
 234 Put out <replaceable>TEXT</replaceable> everytime an enum is encountered
 235 in the input files.
 236 </para></listitem>
 237 </varlistentry>
 238
 239 <varlistentry>
 240 <term><option>--vhead</option> <replaceable>TEXT</replaceable></term>
 241 <listitem><para>
 242 Put out <replaceable>TEXT</replaceable> before iterating over the set of
 243 values of an enum.
 244 </para></listitem>
 245 </varlistentry>
 246
 247 <varlistentry>
 248 <term><option>--vprod</option> <replaceable>TEXT</replaceable></term>
 249 <listitem><para>
 250 Put out <replaceable>TEXT</replaceable> for every value of an enum.
 251 </para></listitem>
 252 </varlistentry>
 253
 254 <varlistentry>
 255 <term><option>--vtail</option> <replaceable>TEXT</replaceable></term>
 256 <listitem><para>
 257 Put out <replaceable>TEXT</replaceable> after iterating over all values
 258 of an enum.
 259 </para></listitem>
 260 </varlistentry>
 261
 262 <varlistentry>
 263 <term><option>--comments</option> <replaceable>TEXT</replaceable></term>
 264 <listitem><para>
 265 Template for auto-generated comments, the default (for C code generations) is
 266 <literal>"/* @comment@ */"</literal>.
 267 </para></listitem>
 268 </varlistentry>
 269
 270 <varlistentry>
 271 <term><option>--template</option> <replaceable>FILE</replaceable></term>
 272 <listitem><para>
 273 Read templates from the given file. The templates are enclosed in
 274 specially-formatted C comments
 275 <informalexample><programlisting>
 276 /*** BEGIN section ***/
 277 /*** END section ***/
 278 </programlisting></informalexample>
 279 where section may be <literal>file-header</literal>,
 280 <literal>file-production</literal>, <literal>file-tail</literal>,
 281 <literal>enumeration-production</literal>, <literal>value-header</literal>,
 282 <literal>value-production</literal>, <literal>value-tail</literal> or
 283 <literal>comment</literal>.
 284 </para></listitem>
 285 </varlistentry>
 286
 287 <varlistentry>
 288 <term><option>--identifier-prefix</option> <replaceable>PREFIX</replaceable></term>
 289 <listitem><para>
 290 Indicates what portion of the enum name should be intepreted as the
 291 prefix (eg, the "<literal>Gtk</literal>" in
 292 "<literal>GtkDirectionType</literal>"). Normally this will be figured
 293 out automatically, but you may need to override the default if your
 294 namespace is capitalized oddly.
 295 </para></listitem>
 296 </varlistentry>
 297
 298 <varlistentry>
 299 <term><option>--symbol-prefix</option> <replaceable>PREFIX</replaceable></term>
 300 <listitem><para>
 301 Indicates what prefix should be used to correspond to the identifier
 302 prefix in related C function names (eg, the "<literal>gtk</literal>"
 303 in "<literal>gtk_direction_type_get_type</literal>". Equivalently,
 304 this is the lowercase version of the prefix component of the enum
 305 value names (eg, the "<literal>GTK</literal>" in
 306 "<literal>GTK_DIR_UP</literal>". The default value is the identifier
 307 prefix, converted to lowercase.
 308 </para></listitem>
 309 </varlistentry>
 310
 311 <varlistentry>
 312 <term><option>--help</option></term>
 313 <listitem><para>
 314 Print brief help and exit.
 315 </para></listitem>
 316 </varlistentry>
 317
 318 <varlistentry>
 319 <term><option>--version</option></term>
 320 <listitem><para>
 321 Print version and exit.
 322 </para></listitem>
 323 </varlistentry>
 324
 325 <varlistentry>
 326 <term><option>--output=FILE</option></term>
 327 <listitem><para>
 328 Write output to FILE instead of stdout.
 329 </para></listitem>
 330 </varlistentry>
 331
 332 </variablelist>
 333 </refsect1>
 334
 335 <refsect1><title>See also</title>
 336 <para>
 337 <citerefentry>
 338 <refentrytitle>glib-genmarshal</refentrytitle>
 339 <manvolnum>1</manvolnum>
 340 </citerefentry>
 341 </para>
 342 </refsect1>
 343 </refentry>