← Back to branch summary

~ubuntu-branches/debian/sid/glib2.0/sid

« back to all changes in this revision

Viewing changes to docs/reference/gobject/glib-mkenums.xml

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2013-05-08 06:25:57 UTC
  • mfrom: (1.27.14) (3.1.181 experimental)
  • Revision ID: package-import@ubuntu.com-20130508062557-i7gbku66mls70gi2
Tags: 2.36.1-2
Merge experimental branch, upload to unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gobject/glib-mkenums.xml
1
1
<refentry id="glib-mkenums" lang="en">
2
2
 
 
3
<refentryinfo>
 
4
  <title>gdbus</title>
 
5
  <productname>GObject</productname>
 
6
  <authorgroup>
 
7
    <author>
 
8
      <contrib>Developer</contrib>
 
9
      <firstname>Owen</firstname>
 
10
      <surname>Taylor</surname>
 
11
    </author>
 
12
  </authorgroup>
 
13
</refentryinfo>
 
14
 
3
15
<refmeta>
4
16
<refentrytitle>glib-mkenums</refentrytitle>
5
17
<manvolnum>1</manvolnum>
14
26
<refsynopsisdiv>
15
27
<cmdsynopsis>
16
28
<command>glib-mkenums</command>
17
 
<arg choice="opt" rep="repeat">options</arg>
18
 
<arg choice="opt" rep="repeat">files</arg>
 
29
<arg choice="opt" rep="repeat">OPTION</arg>
 
30
<arg choice="opt" rep="repeat">FILE</arg>
19
31
</cmdsynopsis>
20
32
</refsynopsisdiv>
21
33
 
22
34
<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 
 
35
<para><command>glib-mkenums</command> is a small perl-script utility that
 
36
parses C code to extract enum definitions and produces enum descriptions based
 
37
on text templates specified by the user. Most frequently this script is used to
 
38
produce C code that contains enum values as strings so programs can provide
27
39
value name strings for introspection.
28
40
</para>
29
 
</refsect1>
30
41
 
31
 
<refsect1><title>Invocation</title>
32
42
<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 
 
43
input. The options specified control the text that is output, certain
 
44
substitutions are performed on the text templates for keywords enclosed
35
45
in @ characters.
36
46
</para>
37
47
 
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>--identifier-prefix</option> <replaceable>prefix</replaceable></term>
122
 
<listitem><para>
123
 
Indicates what portion of the enum name should be intepreted as the
124
 
prefix (eg, the "<literal>Gtk</literal>" in
125
 
"<literal>GtkDirectionType</literal>"). Normally this will be figured
126
 
out automatically, but you may need to override the default if your
127
 
namespace is capitalized oddly.
128
 
</para></listitem>
129
 
</varlistentry>
130
 
 
131
 
<varlistentry>
132
 
<term><option>--symbol-prefix</option> <replaceable>prefix</replaceable></term>
133
 
<listitem><para>
134
 
Indicates what prefix should be used to correspond to the identifier
135
 
