docs/reference/gobject/glib-mkenums.xml

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