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>test -x 1 --long-y foo --flag --long-z=baz -uvw -- 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   An argument consisting solely of two dashes turns off further parsing, any remaining
  35   arguments are returned to the application as rest arguments.
  36 </para></listitem>
  37 </itemizedlist>
  38 </para>
  39
  40 <para>
  41 Another important feature of GOption is that it can automatically generate nicely
  42 formatted help output. Unless it is explicitly turned off with
  43 g_option_context_set_help_enabled(), GOption will recognize the
  44 <option>--help</option>, <option>-?</option>, <option>--help-all</option>
  45 and <option>--help-</option><replaceable>groupname</replaceable> options (where
  46 <replaceable>groupname</replaceable> is the name of a #GOptionGroup) and
  47 write a text similar to the one shown in the following example to stdout.
  48 </para>
  49
  50 <informalexample><screen>
  51 Usage:
  52   testtreemodel [OPTION...]
  53
  54 Help Options:
  55   --help                   Show help options
  56   --help-all               Show all help options
  57   --help-gtk               Show GTK+ Options
  58
  59 Application Options:
  60   -r, --repeats=N          Average over N repetitions
  61   -m, --max-size=M         Test up to 2^M items
  62   --display=DISPLAY        X display to use
  63 </screen></informalexample>
  64
  65 <para>
  66 GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
  67 incorporate options from multiple sources. The intended use for this is
  68 to let applications collect option groups from the libraries it uses,
  69 add them to their #GOptionContext, and parse all options by a single call
  70 to g_option_context_parse(). See gtk_get_option_group() for an example.
  71 </para>
  72
  73 <para>
  74 If an option is declared to be of type string or filename, GOption takes
  75 care of converting it to the right encoding; strings are returned in UTF-8,
  76 filenames are returned in the GLib filename encoding.
  77 </para>
  78
  79 <!-- ##### SECTION See_Also ##### -->
  80 <para>
  81
  82 </para>
  83
  84 <!-- ##### ENUM GOptionError ##### -->
  85 <para>
  86 Error codes returned by option parsing.
  87 </para>
  88
  89 @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser.
  90   This error will only be reported, if the parser hasn't been instructed
  91   to ignore unknown options, see g_option_context_set_ignore_unknown_options().
  92 @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
  93 @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
  94
  95 <!-- ##### MACRO G_OPTION_ERROR ##### -->
  96 <para>
  97 Error domain for option parsing. Errors in this domain will
  98 be from the #GOptionError enumeration. See #GError for information on
  99 error domains.
 100 </para>
 101
 102
 103
 104 <!-- ##### USER_FUNCTION GOptionArgFunc ##### -->
 105 <para>
 106 The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
 107 options.
 108 </para>
 109
 110 @option_name: The name of the option being parsed. This will be either a
 111   single dash followed by a single letter (for a short name) or two dashes
 112   followed by a long option name.
 113 @value: The value to be parsed.
 114 @data: User data added to the #GOptionGroup containing the option when it
 115   was created with g_option_group_new()
 116 @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED
 117   is intended to be used for errors in #GOptionArgFunc callbacks.
 118 @Returns: %TRUE if the option was successfully parsed, %FALSE if an error
 119   occurred
 120
 121
 122 <!-- ##### STRUCT GOptionContext ##### -->
 123 <para>
 124 A <structname>GOptionContext</structname> struct defines which options
 125 are accepted by the commandline option parser. The struct has only private
 126 fields and should not be directly accessed.
 127 </para>
 128
 129
 130 <!-- ##### FUNCTION g_option_context_new ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @parameter_string:
 136 @Returns:
 137
 138
 139 <!-- ##### FUNCTION g_option_context_free ##### -->
 140 <para>
 141
 142 </para>
 143
 144 @context:
 145
 146
 147 <!-- ##### FUNCTION g_option_context_parse ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @context:
 153 @argc:
 154 @argv:
 155 @error:
 156 @Returns:
 157
 158
 159 <!-- ##### FUNCTION g_option_context_set_help_enabled ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @context:
 165 @help_enabled:
 166
 167
 168 <!-- ##### FUNCTION g_option_context_get_help_enabled ##### -->
 169 <para>
 170
 171 </para>
 172
 173 @context:
 174 @Returns:
 175
 176
 177 <!-- ##### FUNCTION g_option_context_set_ignore_unknown_options ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @context:
 183 @ignore_unknown:
 184
 185
 186 <!-- ##### FUNCTION g_option_context_get_ignore_unknown_options ##### -->
 187 <para>
 188
 189 </para>
 190
 191 @context:
 192 @Returns:
 193
 194
 195 <!-- ##### ENUM GOptionArg ##### -->
 196 <para>
 197 The #GOptionArg enum values determine which type of extra argument the
 198 options expect to find. If an option expects an extra argument, it
 199 can be specified in several ways; with a short option:
 200 <option>-x arg</option>, with a long option: <option>--name arg</option>
 201 or combined in a single argument: <option>--name=arg</option>.
 202 </para>
 203
 204 @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
 205 @G_OPTION_ARG_STRING: The option takes a string argument.
 206 @G_OPTION_ARG_INT: The option takes an integer argument.
 207 @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
 208   extra argument.
 209 @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
 210 @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
 211   uses of the option are collected into an array of strings.
 212 @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument,
 213   multiple uses of the option are collected into an array of strings.
 214
 215 <!-- ##### ENUM GOptionFlags ##### -->
 216 <para>
 217 Flags which modify individual options.
 218 </para>
 219
 220 @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
 221    output.
 222 @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
 223    <option>--help</option> output, even if it is defined in a group.
 224
 225 <!-- ##### STRUCT GOptionEntry ##### -->
 226 <para>
 227 A <structname>GOptionEntry</structname> defines a single option.
 228 To have an effect, they must be added to a #GOptionGroup with
 229 g_option_context_add_main_entries() or g_option_group_add_entries().
 230 </para>
 231
 232 @long_name: The long name of an option can be used to specify it
 233   in a commandline as --<replaceable>long_name</replaceable>. Every
 234   option must have a long name.
 235 @short_name: If an option has a short name, it can be specified
 236   -<replaceable>short_name</replaceable> in a commandline.
 237 @flags: Flags from #GOptionEntryFlags.
 238 @arg: The type of the option, as a #GOptionArg.
 239 @arg_data:  If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must
 240  point to a #GOptionArgFunc callback function, which will be called to handle
 241  the extra argument. Otherwise, @arg_data is a pointer to a location to store
 242  the value, the required type of the location depends on the @arg type:
 243   <variablelist>
 244     <varlistentry>
 245       <term>%G_OPTION_ARG_NONE</term>
 246       <listitem><para>%gboolean</para></listitem>
 247     </varlistentry>
 248     <varlistentry>
 249       <term>%G_OPTION_ARG_STRING</term>
 250       <listitem><para>%gchar*</para></listitem>
 251     </varlistentry>
 252     <varlistentry>
 253       <term>%G_OPTION_ARG_INT</term>
 254       <listitem><para>%gint</para></listitem>
 255     </varlistentry>
 256     <varlistentry>
 257       <term>%G_OPTION_ARG_FILENAME</term>
 258       <listitem><para>%gchar*</para></listitem>
 259     </varlistentry>
 260     <varlistentry>
 261       <term>%G_OPTION_ARG_STRING_ARRAY</term>
 262       <listitem><para>%gchar**</para></listitem>
 263     </varlistentry>
 264     <varlistentry>
 265       <term>%G_OPTION_ARG_FILENAME_ARRAY</term>
 266       <listitem><para>%gchar**</para></listitem>
 267     </varlistentry>
 268   </variablelist>
 269 @description: the description for the option in <option>--help</option>
 270   output. The @description is translated using the @translate_func of the
 271   group, see g_option_group_set_translation_domain().
 272 @arg_description: The placeholder to use for the extra argument parsed
 273   by the option in <option>--help</option>
 274   output. The @arg_description is translated using the @translate_func of the
 275   group, see g_option_group_set_translation_domain().
 276
 277 <!-- ##### FUNCTION g_option_context_add_main_entries ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @context:
 283 @entries:
 284 @translation_domain:
 285
 286
 287 <!-- ##### STRUCT GOptionGroup ##### -->
 288 <para>
 289 A <structname>GOptionGroup</structname> struct defines the options in a single
 290 group. The struct has only private fields and should not be directly accessed.
 291 </para>
 292 <para>
 293 All options in a group share the same translation function. Libaries which
 294 need to parse commandline options are expected to provide a function for
 295 getting a <structname>GOptionGroup</structname> holding their options, which
 296 the application can then add to its #GOptionContext.
 297 </para>
 298
 299
 300 <!-- ##### FUNCTION g_option_context_add_group ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @context:
 306 @group:
 307
 308
 309 <!-- ##### FUNCTION g_option_context_set_main_group ##### -->
 310 <para>
 311
 312 </para>
 313
 314 @context:
 315 @group:
 316
 317
 318 <!-- ##### FUNCTION g_option_context_get_main_group ##### -->
 319 <para>
 320
 321 </para>
 322
 323 @context:
 324 @Returns:
 325
 326
 327 <!-- ##### FUNCTION g_option_group_new ##### -->
 328 <para>
 329
 330 </para>
 331
 332 @name:
 333 @description:
 334 @help_description:
 335 @user_data:
 336 @destroy:
 337 @Returns:
 338
 339
 340 <!-- ##### FUNCTION g_option_group_free ##### -->
 341 <para>
 342
 343 </para>
 344
 345 @group:
 346
 347
 348 <!-- ##### FUNCTION g_option_group_add_entries ##### -->
 349 <para>
 350
 351 </para>
 352
 353 @group:
 354 @entries:
 355
 356
 357 <!-- ##### USER_FUNCTION GOptionParseFunc ##### -->
 358 <para>
 359 The type of function that can be called before and after parsing.
 360 </para>
 361
 362 @context The active #GOptionContext
 363
 364 @context:
 365 @group: The group to which the function belongs
 366 @data: User data added to the #GOptionGroup containing the option when it
 367   was created with g_option_group_new()
 368 @error: A return location for error details
 369 @Returns: %TRUE if the function completed successfully, %FALSE if an error
 370   occurred
 371
 372
 373 <!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
 374 <para>
 375
 376 </para>
 377
 378 @group:
 379 @pre_parse_func:
 380 @post_parse_func:
 381
 382
 383 <!-- ##### USER_FUNCTION GOptionErrorFunc ##### -->
 384 <para>
 385 The type of function to be used as callback when a parse error
 386 occurs.
 387 </para>
 388
 389 @context The active #GOptionContext
 390
 391 @context:
 392 @group: The group to which the function belongs
 393 @data: User data added to the #GOptionGroup containing the option when it
 394   was created with g_option_group_new()
 395 @error: The #GError containing details about the parse error
 396
 397
 398 <!-- ##### FUNCTION g_option_group_set_error_hook ##### -->
 399 <para>
 400
 401 </para>
 402
 403 @group:
 404 @error_func:
 405
 406
 407 <!-- ##### USER_FUNCTION GTranslateFunc ##### -->
 408 <para>
 409 The type of functions which are used to translate user-visible
 410 strings, for <option>--help</option> output.
 411 </para>
 412
 413 @str: the untranslated string
 414 @data: user data specified when installing the function, e.g.
 415   in g_option_group_set_translate_func()
 416 @Returns: a translation of the string for the current locale.
 417   The returned string is owned by GLib and must not be freed.
 418
 419
 420 <!-- ##### FUNCTION g_option_group_set_translate_func ##### -->
 421 <para>
 422
 423 </para>
 424
 425 @group:
 426 @func:
 427 @data:
 428 @destroy_notify:
 429
 430
 431 <!-- ##### FUNCTION g_option_group_set_translation_domain ##### -->
 432 <para>
 433
 434 </para>
 435
 436 @group:
 437 @domain:
 438
 439