1 | .TH GLIB-MKENUMS 1 "27 Jul 2002" |
---|
2 | .SH NAME |
---|
3 | glib-mkenums \- C language enum description generation utility |
---|
4 | .SH SYNOPSIS |
---|
5 | |
---|
6 | \fBglib-mkenums\fP [\fIoptions\fP] [\fIfiles...\fP] |
---|
7 | |
---|
8 | .SH DESCRIPTION |
---|
9 | \fBglib-mkenums\fP is a small perl-script utility that parses C code to extract enum |
---|
10 | definitions and produces enum descriptions based on text templates specified |
---|
11 | by the user. Most frequently this script is used to produce C code that contains |
---|
12 | enum values as strings so programs can provide value name strings for introspection. |
---|
13 | |
---|
14 | .SH INVOCATION |
---|
15 | |
---|
16 | \fBglib-mkenums\fP takes a list of valid C code files as input. The options |
---|
17 | specified control the text that is output, certain substitutions are performed |
---|
18 | on the text templates for keywords enclosed in @ characters. |
---|
19 | |
---|
20 | |
---|
21 | .SS Options |
---|
22 | .TP |
---|
23 | \fI--fhead <text> |
---|
24 | Put out <text> prior to processing input files. |
---|
25 | .TP |
---|
26 | \fI--fprod <text> |
---|
27 | Put out <text> everytime a new input file is being processed. |
---|
28 | .TP |
---|
29 | \fI--ftail <text> |
---|
30 | Put out <text> after all input files have been processed. |
---|
31 | .TP |
---|
32 | \fI--eprod <text> |
---|
33 | Put out <text> everytime an enum is encountered in the input files. |
---|
34 | .TP |
---|
35 | \fI--vhead <text> |
---|
36 | Put out <text> before iterating over the set of values of an enum. |
---|
37 | .TP |
---|
38 | \fI--vprod <text> |
---|
39 | Put out <text> for every value of an enum. |
---|
40 | .TP |
---|
41 | \fI--vtail <text> |
---|
42 | Put out <text> after iterating over all values of an enum. |
---|
43 | .TP |
---|
44 | \fI--comments <text> |
---|
45 | Template for auto-generated comments, the default (for C code generations) is |
---|
46 | "/* @comment@ */". |
---|
47 | .TP |
---|
48 | \fI--template file |
---|
49 | Read templates from the given file. The templates are enclosed in |
---|
50 | specially-formatted C comments |
---|
51 | .PP |
---|
52 | .RS |
---|
53 | .nf |
---|
54 | /*** BEGIN section ***/ |
---|
55 | /*** END section ***/ |
---|
56 | .fi |
---|
57 | .PP |
---|
58 | where section may be file-header, file-production, file-tail, |
---|
59 | enumeration-production, value-header, value-production, value-tail or |
---|
60 | comment. |
---|
61 | .TP |
---|
62 | \fI-h, --help\fP |
---|
63 | Print brief help and exit. |
---|
64 | .TP |
---|
65 | \fI-v, --version\fP |
---|
66 | Print version and exit. |
---|
67 | .PP |
---|
68 | |
---|
69 | |
---|
70 | .SS Production text substitutions |
---|
71 | Certain keywords enclosed in @ characters will be substituted in the outputted |
---|
72 | text. For the substitution examples of the keywords below, the following example |
---|
73 | enum definition is assumed: |
---|
74 | .PP |
---|
75 | .RS |
---|
76 | .nf |
---|
77 | typedef enum |
---|
78 | { |
---|
79 | PREFIX_THE_XVALUE = 1 << 3, |
---|
80 | PREFIX_ANOTHER_VALUE = 1 << 4 |
---|
81 | } PrefixTheXEnum; |
---|
82 | .fi |
---|
83 | .RE |
---|
84 | |
---|
85 | .TP 12 |
---|
86 | \fI@EnumName@ |
---|
87 | The name of the enum currently being processed, enum names are assumed to be |
---|
88 | properly namespaced and to use mixed capitalization to separate |
---|
89 | words (e.g. PrefixTheXEnum). |
---|
90 | .TP 12 |
---|
91 | \fI@enum_name@ |
---|
92 | The enum name with words lowercase and word-separated by underscores (e.g. prefix_the_xenum). |
---|
93 | .TP 12 |
---|
94 | \fI@ENUMNAME@ |
---|
95 | The enum name with words uppercase and word-separated by underscores (e.g. PREFIX_THE_XENUM). |
---|
96 | .TP 12 |
---|
97 | \fI@ENUMSHORT@ |
---|
98 | The enum name with words uppercase and word-separated by underscores, prefix stripped (e.g. THE_XENUM). |
---|
99 | .TP 12 |
---|
100 | \fI@VALUENAME@ |
---|
101 | The enum value name currently being processed with words uppercase and word-separated by underscores, |
---|
102 | this is the assumed literal notation of enum values in the C sources (e.g. PREFIX_THE_XVALUE). |
---|
103 | .TP 12 |
---|
104 | \fI@valuenick@ |
---|
105 | A nick name for the enum value currently being processed, this is usually generated by stripping |
---|
106 | common prefix words of all the enum values of the current enum, the words are lowercase and |
---|
107 | underscores are substituted by a minus (e.g. the-xvalue). |
---|
108 | .TP 12 |
---|
109 | \fI@type@ |
---|
110 | This is substituted either by "enum" or "flags", depending on whether the enum value definitions |
---|
111 | contained bit-shift operators or not (e.g. flags). |
---|
112 | .TP 12 |
---|
113 | \fI@Type@ |
---|
114 | The same as \fI@type@\fP with the first letter capitalized (e.g. Flags). |
---|
115 | .TP 12 |
---|
116 | \fI@TYPE@ |
---|
117 | The same as \fI@type@\fP with all letters uppercased (e.g. FLAGS). |
---|
118 | .TP 12 |
---|
119 | \fI@filename@ |
---|
120 | The name of the input file currently being processed (e.g. foo.h). |
---|
121 | |
---|
122 | .SS Trigraph extensions |
---|
123 | Some C comments are treated specially in the parsed enum definitions, such comments |
---|
124 | start out with the trigraph sequence "/*<" and end with the trigraph sequence ">*/". |
---|
125 | .PP |
---|
126 | Per enum definition, the options "skip" and "flags" can be specified, to indicate |
---|
127 | this enum definition to be skipped, or for it to be treated as a flags definition, or |
---|
128 | to specify the common prefix to be stripped from all values to generate value nicknames, |
---|
129 | respectively. The "lowercase_name" option can be used to specify the word separation used |
---|
130 | in the *_get_type() function. For instance, /*< lowercase_name=gnome_vfs_uri_hide_options >*/. |
---|
131 | .PP |
---|
132 | Per value definition, the options "skip" and "nick" are supported. The former causes the |
---|
133 | value to be skipped, and the latter can be used to specify the otherwise auto-generated |
---|
134 | nickname. |
---|
135 | Examples: |
---|
136 | .PP |
---|
137 | .RS |
---|
138 | .nf |
---|
139 | typedef enum /*< skip >*/ |
---|
140 | { |
---|
141 | PREFIX_FOO |
---|
142 | } PrefixThisEnumWillBeSkipped; |
---|
143 | typedef enum /*< flags,prefix=PREFIX >*/ |
---|
144 | { |
---|
145 | PREFIX_THE_ZEROTH_VALUE, /*< skip >*/ |
---|
146 | PREFIX_THE_FIRST_VALUE, |
---|
147 | PREFIX_THE_SECOND_VALUE, |
---|
148 | PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/ |
---|
149 | } PrefixTheFlagsEnum; |
---|
150 | .fi |
---|
151 | .RE |
---|
152 | |
---|
153 | .SH SEE ALSO |
---|
154 | \fB |
---|
155 | glib-genmarshal(1) |
---|
156 | \fP |
---|
157 | |
---|
158 | .SH BUGS |
---|
159 | None known yet. |
---|
160 | |
---|
161 | .SH AUTHOR |
---|
162 | .B glib-mkenums |
---|
163 | was written by Tim Janik <timj@gtk.org> and Owen Taylor <otaylor@redhat.com>. |
---|
164 | .PP |
---|
165 | This manual page was provided by Tim Janik <timj@gtk.org>. |
---|