<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!--ARC : LSARC 2001/384 Gtk+ 2.0 / glib 2.0-->
<!--ARC : LSARC 2001/781 location of GTK/Glib-->
<!--ARC : PSARC 2001/804 GTK/Glib becomes Contracted External-->
<!ENTITY cmd "glib-mkenums">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY suncopy "Copyright (c) 2003,2006 Sun Microsystems, Inc. All Rights Reserved.">
]>
<refentry id="glib-mkenums-1">
<!-- %Z%%M% %I% %E% SMI; -->
<refmeta><refentrytitle>glib-mkenums</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">7 Apr 2003</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&release;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">&suncopy;</refmiscinfo>
</refmeta>
<indexterm><primary>glib-mkenums</primary></indexterm><indexterm><primary>
generate C language <literal>enum</literal> description</primary></indexterm>
<refnamediv id="glib-mkenums-1-name"><refname>glib-mkenums</refname><refpurpose>
generate C language <literal>enum</literal> description</refpurpose></refnamediv>
<refsynopsisdiv id="glib-mkenums-1-synp"><title>&synp-tt;</title>
<cmdsynopsis><command>&cmd;</command>
<arg choice="opt"><option>-comments <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>-eprod <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>-fhead <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>-fprod <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>-ftail <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>-help</option></arg>
<arg choice="opt"><option>-template <replaceable>file</replaceable></option></arg>
<arg choice="opt"><option>-version</option></arg>
<arg choice="opt"><option>-vhead <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>-vprod <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>-vtail <replaceable>text</replaceable></option></arg>
<arg choice="opt" rep="repeat"><option role="nodash"><replaceable>file</replaceable></option></arg>
</cmdsynopsis></refsynopsisdiv>

<refsect1 id="glib-mkenums-1-desc"><title>&desc-tt;</title>
<para>
<command>&cmd;</command> parses C code to extract <literal>enum</literal>
definitions, and produces <literal>enum</literal> descriptions based on text
templates specified by the user. <command>&cmd;</command> produces C code
that contains <literal>enum</literal> values as strings, which allows programs
to provide value name strings for introspection.
</para>

<para>
<command>glib-mkenums</command> takes a list of valid C code files as input.
The options specified control the text that is output, certain substitutions
are performed on the text templates for keywords enclosed in @ characters.
</para>
</refsect1>

<refsect1 id="glib-mkenums-1-exde"><title>&exde-tt;</title>
<para>
This section provides more information about text substitution and trigraph
extensions.
</para>

<refsect2 id="glib-mkenums-1-exde-tsub"><title>Text Substitution</title>
<para>
<command>&cmd;</command> substitutes certain keywords, which are enclosed in
@ characters, when creating the output text. For the substitution examples of
the keywords in this section, the following example <literal>enum</literal>
definition is assumed:
</para>

<screen>
typedef enum
{
  PREFIX_THE_XVALUE    = 1 &lt;&lt; 3,
  PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
} PrefixTheXEnum;
</screen>

<para>
<command>&cmd;</command> substitutes the following keywords:
</para>

