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>--help</option></term>
 122 <listitem><para>
 123 Print brief help and exit.
 124 </para></listitem>
 125 </varlistentry>
 126
 127 <varlistentry>
 128 <term><option>--version</option></term>
 129 <listitem><para>
 130 Print version and exit.
 131 </para></listitem>
 132 </varlistentry>
 133
 134 </variablelist>
 135 </refsect2>
 136
 137 <refsect2><title>Production text substitutions</title>
 138 <para>
 139 Certain keywords enclosed in @ characters will be substituted in the
 140 emitted text. For the substitution examples of the keywords below,
 141 the following example enum definition is assumed:
 142 <programlisting>
 143 typedef enum
 144 {
 145   PREFIX_THE_XVALUE    = 1 &lt;&lt; 3,
 146   PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
 147 } PrefixTheXEnum;
 148 </programlisting>
 149 <variablelist>
 150 <varlistentry>
 151 <term>@EnumName@</term>
 152 <listitem><para>
 153 The name of the enum currently being processed, enum names are assumed to be
 154 properly namespaced and to use mixed capitalization to separate
 155 words (e.g. PrefixTheXEnum).
 156 </para></listitem>
 157 </varlistentry>
 158
 159 <varlistentry>
 160 <term>@enum_name@</term>
 161 <listitem><para>
 162 The enum name with words lowercase and word-separated by underscores
 163 (e.g. prefix_the_xenum).
 164 </para></listitem>
 165 </varlistentry>
 166
 167 <varlistentry>
 168 <term>@ENUMNAME@</term>
 169 <listitem><para>
 170 The enum name with words uppercase and word-separated by underscores
 171 (e.g. PREFIX_THE_XENUM).
 172 </para></listitem>
 173 </varlistentry>
 174
 175 <varlistentry>
 176 <term>@ENUMSHORT@</term>
 177 <listitem><para>
 178 The enum name with words uppercase and word-separated by underscores,
 179 prefix stripped (e.g. THE_XENUM).
 180 </para></listitem>
 181 </varlistentry>
 182
 183 <varlistentry>
 184 <term>@VALUENAME@</term>
 185 <listitem><para>
 186 The enum value name currently being processed with words uppercase and
 187 word-separated by underscores,
 188 this is the assumed literal notation of enum values in the C sources
 189 (e.g. PREFIX_THE_XVALUE).
 190 </para></listitem>
 191 </varlistentry>
 192
 193 <varlistentry>
 194 <term>@valuenick@</term>
 195 <listitem><para>
 196 A nick name for the enum value currently being processed, this is usually
 197 generated by stripping common prefix words of all the enum values of the
 198 current enum, the words are lowercase and underscores are substituted by a
 199 minus (e.g. the-xvalue).
 200 </para></listitem>
 201 </varlistentry>
 202
 203 <varlistentry>
 204 <term>@valuenum@</term>
 205 <listitem><para>
 206 The integer value for the enum value currently being processed.  This is
 207 calculated by using <command>perl</command> to attempt to evaluate the
 208 expression as it appears in the C source code.  If evaluation fails then
 209 <command>glib-mkenums</command> will exit with an error status, but this
 210 only happens if <literal>@valuenum@</literal> appears in your value
 211 production template.  (Since: 2.26)
 212 </para></listitem>
 213 </varlistentry>
 214
 215 <varlistentry>
 216 <term>@type@</term>
 217 <listitem><para>
 218 This is substituted either by "enum" or "flags", depending on whether the
 219 enum value definitions contained bit-shift operators or not (e.g. flags).
 220 </para></listitem>
 221 </varlistentry>
 222
 223 <varlistentry>
 224 <term>@Type@</term>
 225 <listitem><para>
 226 The same as <literal>@type@</literal> with the first letter capitalized (e.g. Flags).
 227 </para></listitem>
 228 </varlistentry>
 229
 230 <varlistentry>
 231 <term>@TYPE@</term>
 232 <listitem><para>
 233 The same as <literal>@type@</literal> with all letters uppercased (e.g. FLAGS).
 234 </para></listitem>
 235 </varlistentry>
 236
 237 <varlistentry>
 238 <term>@filename@</term>
 239 <listitem><para>
 240 The name of the input file currently being processed (e.g. foo.h).
 241 </para></listitem>
 242 </varlistentry>
 243
 244 <varlistentry>
 245 <term>@basename@</term>
 246 <listitem><para>
 247 The base name of the input file currently being processed (e.g. foo.h). (Since: 2.22)
 248 </para></listitem>
 249 </varlistentry>
 250 </variablelist>
 251 </para>
 252 </refsect2>
 253 <refsect2><title>Trigraph extensions</title>
 254 <para>
 255 Some C comments are treated specially in the parsed enum definitions,
 256 such comments start out with the trigraph sequence <literal>/*&lt;</literal>
 257 and end with the trigraph sequence <literal>&gt;*/</literal>.
 258 Per enum definition, the options "skip" and "flags" can be specified, to
 259 indicate this enum definition to be skipped, or for it to be treated as
 260 a flags definition, or to specify the common prefix to be stripped from
 261 all values to generate value nicknames, respectively. The "lowercase_name"
 262 option can be used to specify the word separation used in the *_get_type()
 263 function. For instance, /*&lt; lowercase_name=gnome_vfs_uri_hide_options &gt;*/.
 264 </para>
 265 <para>
 266 Per value definition, the options "skip" and "nick" are supported.
 267 The former causes the value to be skipped, and the latter can be used to
 268 specify the otherwise auto-generated nickname.
 269 Examples:
 270 <programlisting>
 271 typedef enum /*&lt; skip &gt;*/
 272 {
 273   PREFIX_FOO
 274 } PrefixThisEnumWillBeSkipped;
 275 typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
 276 {
 277   PREFIX_THE_ZEROTH_VALUE,      /*&lt; skip &gt;*/
 278   PREFIX_THE_FIRST_VALUE,
 279   PREFIX_THE_SECOND_VALUE,
 280   PREFIX_THE_THIRD_VALUE,       /*&lt; nick=the-last-value &gt;*/
 281 } PrefixTheFlagsEnum;
 282 </programlisting>
 283 </para>
 284 </refsect2>
 285 </refsect1>
 286 <refsect1><title>See also</title>
 287 <para>
 288 <citerefentry>
 289 <refentrytitle>glib-genmarshal</refentrytitle>
 290 <manvolnum>1</manvolnum>
 291 </citerefentry>
 292 </para>
 293 </refsect1>
 294 </refentry>
 295
 296