glib-mkenums

GLIB-MKENUMS(1)						      GLIB-MKENUMS(1)



NAME
       glib-mkenums - C language enum description generation utility

SYNOPSIS
       glib-mkenums [options...] [files...]


DESCRIPTION
	glib-mkenums is a small perl-script utility that parses C code to ex-
       tract enum definitions and produces enum descriptions  based  on	 text
       templates  specified  by the user. Most frequently this script is used
       to produce C code that contains enum values as strings so programs can
       provide value name strings for introspection.


INVOKATION
	glib-mkenums 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.


   Options
       --fhead text
	      Put out text prior to processing input files.


       --fprod text
	      Put out text everytime a new input file is being processed.


       --ftail text
	      Put out text after all input files have been processed.


       --eprod text
	      Put out text everytime an enum  is  encountered  in  the	input
	      files.


       --vhead text
	      Put  out	text  before  iterating	 over the set of values of an
	      enum.


       --vprod text
	      Put out text for every value of an enum.


       --vtail text
	      Put out text after iterating over all values of an enum.


       --comments text
	      Template for auto-generated comments, the default (for  C	 code
	      generations) is "/* @comment@ */".


       --template file
	      Read  templates from the given file. The templates are enclosed
	      in specially-formatted C comments


	      /*** BEGIN section ***/
	      /*** END section ***/

	       where section may be file-header, file-production,  file-tail,
	      enumeration-production,  value-header,  value-production,	 val-
	      ue-tail or comment.


       --help Print brief help and exit.


       --version
	      Print version and exit.


   Production text substitutions
       Certain keywords enclosed in @ characters will be substituted  in  the
       emitted text. For the substitution examples of the keywords below, the
       following example enum definition is assumed:


       typedef enum
       {
	 PREFIX_THE_XVALUE    = 1 << 3,
	 PREFIX_ANOTHER_VALUE = 1 << 4
       } PrefixTheXEnum;




       @EnumName@
	      The name of the enum currently being processed, enum names  are
	      assumed  to be properly namespaced and to use mixed capitaliza-
	      tion to separate words (e.g. PrefixTheXEnum).


       @enum_name@
	      The enum name with words lowercase and word-separated by under-
	      scores (e.g. prefix_the_xenum).


       @ENUMNAME@
	      The enum name with words uppercase and word-separated by under-
	      scores (e.g. PREFIX_THE_XENUM).


       @ENUMSHORT@
	      The enum name with words uppercase and word-separated by under-
	      scores, prefix stripped (e.g. THE_XENUM).


       @VALUENAME@
	      The enum value name currently being processed with words upper-
	      case and word-separated by underscores,  this  is	 the  assumed
	      literal  notation	 of  enum  values in the C sources (e.g. PRE-
	      FIX_THE_XVALUE).


       @valuenick@
	      A nick name for the enum value currently being processed,	 this
	      is  usually  generated  by stripping common prefix words of all
	      the enum values of the current enum, the	words  are  lowercase
	      and underscores are substituted by a minus (e.g. the-xvalue).


       @type@ This  is	substituted either by "enum" or "flags", depending on
	      whether the enum value definitions contained  bit-shift  opera-
	      tors or not (e.g. flags).


       @Type@ The  same	 as  @type@  with  the first letter capitalized (e.g.
	      Flags).


       @TYPE@ The same as @type@ with all letters uppercased (e.g. FLAGS).


       @filename@
	      The name of the input  file  currently  being  processed	(e.g.
	      foo.h).



   Trigraph extensions
       Some  C comments are treated specially in the parsed enum definitions,
       such comments start out with the trigraph sequence /*<  and  end	 with
       the trigraph sequence >*/. Per enum definition, the options "skip" and
       "flags" can be specified, to  indicate  this  enum  definition  to  be
       skipped,	 or for it to be treated as a flags definition, or to specify
       the common prefix to be stripped from all  values  to  generate	value
       nicknames,  respectively.  The  "lowercase_name" option can be used to
       specify the word separation used in the *_get_type() function. For in-
       stance, /*< lowercase_name=gnome_vfs_uri_hide_options >*/.


       Per value definition, the options "skip" and "nick" are supported. The
       former causes the value to be skipped, and the latter can be  used  to
       specify the otherwise auto-generated nickname. Examples:


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




SEE ALSO
	glib-genmarshal(1)




							      GLIB-MKENUMS(1)