docs/reference/glib/tmpl/option.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Commandline option parser
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 parses commandline options
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The GOption commandline parser is intended to be a simpler replacement for the
  10 popt library. It supports short and long commandline options, as shown in the
  11 following example:
  12 </para>
  13
  14 <para>
  15 <literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
  16 </para>
  17
  18 <para>
  19 The example demonstrates a number of features of the GOption commandline parser
  20 <itemizedlist>
  21 <listitem><para>
  22   Options can be single letters, prefixed by a single dash. Multiple
  23   short options can be grouped behind a single dash.
  24 </para></listitem>
  25 <listitem><para>
  26   Long options are prefixed by two consecutive dashes.
  27 </para></listitem>
  28 <listitem><para>
  29   Options can have an extra argument, which can be a number, a string or a filename.
  30   For long options, the extra argument can be appended with an equals sign after the
  31   option name.
  32 </para></listitem>
  33 <listitem><para>
  34   Non-option arguments are returned to the application as rest arguments.
  35 </para></listitem>
  36 <listitem><para>
  37   An argument consisting solely of two dashes turns off further parsing, any remaining
  38   arguments (even those starting with a dash) are returned to the application as rest
  39   arguments.
  40 </para></listitem>
  41 </itemizedlist>
  42 </para>
  43
  44 <para>
  45 Another important feature of GOption is that it can automatically generate nicely
  46 formatted help output. Unless it is explicitly turned off with
  47 g_option_context_set_help_enabled(), GOption will recognize the
  48 <option>--help</option>, <option>-?</option>, <option>--help-all</option>
  49 and <option>--help-</option><replaceable>groupname</replaceable> options
  50 (where <replaceable>groupname</replaceable> is the name of a #GOptionGroup)
  51 and write a text similar to the one shown in the following example to stdout.
  52 </para>
  53
  54 <informalexample><screen>
  55 Usage:
  56   testtreemodel [OPTION...] - test tree model performance
  57
  58 Help Options:
  59   -?, --help               Show help options
  60   --help-all               Show all help options
  61   --help-gtk               Show GTK+ Options
  62
  63 Application Options:
  64   -r, --repeats=N          Average over N repetitions
  65   -m, --max-size=M         Test up to 2^M items
  66   --display=DISPLAY        X display to use
  67   -v, --verbose            Be verbose
  68   -b, --beep               Beep when done
  69   --rand                   Randomize the data
  70 </screen></informalexample>
  71
  72 <para>
  73 GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
  74 incorporate options from multiple sources. The intended use for this is
  75 to let applications collect option groups from the libraries it uses,
  76 add them to their #GOptionContext, and parse all options by a single call
  77 to g_option_context_parse(). See gtk_get_option_group() for an example.
  78 </para>
  79
  80 <para>
  81 If an option is declared to be of type string or filename, GOption takes
  82 care of converting it to the right encoding; strings are returned in UTF-8,
  83 filenames are returned in the GLib filename encoding.
  84 </para>
  85
  86 <para>
  87 Here is a complete example of setting up GOption to parse the example
  88 commandline above and produce the example help output.
  89 </para>
  90 <informalexample><programlisting>
  91 static gint repeats = 2;
  92 static gint max_size = 8;
  93 static gboolean verbose = FALSE;
  94 static gboolean beep = FALSE;
  95 static gboolean rand = FALSE;
  96
  97 static GOptionEntry entries[] =
  98 {
  99   { "repeats", 'r', 0, G_OPTION_ARG_INT, &amp;repeats, "Average over N repetitions", "N" },
 100   { "max-size", 'm', 0, G_OPTION_ARG_INT, &amp;max_size, "Test up to 2^M items", "M" },
 101   { "verbose", 'v', 0, G_OPTION_ARG_NONE, &amp;verbose, "Be verbose", NULL },
 102   { "beep", 'b', 0, G_OPTION_ARG_NONE, &amp;beep, "Beep when done", NULL },
 103   { "rand", 0, 0, G_OPTION_ARG_NONE, &amp;rand, "Randomize the data", NULL },
 104   { NULL }
 105 };
 106
 107 int
 108 main (int argc, char *argv[])
 109 {
 110   GError *error = NULL;
 111
 112   context = g_option_context_new ("- test tree model performance");
 113   g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
 114   g_option_context_add_group (context, gtk_get_option_group (TRUE));
 115   g_option_context_parse (context, &amp;argc, &amp;argv, &amp;error);
 116
 117   /* ... */
 118
 119 }
 120 </programlisting></informalexample>
 121
 122 <!-- ##### SECTION See_Also ##### -->
 123 <para>
 124
 125 </para>
 126
 127 <!-- ##### SECTION Stability_Level ##### -->
 128
 129
 130 <!-- ##### ENUM GOptionError ##### -->
 131 <para>
 132 Error codes returned by option parsing.
 133 </para>
 134
 135 @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser.
 136   This error will only be reported, if the parser hasn't been instructed
 137   to ignore unknown options, see g_option_context_set_ignore_unknown_options().
 138 @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
 139 @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
 140
 141 <!-- ##### MACRO G_OPTION_ERROR ##### -->
 142 <para>
 143 Error domain for option parsing. Errors in this domain will
 144 be from the #GOptionError enumeration. See #GError for information on
 145 error domains.
 146 </para>
 147
 148
 149
 150 <!-- ##### USER_FUNCTION GOptionArgFunc ##### -->
 151 <para>
 152 The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
 153 options.
 154 </para>
 155
 156 @option_name: The name of the option being parsed. This will be either a
 157   single dash followed by a single letter (for a short name) or two dashes
 158   followed by a long option name.
 159 @value: The value to be parsed.
 160 @data: User data added to the #GOptionGroup containing the option when it
 161   was created with g_option_group_new()
 162 @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED
 163   is intended to be used for errors in #GOptionArgFunc callbacks.
 164 @Returns: %TRUE if the option was successfully parsed, %FALSE if an error
 165   occurred
 166
 167
 168 <!-- ##### STRUCT GOptionContext ##### -->
 169 <para>
 170 A <structname>GOptionContext</structname> struct defines which options
 171 are accepted by the commandline option parser. The struct has only private
 172 fields and should not be directly accessed.
 173 </para>
 174
 175
 176 <!-- ##### FUNCTION g_option_context_new ##### -->
 177 <para>
 178
 179 </para>
 180
 181 @parameter_string:
 182 @Returns:
 183
 184
 185 <!-- ##### FUNCTION g_option_context_free ##### -->
 186 <para>
 187
 188 </para>
 189
 190 @context:
 191
 192
 193 <!-- ##### FUNCTION g_option_context_parse ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @context:
 199 @argc:
 200 @argv:
 201 @error:
 202 @Returns:
 203
 204
 205 <!-- ##### FUNCTION g_option_context_set_help_enabled ##### -->
 206 <para>
 207
 208 </para>
 209
 210 @context:
 211 @help_enabled:
 212
 213
 214 <!-- ##### FUNCTION g_option_context_get_help_enabled ##### -->
 215 <para>
 216
 217 </para>
 218
 219 @context:
 220 @Returns:
 221
 222
 223 <!-- ##### FUNCTION g_option_context_set_ignore_unknown_options ##### -->
 224 <para>
 225
 226 </para>
 227
 228 @context:
 229 @ignore_unknown:
 230
 231
 232 <!-- ##### FUNCTION g_option_context_get_ignore_unknown_options ##### -->
 233 <para>
 234
 235 </para>
 236
 237 @context:
 238 @Returns:
 239
 240
 241 <!-- ##### ENUM GOptionArg ##### -->
 242 <para>
 243 The #GOptionArg enum values determine which type of extra argument the
 244 options expect to find. If an option expects an extra argument, it
 245 can be specified in several ways; with a short option:
 246 <option>-x arg</option>, with a long option: <option>--name arg</option>
 247 or combined in a single argument: <option>--name=arg</option>.
 248 </para>
 249
 250 @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
 251 @G_OPTION_ARG_STRING: The option takes a string argument.
 252 @G_OPTION_ARG_INT: The option takes an integer argument.
 253 @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
 254   extra argument.
 255 @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
 256 @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
 257   uses of the option are collected into an array of strings.
 258 @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument,
 259   multiple uses of the option are collected into an array of strings.
 260
 261 <!-- ##### ENUM GOptionFlags ##### -->
 262 <para>
 263 Flags which modify individual options.
 264 </para>
 265
 266 @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
 267    output.
 268 @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
 269    <option>--help</option> output, even if it is defined in a group.
 270 @G_OPTION_FLAG_REVERSE: For options of the G_OPTION_ARG_NONE kind, this flag
 271    indicates that the sense of the option is reversed.
 272
 273 <!-- ##### MACRO G_OPTION_REMAINING ##### -->
 274 <para>
 275 If a long option in the main group has this name, it is not treated as a
 276 regular option. Instead it collects all non-option arguments which would
 277 otherwise be left in <literal>argv</literal>. The option must be of type
 278 %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY.
 279 </para>
 280
 281 <para>
 282 Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
 283 for leftover arguments has the advantage that GOption takes care of
 284 necessary encoding conversions for strings or filenames.
 285 </para>
 286
 287 @Since: 2.6
 288
 289
 290 <!-- ##### STRUCT GOptionEntry ##### -->
 291 <para>
 292 A <structname>GOptionEntry</structname> defines a single option.
 293 To have an effect, they must be added to a #GOptionGroup with
 294 g_option_context_add_main_entries() or g_option_group_add_entries().
 295 </para>
 296
 297 @long_name: The long name of an option can be used to specify it
 298   in a commandline as --<replaceable>long_name</replaceable>. Every
 299   option must have a long name. To resolve conflicts if multiple
 300   option groups contain the same long name, it is also possible to
 301   specify the option as
 302   --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
 303 @short_name: If an option has a short name, it can be specified
 304   -<replaceable>short_name</replaceable> in a commandline.
 305 @flags: Flags from #GOptionFlags.
 306 @arg: The type of the option, as a #GOptionArg.
 307 @arg_data:  If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must
 308  point to a #GOptionArgFunc callback function, which will be called to handle
 309  the extra argument. Otherwise, @arg_data is a pointer to a location to store
 310  the value, the required type of the location depends on the @arg type:
 311   <variablelist>
 312     <varlistentry>
 313       <term>%G_OPTION_ARG_NONE</term>
 314       <listitem><para>%gboolean</para></listitem>
 315     </varlistentry>
 316     <varlistentry>
 317       <term>%G_OPTION_ARG_STRING</term>
 318       <listitem><para>%gchar*</para></listitem>
 319     </varlistentry>
 320     <varlistentry>
 321       <term>%G_OPTION_ARG_INT</term>
 322       <listitem><para>%gint</para></listitem>
 323     </varlistentry>
 324     <varlistentry>
 325       <term>%G_OPTION_ARG_FILENAME</term>
 326       <listitem><para>%gchar*</para></listitem>
 327     </varlistentry>
 328     <varlistentry>
 329       <term>%G_OPTION_ARG_STRING_ARRAY</term>
 330       <listitem><para>%gchar**</para></listitem>
 331     </varlistentry>
 332     <varlistentry>
 333       <term>%G_OPTION_ARG_FILENAME_ARRAY</term>
 334       <listitem><para>%gchar**</para></listitem>
 335     </varlistentry>
 336   </variablelist>
 337 @description: the description for the option in <option>--help</option>
 338   output. The @description is translated using the @translate_func of the
 339   group, see g_option_group_set_translation_domain().
 340 @arg_description: The placeholder to use for the extra argument parsed
 341   by the option in <option>--help</option>
 342   output. The @arg_description is translated using the @translate_func of the
 343   group, see g_option_group_set_translation_domain().
 344
 345 <!-- ##### FUNCTION g_option_context_add_main_entries ##### -->
 346 <para>
 347
 348 </para>
 349
 350 @context:
 351 @entries:
 352 @translation_domain:
 353
 354
 355 <!-- ##### STRUCT GOptionGroup ##### -->
 356 <para>
 357 A <structname>GOptionGroup</structname> struct defines the options in a single
 358 group. The struct has only private fields and should not be directly accessed.
 359 </para>
 360 <para>
 361 All options in a group share the same translation function. Libaries which
 362 need to parse commandline options are expected to provide a function for
 363 getting a <structname>GOptionGroup</structname> holding their options, which
 364 the application can then add to its #GOptionContext.
 365 </para>
 366
 367
 368 <!-- ##### FUNCTION g_option_context_add_group ##### -->
 369 <para>
 370
 371 </para>
 372
 373 @context:
 374 @group:
 375
 376
 377 <!-- ##### FUNCTION g_option_context_set_main_group ##### -->
 378 <para>
 379
 380 </para>
 381
 382 @context:
 383 @group:
 384
 385
 386 <!-- ##### FUNCTION g_option_context_get_main_group ##### -->
 387 <para>
 388
 389 </para>
 390
 391 @context:
 392 @Returns:
 393
 394
 395 <!-- ##### FUNCTION g_option_group_new ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @name:
 401 @description:
 402 @help_description:
 403 @user_data:
 404 @destroy:
 405 @Returns:
 406
 407
 408 <!-- ##### FUNCTION g_option_group_free ##### -->
 409 <para>
 410
 411 </para>
 412
 413 @group:
 414
 415
 416 <!-- ##### FUNCTION g_option_group_add_entries ##### -->
 417 <para>
 418
 419 </para>
 420
 421 @group:
 422 @entries:
 423
 424
 425 <!-- ##### USER_FUNCTION GOptionParseFunc ##### -->
 426 <para>
 427 The type of function that can be called before and after parsing.
 428 </para>
 429
 430 @context The active #GOptionContext
 431
 432 @context:
 433 @group: The group to which the function belongs
 434 @data: User data added to the #GOptionGroup containing the option when it
 435   was created with g_option_group_new()
 436 @error: A return location for error details
 437 @Returns: %TRUE if the function completed successfully, %FALSE if an error
 438   occurred
 439
 440
 441 <!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @group:
 447 @pre_parse_func:
 448 @post_parse_func:
 449
 450
 451 <!-- ##### USER_FUNCTION GOptionErrorFunc ##### -->
 452 <para>
 453 The type of function to be used as callback when a parse error
 454 occurs.
 455 </para>
 456
 457 @context The active #GOptionContext
 458
 459 @context:
 460 @group: The group to which the function belongs
 461 @data: User data added to the #GOptionGroup containing the option when it
 462   was created with g_option_group_new()
 463 @error: The #GError containing details about the parse error
 464
 465
 466 <!-- ##### FUNCTION g_option_group_set_error_hook ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @group:
 472 @error_func:
 473
 474
 475 <!-- ##### USER_FUNCTION GTranslateFunc ##### -->
 476 <para>
 477 The type of functions which are used to translate user-visible
 478 strings, for <option>--help</option> output.
 479 </para>
 480
 481 @str: the untranslated string
 482 @data: user data specified when installing the function, e.g.
 483   in g_option_group_set_translate_func()
 484 @Returns: a translation of the string for the current locale.
 485   The returned string is owned by GLib and must not be freed.
 486
 487
 488 <!-- ##### FUNCTION g_option_group_set_translate_func ##### -->
 489 <para>
 490
 491 </para>
 492
 493 @group:
 494 @func:
 495 @data:
 496 @destroy_notify:
 497
 498
 499 <!-- ##### FUNCTION g_option_group_set_translation_domain ##### -->
 500 <para>
 501
 502 </para>
 503
 504 @group:
 505 @domain:
 506
 507