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