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