<variablelist termlength="narrow">
<varlistentry>
<term><literal>@EnumName@</literal></term>
<listitem><para>
The name of the <literal>enum</literal> currently being
processed. <literal>enum</literal> names are assumed to be properly namespaced
and to use mixed capitalization to separate words (for example,
<literal>PrefixTheXEnum</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@enum_name@</literal></term>
<listitem><para>
The <literal>enum</literal> name with words in lowercase and each word
separated by underscores (for example, <literal>prefix_the_xenum</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@ENUMNAME@</literal></term>
<listitem><para>
The <literal>enum</literal> name with words in uppercase and each word
separated by underscores (for example, <literal>PREFIX_THE_XENUM</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@ENUMSHORT@</literal></term>
<listitem><para>
The <literal>enum</literal> name with words in uppercase and each word separated
by underscores, and with the prefix stripped (for example, <literal>THE_XENUM
</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@VALUENAME@</literal></term>
<listitem><para>
The <literal>enum</literal> value name currently being processed, with words
in uppercase and each word separated by underscores. This is the assumed literal
notation of <literal>enum</literal> values in the C sources (for example,
<literal>PREFIX_THE_XVALUE</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@valuenick@</literal></term>
<listitem><para>
A nickname for the <literal>enum</literal> value currently being processed.
This is usually generated by stripping the common prefix words of all of the
<literal>enum</literal> values of the current <literal>enum</literal>, with
words in lowercase and underscores substituted by hyphens (for example,
<literal>the-xvalue</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@type@</literal></term>
<listitem><para>
This is substituted either by "<literal>enum</literal>" or
"<literal>flags</literal>", depending on whether the <literal>enum</literal>
value definitions contain bit-shift operators or not (for example,
<literal>flags</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@Type@</literal></term>
<listitem><para>
Same as <literal>@type@</literal>, but with the first letter capitalized (for
example, <literal>Flags</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@TYPE@</literal></term>
<listitem><para>
Same as <literal>@type@</literal>, but with all letters in uppercase (for
example, <literal>FLAGS</literal>).
</para></listitem></varlistentry>
<varlistentry>
<term><literal>@filename@</literal></term>
<listitem><para>
The name of the input file currently being processed (for example,
<literal>foo.h</literal>).
</para></listitem></varlistentry>
</variablelist>
</refsect2>

<refsect2 id="glib-mkenums-1-exde-trex"><title>Trigraph Extensions</title>
<para>
Some C comments in the parsed <literal>enum</literal> definitions are treated
as special. Such comments start with the trigraph sequence
<literal>/*&lt;</literal> and end with the trigraph sequence
<literal>>*/</literal>. 
</para>
<para>
Per <literal>enum</literal> definition, the "<literal>skip</literal>" and
"<literal>flags</literal>" options are supported. The <literal>skip</literal>
option indicates that this <literal>enum</literal> definition should be
skipped.  The <literal>flags</literal> option specifies that this
<literal>enum</literal> definition should be treated as a flags definition, or
specifies the common prefix to be stripped from all values to generate value
nicknames.  The "<literal>underscore_name</literal>" option can be used to
specify the underscorized name variant used in the *_get_type() function and
*_TYPE_* macro.  For instance:
</para>

<screen>
/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/
</screen>

<para>
Per value definition, the "<literal>skip</literal>" and
"<literal>nick</literal>" options are supported. The <literal>skip</literal>
option causes the value to be skipped. The <literal>nick</literal> option
specifies the otherwise autogenerated nickname.
</para>
</refsect2>
</refsect1>

<refsect1 id="glib-mkenums-1-opts"><title>&opts-tt;</title>
<para>
The following options are supported:
</para>
<variablelist termlength="medium"><varlistentry>
<term><option>-comments <replaceable> text</replaceable></option></term>
<listitem><para>
Template <replaceable>text</replaceable> for auto-generated comments, the
default (for C code generation) is <screen>"/* @comment@ */"</screen>
</para></listitem></varlistentry>
<varlistentry>
<term><option>-eprod <replaceable>text</replaceable></option></term>
<listitem><para>
Output <replaceable>text</replaceable> every time an <literal>enum</literal>
occurs in the input files.
</para></listitem></varlistentry>
<varlistentry>
<term><option>-fhead <replaceable>text</replaceable></option></term>
<listitem><para>
Output <replaceable>text</replaceable> prior to processing input files.
</para>
</listitem></varlistentry>
<varlistentry>
<term><option>-fprod <replaceable>text</replaceable></option></term>
<listitem><para>
Output <replaceable>text</replaceable> every time a new input file is
processed.
</para>
</listitem></varlistentry>
<varlistentry>
<term><option>-ftail <replaceable>text</replaceable></option></term>
<listitem><para>
Output <replaceable>text</replaceable> after all input files have been
processed.
</para>
</listitem></varlistentry>
<varlistentry>
<term><option role="nodash">-h</option>, <option>-help</option></term>
<listitem><para>
Show usage and basic help information.
</para>
</listitem></varlistentry>
<varlistentry>
<term><option>-template <replaceable>file</replaceable></option></term>
<listitem><para>
Read template from the given <replaceable>file</replaceable>.  The templates
are enclosed in specially-formatted C comments
</para>
<para><screen>
/*** BEGIN <replaceable>section</replaceable> ***/
/*** END <replaceable>section</replaceable> ***/
</screen></para>
<para>
where <replaceable>section</replaceable> may be file-header, file-production,
file-tail, enumeration-production, value-header, value-production, value-tail,
or comment.
</para>
</listitem></varlistentry>
<varlistentry>
<term><option role="nodash">-v</option>, <option>-version</option></term>
<listitem><para>
Show version information.
</para></listitem></varlistentry>
<varlistentry>
<term><option>-vhead <replaceable>text</replaceable></option></term>
<listitem><para>
Output <replaceable>text</replaceable> before iterating the set of values of an
<literal>enum</literal>.
</para></listitem></varlistentry>
<varlistentry>
<term><option>-vprod <replaceable>text</replaceable></option></term>
<listitem><para>
Output <replaceable>text</replaceable> for every value of an
<literal>enum</literal>.
</para></listitem></varlistentry>
<varlistentry>
<term><option>-vtail <replaceable>text</replaceable></option></term>
<listitem><para>
Output <replaceable>text</replaceable> after iterating all values of an
<literal>enum</literal>.
</para></listitem></varlistentry>
</variablelist></refsect1>

<refsect1 id="glib-mkenums-1-oper"><title>&oper-tt;</title>
<para>
The following operands are supported:
</para>
<variablelist termlength="medium"><varlistentry>
<term><option role="nodash"><replaceable>file</replaceable></option></term>
<listitem><para>
Specifies a valid C code file.
</para>
</listitem></varlistentry>
</variablelist>
</refsect1>

<refsect1 id="glib-mkenums-1-exam"><title>&exam-tt;</title>
<example role="example"><title>Examples of Trigraph Extensions
</title>

<para><screen>
typedef enum /*&lt; skip >*/
{
  PREFIX_FOO
} PrefixThisEnumWillBeSkipped;
typedef enum /*&lt; flags,prefix=PREFIX >*/
{
  PREFIX_THE_ZEROTH_VALUE,    /*&lt; skip >*/
  PREFIX_THE_FIRST_VALUE,
  PREFIX_THE_SECOND_VALUE,
  PREFIX_THE_THIRD_VALUE,     /*&lt; nick=the-last-value >*/
} PrefixTheFlagsEnum;

</screen></para></example>
</refsect1>

<refsect1 id="glib-mkenums-1-exit"><title>&exit-tt;</title>
<para>
The following exit values are returned:
</para>

<variablelist termlength="xtranarrow"><varlistentry>
<term><returnvalue>0</returnvalue></term>
<listitem><para>
Application exited successfully
</para></listitem></varlistentry>
<varlistentry>
<term><returnvalue>>0</returnvalue></term>
<listitem><para>
Application exited with failure
</para></listitem></varlistentry>
</variablelist>
</refsect1>

<refsect1 id="glib-mkenums-1-file"><title>&file-tt;</title>
<para>
The following files are used by this application:
</para>

<variablelist termlength="wide"><varlistentry>
<term><filename>/usr/bin/&cmd;</filename></term>
<listitem><para>
The command-line executable for the application.
</para></listitem></varlistentry>
<varlistentry>
<term><filename>/usr/share/gtk-doc/html/glib</filename></term>
<listitem><para>
Location of developer documentation
</para></listitem></varlistentry>
</variablelist>
</refsect1>

<refsect1 id="glib-mkenums-1-attr"><title>&attr-tt;</title>
<para>
See
<olink targetdocent="REFMAN5" localinfo="attributes-5">
<citerefentry><refentrytitle>attributes</refentrytitle>
<manvolnum>5</manvolnum></citerefentry></olink>
for descriptions of the following attributes:
</para>

<informaltable frame="all">
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="COLSPEC0" colwidth="1*">
<colspec colname="COLSPEC1" colwidth="1*">
<thead>
<row>
<entry align="center" valign="middle">ATTRIBUTE TYPE</entry>
<entry align="center" valign="middle">ATTRIBUTE VALUE</entry>
</row>
</thead>
<tbody>
<row>
<entry><para>Availability</para></entry>
<entry><para>SUNWglib2-devel</para></entry>
</row>
<row>
<entry colname="COLSPEC0"><para>Interface stability</para></entry>
<entry colname="COLSPEC1"><para>Committed</para></entry>
</row>
</tbody></tgroup></informaltable>
</refsect1>

<refsect1 id="glib-mkenums-1-also"><title>&also-tt;</title>
<!--Reference to another man page-->
<!--Reference to a Help manual-->
<!--Reference to a book.-->
<para>
<citerefentry><refentrytitle>gdk-pixbuf-source</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gdk-pixbuf-query-loaders</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>glib-genmarshal</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>glib-gettextize</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gobject-query</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gtk-query-immodules-2.0</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gtk-update-icon-cache</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>libglib-2.0</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>gnome-interfaces</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
<refsect1 id="glib-mkenums-1-note"><title>&note-tt;</title>
<para>
Written by Tim Janik.  Updated by Brian Cameron, Sun Microsystems Inc., 2003,
2006.
</para>
</refsect1>
</refentry>