prefix in related C function names (eg, the "<literal>gtk</literal>"
136
 
in "<literal>gtk_direction_type_get_type</literal>". Equivalently,
137
 
this is the lowercase version of the prefix component of the enum
138
 
value names (eg, the "<literal>GTK</literal>" in
139
 
"<literal>GTK_DIR_UP</literal>". The default value is the identifier
140
 
prefix, converted to lowercase.
141
 
</para></listitem>
142
 
</varlistentry>
143
 
 
144
 
<varlistentry>
145
 
<term><option>--help</option></term>
146
 
<listitem><para>
147
 
Print brief help and exit.
148
 
</para></listitem>
149
 
</varlistentry>
150
 
 
151
 
<varlistentry>
152
 
<term><option>--version</option></term>
153
 
<listitem><para>
154
 
Print version and exit.
155
 
</para></listitem>
156
 
</varlistentry>
157
 
 
158
 
</variablelist>
159
 
</refsect2>
160
 
 
161
48
<refsect2><title>Production text substitutions</title>
162
49
<para>
163
 
Certain keywords enclosed in @ characters will be substituted in the 
164
 
emitted text. For the substitution examples of the keywords below, 
 
50
Certain keywords enclosed in @ characters will be substituted in the
 
51
emitted text. For the substitution examples of the keywords below,
165
52
the following example enum definition is assumed:
166
53
<programlisting>
167
54
typedef enum
183
70
<varlistentry>
184
71
<term>@enum_name@</term>
185
72
<listitem><para>
186
 
The enum name with words lowercase and word-separated by underscores 
 
73
The enum name with words lowercase and word-separated by underscores
187
74
(e.g. prefix_the_xenum).
188
75
</para></listitem>
189
76
</varlistentry>
191
78
<varlistentry>
192
79
<term>@ENUMNAME@</term>
193
80
<listitem><para>
194
 
The enum name with words uppercase and word-separated by underscores 
 
81
The enum name with words uppercase and word-separated by underscores
195
82
(e.g. PREFIX_THE_XENUM).
196
83
</para></listitem>
197
84
</varlistentry>
199
86
<varlistentry>
200
87
<term>@ENUMSHORT@</term>
201
88
<listitem><para>
202
 
The enum name with words uppercase and word-separated by underscores, 
 
89
The enum name with words uppercase and word-separated by underscores,
203
90
prefix stripped (e.g. THE_XENUM).
204
91
</para></listitem>
205
92
</varlistentry>
207
94
<varlistentry>
208
95
<term>@VALUENAME@</term>
209
96
<listitem><para>
210
 
The enum value name currently being processed with words uppercase and 
 
97
The enum value name currently being processed with words uppercase and
211
98
word-separated by underscores,
212
 
this is the assumed literal notation of enum values in the C sources 
 
99
this is the assumed literal notation of enum values in the C sources
213
100
(e.g. PREFIX_THE_XVALUE).
214
101
</para></listitem>
215
102
</varlistentry>
217
104
<varlistentry>
218
105
<term>@valuenick@</term>
219
106
<listitem><para>
220
 
A nick name for the enum value currently being processed, this is usually 
221
 
generated by stripping common prefix words of all the enum values of the 
222
 
current enum, the words are lowercase and underscores are substituted by a 
 
107
A nick name for the enum value currently being processed, this is usually
 
108
generated by stripping common prefix words of all the enum values of the
 
109
current enum, the words are lowercase and underscores are substituted by a
223
110
minus (e.g. the-xvalue).
224
111
</para></listitem>
225
112
</varlistentry>
239
126
<varlistentry>
240
127
<term>@type@</term>
241
128
<listitem><para>
242
 
This is substituted either by "enum" or "flags", depending on whether the 
 
129
This is substituted either by "enum" or "flags", depending on whether the
243
130
enum value definitions contained bit-shift operators or not (e.g. flags).
244
131
</para></listitem>
245
132
</varlistentry>
276
163
</refsect2>
277
164
<refsect2><title>Trigraph extensions</title>
278
165
<para>
279
 
Some C comments are treated specially in the parsed enum definitions, 
280
 
such comments start out with the trigraph sequence <literal>/*&lt;</literal> 
 
166
Some C comments are treated specially in the parsed enum definitions,
 
167
such comments start out with the trigraph sequence <literal>/*&lt;</literal>
281
168
and end with the trigraph sequence <literal>&gt;*/</literal>.
282
 
Per enum definition, the options "skip" and "flags" can be specified, to 
283
 
indicate this enum definition to be skipped, or for it to be treated as 
284
 
a flags definition, or to specify the common prefix to be stripped from 
 
169
Per enum definition, the options "skip" and "flags" can be specified, to
 
170
indicate this enum definition to be skipped, or for it to be treated as
 
171
a flags definition, or to specify the common prefix to be stripped from
285
172
all values to generate value nicknames, respectively. The "underscore_name"
286
173
option can be used to specify the word separation used in the *_get_type()
287
174
function. For instance, /*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/.
288
175
</para>
289
176
<para>
290
 
Per value definition, the options "skip" and "nick" are supported. 
291
 
The former causes the value to be skipped, and the latter can be used to 
 
177
Per value definition, the options "skip" and "nick" are supported.
 
178
The former causes the value to be skipped, and the latter can be used to
292
179
specify the otherwise auto-generated nickname.
293
180
Examples:
294
181
<programlisting>
307
194
</para>
308
195
</refsect2>
309
196
</refsect1>
 
197
 
 
198
<refsect1><title>Options</title>
 
199
<variablelist>
 
200
 
 
201
<varlistentry>
 
202
<term><option>--fhead</option> <replaceable>TEXT</replaceable></term>
 
203
<listitem><para>
 
204
Put out <replaceable>TEXT</replaceable> prior to processing input files.
 
205
</para></listitem>
 
206
</varlistentry>
 
207
 
 
208
<varlistentry>
 
209
<term><option>--fprod</option> <replaceable>TEXT</replaceable></term>
 
210
<listitem><para>
 
211
Put out <replaceable>TEXT</replaceable> everytime a new input file
 
212
is being processed.
 
213
</para></listitem>
 
214
</varlistentry>
 
215
 
 
216
<varlistentry>
 
217
<term><option>--ftail</option> <replaceable>TEXT</replaceable></term>
 
218
<listitem><para>
 
219
Put out <replaceable>TEXT</replaceable> after all input files have been
 
220
processed.
 
221
</para></listitem>
 
222
</varlistentry>
 
223
 
 
224
<varlistentry>
 
225
<term><option>--eprod</option> <replaceable>TEXT</replaceable></term>
 
226
<listitem><para>
 
227
Put out <replaceable>TEXT</replaceable> everytime an enum is encountered
 
228
in the input files.
 
229
</para></listitem>
 
230
</varlistentry>
 
231
 
 
232
<varlistentry>
 
233
<term><option>--vhead</option> <replaceable>TEXT</replaceable></term>
 
234
<listitem><para>
 
235
Put out <replaceable>TEXT</replaceable> before iterating over the set of
 
236
values of an enum.
 
237
</para></listitem>
 
238
</varlistentry>
 
239
 
 
240
<varlistentry>
 
241
<term><option>--vprod</option> <replaceable>TEXT</replaceable></term>
 
242
<listitem><para>
 
243
Put out <replaceable>TEXT</replaceable> for every value of an enum.
 
244
</para></listitem>
 
245
</varlistentry>
 
246
 
 
247
<varlistentry>
 
248
<term><option>--vtail</option> <replaceable>TEXT</replaceable></term>
 
249
<listitem><para>
 
250
Put out <replaceable>TEXT</replaceable> after iterating over all values
 
251
of an enum.
 
252
</para></listitem>
 
253
</varlistentry>
 
254
 
 
255
<varlistentry>
 
256
<term><option>--comments</option> <replaceable>TEXT</replaceable></term>
 
257
<listitem><para>
 
258
Template for auto-generated comments, the default (for C code generations) is
 
259
<literal>"/* @comment@ */"</literal>.
 
260
</para></listitem>
 
261
</varlistentry>
 
262
 
 
263
<varlistentry>
 
264
<term><option>--template</option> <replaceable>FILE</replaceable></term>
 
265
<listitem><para>
 
266
Read templates from the given file. The templates are enclosed in
 
267
specially-formatted C comments
 
268
<programlisting>
 
269
/*** BEGIN section ***/
 
270
/*** END section ***/
 
271
</programlisting>
 
272
where section may be <literal>file-header</literal>,
 
273
<literal>file-production</literal>, <literal>file-tail</literal>,
 
274
<literal>enumeration-production</literal>, <literal>value-header</literal>,
 
275
<literal>value-production</literal>, <literal>value-tail</literal> or
 
276
<literal>comment</literal>.
 
277
</para></listitem>
 
278
</varlistentry>
 
279
 
 
280
<varlistentry>
 
281
<term><option>--identifier-prefix</option> <replaceable>PREFIX</replaceable></term>
 
282
<listitem><para>
 
283
Indicates what portion of the enum name should be intepreted as the
 
284
prefix (eg, the "<literal>Gtk</literal>" in
 
285
"<literal>GtkDirectionType</literal>"). Normally this will be figured
 
286
out automatically, but you may need to override the default if your
 
287
namespace is capitalized oddly.
 
288
</para></listitem>
 
289
</varlistentry>
 
290
 
 
291
<varlistentry>
 
292
<term><option>--symbol-prefix</option> <replaceable>PREFIX</replaceable></term>
 
293
<listitem><para>
 
294
Indicates what prefix should be used to correspond to the identifier
 
295
prefix in related C function names (eg, the "<literal>gtk</literal>"
 
296
in "<literal>gtk_direction_type_get_type</literal>". Equivalently,
 
297
this is the lowercase version of the prefix component of the enum
 
298
value names (eg, the "<literal>GTK</literal>" in
 
299
"<literal>GTK_DIR_UP</literal>". The default value is the identifier
 
300
prefix, converted to lowercase.
 
301
</para></listitem>
 
302
</varlistentry>
 
303
 
 
304
<varlistentry>
 
305
<term><option>--help</option></term>
 
306
<listitem><para>
 
307
Print brief help and exit.
 
308
</para></listitem>
 
309
</varlistentry>
 
310
 
 
311
<varlistentry>
 
312
<term><option>--version</option></term>
 
313
<listitem><para>
 
314
Print version and exit.
 
315
</para></listitem>
 
316
</varlistentry>
 
317
 
 
318
</variablelist>
 
319
</refsect1>
 
320
 
310
321
<refsect1><title>See also</title>
311
322
<para>
312
323
<citerefentry>
316
327
</para>
317
328
</refsect1>
318
329
</refentry>
319
 
 
320