1 | /* goption.h - Option parser |
2 | * |
3 | * Copyright (C) 2004 Anders Carlsson <andersca@gnome.org> |
4 | * |
5 | * SPDX-License-Identifier: LGPL-2.1-or-later |
6 | * |
7 | * This library is free software; you can redistribute it and/or |
8 | * modify it under the terms of the GNU Lesser General Public |
9 | * License as published by the Free Software Foundation; either |
10 | * version 2.1 of the License, or (at your option) any later version. |
11 | * |
12 | * This library is distributed in the hope that it will be useful, |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | * Lesser General Public License for more details. |
16 | * |
17 | * You should have received a copy of the GNU Lesser General Public License |
18 | * along with this library; if not, see <http://www.gnu.org/licenses/>. |
19 | */ |
20 | |
21 | #ifndef __G_OPTION_H__ |
22 | #define __G_OPTION_H__ |
23 | |
24 | #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) |
25 | #error "Only <glib.h> can be included directly." |
26 | #endif |
27 | |
28 | #include <glib/gerror.h> |
29 | #include <glib/gquark.h> |
30 | |
31 | G_BEGIN_DECLS |
32 | |
33 | /** |
34 | * GOptionContext: |
35 | * |
36 | * A `GOptionContext` struct defines which options |
37 | * are accepted by the commandline option parser. The struct has only private |
38 | * fields and should not be directly accessed. |
39 | */ |
40 | typedef struct _GOptionContext GOptionContext; |
41 | |
42 | /** |
43 | * GOptionGroup: |
44 | * |
45 | * A `GOptionGroup` struct defines the options in a single |
46 | * group. The struct has only private fields and should not be directly accessed. |
47 | * |
48 | * All options in a group share the same translation function. Libraries which |
49 | * need to parse commandline options are expected to provide a function for |
50 | * getting a `GOptionGroup` holding their options, which |
51 | * the application can then add to its #GOptionContext. |
52 | */ |
53 | typedef struct _GOptionGroup GOptionGroup; |
54 | typedef struct _GOptionEntry GOptionEntry; |
55 | |
56 | /** |
57 | * GOptionFlags: |
58 | * @G_OPTION_FLAG_NONE: No flags. Since: 2.42. |
59 | * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in `--help` output. |
60 | * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the |
61 | * `--help` output, even if it is defined in a group. |
62 | * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this |
63 | * flag indicates that the sense of the option is reversed. i.e. %FALSE will |
64 | * be stored into the argument rather than %TRUE. |
65 | * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, |
66 | * this flag indicates that the callback does not take any argument |
67 | * (like a %G_OPTION_ARG_NONE option). Since 2.8 |
68 | * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK |
69 | * kind, this flag indicates that the argument should be passed to the |
70 | * callback in the GLib filename encoding rather than UTF-8. Since 2.8 |
71 | * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK |
72 | * kind, this flag indicates that the argument supply is optional. |
73 | * If no argument is given then data of %GOptionParseFunc will be |
74 | * set to NULL. Since 2.8 |
75 | * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict |
76 | * resolution which prefixes long option names with `groupname-` if |
77 | * there is a conflict. This option should only be used in situations |
78 | * where aliasing is necessary to model some legacy commandline interface. |
79 | * It is not safe to use this option, unless all option groups are under |
80 | * your direct control. Since 2.8. |
81 | * |
82 | * Flags which modify individual options. |
83 | */ |
84 | typedef enum |
85 | { |
86 | G_OPTION_FLAG_NONE = 0, |
87 | G_OPTION_FLAG_HIDDEN = 1 << 0, |
88 | G_OPTION_FLAG_IN_MAIN = 1 << 1, |
89 | G_OPTION_FLAG_REVERSE = 1 << 2, |
90 | G_OPTION_FLAG_NO_ARG = 1 << 3, |
91 | G_OPTION_FLAG_FILENAME = 1 << 4, |
92 | G_OPTION_FLAG_OPTIONAL_ARG = 1 << 5, |
93 | G_OPTION_FLAG_NOALIAS = 1 << 6 |
94 | } GOptionFlags; |
95 | |
96 | /** |
97 | * GOptionArg: |
98 | * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags or booleans. |
99 | * @G_OPTION_ARG_STRING: The option takes a UTF-8 string argument. |
100 | * @G_OPTION_ARG_INT: The option takes an integer argument. |
101 | * @G_OPTION_ARG_CALLBACK: The option provides a callback (of type |
102 | * #GOptionArgFunc) to parse the extra argument. |
103 | * @G_OPTION_ARG_FILENAME: The option takes a filename as argument, which will |
104 | be in the GLib filename encoding rather than UTF-8. |
105 | * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple |
106 | * uses of the option are collected into an array of strings. |
107 | * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, |
108 | * multiple uses of the option are collected into an array of strings. |
109 | * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument |
110 | * can be formatted either for the user's locale or for the "C" locale. |
111 | * Since 2.12 |
112 | * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like |
113 | * %G_OPTION_ARG_INT but for larger numbers. The number can be in |
114 | * decimal base, or in hexadecimal (when prefixed with `0x`, for |
115 | * example, `0xffffffff`). Since 2.12 |
116 | * |
117 | * The #GOptionArg enum values determine which type of extra argument the |
118 | * options expect to find. If an option expects an extra argument, it can |
119 | * be specified in several ways; with a short option: `-x arg`, with a long |
120 | * option: `--name arg` or combined in a single argument: `--name=arg`. |
121 | */ |
122 | typedef enum |
123 | { |
124 | G_OPTION_ARG_NONE, |
125 | G_OPTION_ARG_STRING, |
126 | G_OPTION_ARG_INT, |
127 | G_OPTION_ARG_CALLBACK, |
128 | G_OPTION_ARG_FILENAME, |
129 | G_OPTION_ARG_STRING_ARRAY, |
130 | G_OPTION_ARG_FILENAME_ARRAY, |
131 | G_OPTION_ARG_DOUBLE, |
132 | G_OPTION_ARG_INT64 |
133 | } GOptionArg; |
134 | |
135 | /** |
136 | * GOptionArgFunc: |
137 | * @option_name: The name of the option being parsed. This will be either a |
138 | * single dash followed by a single letter (for a short name) or two dashes |
139 | * followed by a long option name. |
140 | * @value: The value to be parsed. |
141 | * @data: User data added to the #GOptionGroup containing the option when it |
142 | * was created with g_option_group_new() |
143 | * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED |
144 | * is intended to be used for errors in #GOptionArgFunc callbacks. |
145 | * |
146 | * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK |
147 | * options. |
148 | * |
149 | * Returns: %TRUE if the option was successfully parsed, %FALSE if an error |
150 | * occurred, in which case @error should be set with g_set_error() |
151 | */ |
152 | typedef gboolean (*GOptionArgFunc) (const gchar *option_name, |
153 | const gchar *value, |
154 | gpointer data, |
155 | GError **error); |
156 | |
157 | /** |
158 | * GOptionParseFunc: |
159 | * @context: The active #GOptionContext |
160 | * @group: The group to which the function belongs |
161 | * @data: User data added to the #GOptionGroup containing the option when it |
162 | * was created with g_option_group_new() |
163 | * @error: A return location for error details |
164 | * |
165 | * The type of function that can be called before and after parsing. |
166 | * |
167 | * Returns: %TRUE if the function completed successfully, %FALSE if an error |
168 | * occurred, in which case @error should be set with g_set_error() |
169 | */ |
170 | typedef gboolean (*GOptionParseFunc) (GOptionContext *context, |
171 | GOptionGroup *group, |
172 | gpointer data, |
173 | GError **error); |
174 | |
175 | /** |
176 | * GOptionErrorFunc: |
177 | * @context: The active #GOptionContext |
178 | * @group: The group to which the function belongs |
179 | * @data: User data added to the #GOptionGroup containing the option when it |
180 | * was created with g_option_group_new() |
181 | * @error: The #GError containing details about the parse error |
182 | * |
183 | * The type of function to be used as callback when a parse error occurs. |
184 | */ |
185 | typedef void (*GOptionErrorFunc) (GOptionContext *context, |
186 | GOptionGroup *group, |
187 | gpointer data, |
188 | GError **error); |
189 | |
190 | /** |
191 | * G_OPTION_ERROR: |
192 | * |
193 | * Error domain for option parsing. Errors in this domain will |
194 | * be from the #GOptionError enumeration. See #GError for information on |
195 | * error domains. |
196 | */ |
197 | #define G_OPTION_ERROR (g_option_error_quark ()) |
198 | |
199 | /** |
200 | * GOptionError: |
201 | * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. |
202 | * This error will only be reported, if the parser hasn't been instructed |
203 | * to ignore unknown options, see g_option_context_set_ignore_unknown_options(). |
204 | * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. |
205 | * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. |
206 | * |
207 | * Error codes returned by option parsing. |
208 | */ |
209 | typedef enum |
210 | { |
211 | G_OPTION_ERROR_UNKNOWN_OPTION, |
212 | G_OPTION_ERROR_BAD_VALUE, |
213 | G_OPTION_ERROR_FAILED |
214 | } GOptionError; |
215 | |
216 | GLIB_AVAILABLE_IN_ALL |
217 | GQuark g_option_error_quark (void); |
218 | |
219 | /** |
220 | * GOptionEntry: |
221 | * @long_name: The long name of an option can be used to specify it |
222 | * in a commandline as `--long_name`. Every option must have a |
223 | * long name. To resolve conflicts if multiple option groups contain |
224 | * the same long name, it is also possible to specify the option as |
225 | * `--groupname-long_name`. |
226 | * @short_name: If an option has a short name, it can be specified |
227 | * `-short_name` in a commandline. @short_name must be a printable |
228 | * ASCII character different from '-', or zero if the option has no |
229 | * short name. |
230 | * @flags: Flags from #GOptionFlags |
231 | * @arg: The type of the option, as a #GOptionArg |
232 | * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data |
233 | * must point to a #GOptionArgFunc callback function, which will be |
234 | * called to handle the extra argument. Otherwise, @arg_data is a |
235 | * pointer to a location to store the value, the required type of |
236 | * the location depends on the @arg type: |
237 | * - %G_OPTION_ARG_NONE: %gboolean |
238 | * - %G_OPTION_ARG_STRING: %gchar* |
239 | * - %G_OPTION_ARG_INT: %gint |
240 | * - %G_OPTION_ARG_FILENAME: %gchar* |
241 | * - %G_OPTION_ARG_STRING_ARRAY: %gchar** |
242 | * - %G_OPTION_ARG_FILENAME_ARRAY: %gchar** |
243 | * - %G_OPTION_ARG_DOUBLE: %gdouble |
244 | * If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME, |
245 | * the location will contain a newly allocated string if the option |
246 | * was given. That string needs to be freed by the callee using g_free(). |
247 | * Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or |
248 | * %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). |
249 | * @description: the description for the option in `--help` |
250 | * output. The @description is translated using the @translate_func |
251 | * of the group, see g_option_group_set_translation_domain(). |
252 | * @arg_description: The placeholder to use for the extra argument parsed |
253 | * by the option in `--help` output. The @arg_description is translated |
254 | * using the @translate_func of the group, see |
255 | * g_option_group_set_translation_domain(). |
256 | * |
257 | * A GOptionEntry struct defines a single option. To have an effect, they |
258 | * must be added to a #GOptionGroup with g_option_context_add_main_entries() |
259 | * or g_option_group_add_entries(). |
260 | */ |
261 | struct _GOptionEntry |
262 | { |
263 | const gchar *long_name; |
264 | gchar short_name; |
265 | gint flags; |
266 | |
267 | GOptionArg arg; |
268 | gpointer arg_data; |
269 | |
270 | const gchar *description; |
271 | const gchar *arg_description; |
272 | }; |
273 | |
274 | /** |
275 | * G_OPTION_REMAINING: |
276 | * |
277 | * If a long option in the main group has this name, it is not treated as a |
278 | * regular option. Instead it collects all non-option arguments which would |
279 | * otherwise be left in `argv`. The option must be of type |
280 | * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY |
281 | * or %G_OPTION_ARG_FILENAME_ARRAY. |
282 | * |
283 | * |
284 | * Using %G_OPTION_REMAINING instead of simply scanning `argv` |
285 | * for leftover arguments has the advantage that GOption takes care of |
286 | * necessary encoding conversions for strings or filenames. |
287 | * |
288 | * Since: 2.6 |
289 | */ |
290 | #define G_OPTION_REMAINING "" |
291 | |
292 | /** |
293 | * G_OPTION_ENTRY_NULL: |
294 | * |
295 | * A #GOptionEntry array requires a %NULL terminator, this macro can |
296 | * be used as terminator instead of an explicit `{ 0 }` but it cannot |
297 | * be assigned to a variable. |
298 | * |
299 | * |[ |
300 | * GOptionEntry option[] = { G_OPTION_ENTRY_NULL }; |
301 | * ]| |
302 | * |
303 | * Since: 2.70 |
304 | */ |
305 | #define G_OPTION_ENTRY_NULL \ |
306 | GLIB_AVAILABLE_MACRO_IN_2_70 \ |
307 | { NULL, 0, 0, 0, NULL, NULL, NULL } |
308 | |
309 | |
310 | GLIB_AVAILABLE_IN_ALL |
311 | GOptionContext *g_option_context_new (const gchar *parameter_string); |
312 | GLIB_AVAILABLE_IN_ALL |
313 | void g_option_context_set_summary (GOptionContext *context, |
314 | const gchar *summary); |
315 | GLIB_AVAILABLE_IN_ALL |
316 | const gchar * g_option_context_get_summary (GOptionContext *context); |
317 | GLIB_AVAILABLE_IN_ALL |
318 | void g_option_context_set_description (GOptionContext *context, |
319 | const gchar *description); |
320 | GLIB_AVAILABLE_IN_ALL |
321 | const gchar * g_option_context_get_description (GOptionContext *context); |
322 | GLIB_AVAILABLE_IN_ALL |
323 | void g_option_context_free (GOptionContext *context); |
324 | GLIB_AVAILABLE_IN_ALL |
325 | void g_option_context_set_help_enabled (GOptionContext *context, |
326 | gboolean help_enabled); |
327 | GLIB_AVAILABLE_IN_ALL |
328 | gboolean g_option_context_get_help_enabled (GOptionContext *context); |
329 | GLIB_AVAILABLE_IN_ALL |
330 | void g_option_context_set_ignore_unknown_options (GOptionContext *context, |
331 | gboolean ignore_unknown); |
332 | GLIB_AVAILABLE_IN_ALL |
333 | gboolean g_option_context_get_ignore_unknown_options (GOptionContext *context); |
334 | |
335 | GLIB_AVAILABLE_IN_2_44 |
336 | void g_option_context_set_strict_posix (GOptionContext *context, |
337 | gboolean strict_posix); |
338 | GLIB_AVAILABLE_IN_2_44 |
339 | gboolean g_option_context_get_strict_posix (GOptionContext *context); |
340 | |
341 | GLIB_AVAILABLE_IN_ALL |
342 | void g_option_context_add_main_entries (GOptionContext *context, |
343 | const GOptionEntry *entries, |
344 | const gchar *translation_domain); |
345 | GLIB_AVAILABLE_IN_ALL |
346 | gboolean g_option_context_parse (GOptionContext *context, |
347 | gint *argc, |
348 | gchar ***argv, |
349 | GError **error); |
350 | GLIB_AVAILABLE_IN_2_40 |
351 | gboolean g_option_context_parse_strv (GOptionContext *context, |
352 | gchar ***arguments, |
353 | GError **error); |
354 | GLIB_AVAILABLE_IN_ALL |
355 | void g_option_context_set_translate_func (GOptionContext *context, |
356 | GTranslateFunc func, |
357 | gpointer data, |
358 | GDestroyNotify destroy_notify); |
359 | GLIB_AVAILABLE_IN_ALL |
360 | void g_option_context_set_translation_domain (GOptionContext *context, |
361 | const gchar *domain); |
362 | |
363 | GLIB_AVAILABLE_IN_ALL |
364 | void g_option_context_add_group (GOptionContext *context, |
365 | GOptionGroup *group); |
366 | GLIB_AVAILABLE_IN_ALL |
367 | void g_option_context_set_main_group (GOptionContext *context, |
368 | GOptionGroup *group); |
369 | GLIB_AVAILABLE_IN_ALL |
370 | GOptionGroup *g_option_context_get_main_group (GOptionContext *context); |
371 | GLIB_AVAILABLE_IN_ALL |
372 | gchar *g_option_context_get_help (GOptionContext *context, |
373 | gboolean main_help, |
374 | GOptionGroup *group); |
375 | |
376 | GLIB_AVAILABLE_IN_ALL |
377 | GOptionGroup *g_option_group_new (const gchar *name, |
378 | const gchar *description, |
379 | const gchar *help_description, |
380 | gpointer user_data, |
381 | GDestroyNotify destroy); |
382 | GLIB_AVAILABLE_IN_ALL |
383 | void g_option_group_set_parse_hooks (GOptionGroup *group, |
384 | GOptionParseFunc pre_parse_func, |
385 | GOptionParseFunc post_parse_func); |
386 | GLIB_AVAILABLE_IN_ALL |
387 | void g_option_group_set_error_hook (GOptionGroup *group, |
388 | GOptionErrorFunc error_func); |
389 | GLIB_DEPRECATED_IN_2_44 |
390 | void g_option_group_free (GOptionGroup *group); |
391 | GLIB_AVAILABLE_IN_2_44 |
392 | GOptionGroup *g_option_group_ref (GOptionGroup *group); |
393 | GLIB_AVAILABLE_IN_2_44 |
394 | void g_option_group_unref (GOptionGroup *group); |
395 | GLIB_AVAILABLE_IN_ALL |
396 | void g_option_group_add_entries (GOptionGroup *group, |
397 | const GOptionEntry *entries); |
398 | GLIB_AVAILABLE_IN_ALL |
399 | void g_option_group_set_translate_func (GOptionGroup *group, |
400 | GTranslateFunc func, |
401 | gpointer data, |
402 | GDestroyNotify destroy_notify); |
403 | GLIB_AVAILABLE_IN_ALL |
404 | void g_option_group_set_translation_domain (GOptionGroup *group, |
405 | const gchar *domain); |
406 | |
407 | G_END_DECLS |
408 | |
409 | #endif /* __G_OPTION_H__ */ |
410 | |