luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-06-06 12:50:07 +02:00
Code Issues Packages Projects Releases Wiki Activity

goption: move docs from tmpl folder to inline comments

Browse Source
This commit is contained in:
Stefan Kost 2009-04-14 11:23:25 +03:00
parent 0f48f804b6
commit 2026c232b3
5 changed files with 330 additions and 604 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
option.sgml

603
docs/reference/glib/tmpl/option.sgml
View File

@ -1,603 +0,0 @@
<!-- ##### SECTION Title ##### -->
Commandline option parser
<!-- ##### SECTION Short_Description ##### -->
parses commandline options
<!-- ##### SECTION Long_Description ##### -->
<para>
The GOption commandline parser is intended to be a simpler replacement for the
popt library. It supports short and long commandline options, as shown in the
following example:
</para>
<para>
<literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
</para>
<para>
The example demonstrates a number of features of the GOption commandline parser
<itemizedlist>
<listitem><para>
Options can be single letters, prefixed by a single dash. Multiple
short options can be grouped behind a single dash.
</para></listitem>
<listitem><para>
Long options are prefixed by two consecutive dashes.
</para></listitem>
<listitem><para>
Options can have an extra argument, which can be a number, a string or a
filename. For long options, the extra argument can be appended with an
equals sign after the option name.
</para></listitem>
<listitem><para>
Non-option arguments are returned to the application as rest arguments.
</para></listitem>
<listitem><para>
An argument consisting solely of two dashes turns off further parsing,
any remaining arguments (even those starting with a dash) are returned
to the application as rest arguments.
</para></listitem>
</itemizedlist>
</para>
<para>
Another important feature of GOption is that it can automatically generate
nicely formatted help output. Unless it is explicitly turned off with
g_option_context_set_help_enabled(), GOption will recognize the
<option>--help</option>, <option>-?</option>, <option>--help-all</option>
and <option>--help-</option><replaceable>groupname</replaceable> options
(where <replaceable>groupname</replaceable> is the name of a #GOptionGroup)
and write a text similar to the one shown in the following example to stdout.
</para>
<informalexample><screen>
Usage:
testtreemodel [OPTION...] - test tree model performance
Help Options:
-?, --help Show help options
--help-all Show all help options
--help-gtk Show GTK+ Options
Application Options:
-r, --repeats=N Average over N repetitions
-m, --max-size=M Test up to 2^M items
--display=DISPLAY X display to use
-v, --verbose Be verbose
-b, --beep Beep when done
--rand Randomize the data
</screen></informalexample>
<para>
GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
incorporate options from multiple sources. The intended use for this is
to let applications collect option groups from the libraries it uses,
add them to their #GOptionContext, and parse all options by a single call
to g_option_context_parse(). See gtk_get_option_group() for an example.
</para>
<para>
If an option is declared to be of type string or filename, GOption takes
care of converting it to the right encoding; strings are returned in UTF-8,
filenames are returned in the GLib filename encoding. Note that this only
works if setlocale() has been called before g_option_context_parse().
</para>
<para>
Here is a complete example of setting up GOption to parse the example
commandline above and produce the example help output.
</para>
<informalexample><programlisting>
static gint repeats = 2;
static gint max_size = 8;
static gboolean verbose = FALSE;
static gboolean beep = FALSE;
static gboolean rand = FALSE;
static GOptionEntry entries[] =
{
{ "repeats", 'r', 0, G_OPTION_ARG_INT, &amp;repeats, "Average over N repetitions", "N" },
{ "max-size", 'm', 0, G_OPTION_ARG_INT, &amp;max_size, "Test up to 2^M items", "M" },
{ "verbose", 'v', 0, G_OPTION_ARG_NONE, &amp;verbose, "Be verbose", NULL },
{ "beep", 'b', 0, G_OPTION_ARG_NONE, &amp;beep, "Beep when done", NULL },
{ "rand", 0, 0, G_OPTION_ARG_NONE, &amp;rand, "Randomize the data", NULL },
{ NULL }
};
int
main (int argc, char *argv[])
{
GError *error = NULL;
GOptionContext *context;
context = g_option_context_new ("- test tree model performance");
g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
g_option_context_add_group (context, gtk_get_option_group (TRUE));
if (!g_option_context_parse (context, &amp;argc, &amp;argv, &amp;error))
{
g_print ("option parsing failed: %s\n", error->message);
exit (1);
}
/* ... */
}
</programlisting></informalexample>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### ENUM GOptionError ##### -->
<para>
Error codes returned by option parsing.
</para>
@G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser.
This error will only be reported, if the parser hasn't been instructed
to ignore unknown options, see g_option_context_set_ignore_unknown_options().
@G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
@G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
<!-- ##### MACRO G_OPTION_ERROR ##### -->
<para>
Error domain for option parsing. Errors in this domain will
be from the #GOptionError enumeration. See #GError for information on
error domains.
</para>
<!-- ##### USER_FUNCTION GOptionArgFunc ##### -->
<para>
The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
options.
</para>
@option_name: The name of the option being parsed. This will be either a
single dash followed by a single letter (for a short name) or two dashes
followed by a long option name.
@value: The value to be parsed.
@data: User data added to the #GOptionGroup containing the option when it
was created with g_option_group_new()
@error: A return location for errors. The error code %G_OPTION_ERROR_FAILED
is intended to be used for errors in #GOptionArgFunc callbacks.
@Returns: %TRUE if the option was successfully parsed, %FALSE if an error
occurred, in which case @error should be set with g_set_error()
<!-- ##### STRUCT GOptionContext ##### -->
<para>
A <structname>GOptionContext</structname> struct defines which options
are accepted by the commandline option parser. The struct has only private
fields and should not be directly accessed.
</para>
<!-- ##### FUNCTION g_option_context_new ##### -->
<para>
</para>
@parameter_string:
@Returns:
<!-- ##### FUNCTION g_option_context_set_summary ##### -->
<para>
</para>
@context:
@summary:
<!-- ##### FUNCTION g_option_context_get_summary ##### -->
<para>
</para>
@context:
@Returns:
<!-- ##### FUNCTION g_option_context_set_description ##### -->
<para>
</para>
@context:
@description:
<!-- ##### FUNCTION g_option_context_get_description ##### -->
<para>
</para>
@context:
@Returns:
<!-- ##### USER_FUNCTION GTranslateFunc ##### -->
<para>
The type of functions which are used to translate user-visible
strings, for <option>--help</option> output.
</para>
@str: the untranslated string
@data: user data specified when installing the function, e.g.
in g_option_group_set_translate_func()
@Returns: a translation of the string for the current locale.
The returned string is owned by GLib and must not be freed.
<!-- ##### FUNCTION g_option_context_set_translate_func ##### -->
<para>
</para>
@context:
@func:
@data:
@destroy_notify:
<!-- ##### FUNCTION g_option_context_set_translation_domain ##### -->
<para>
</para>
@context:
@domain:
<!-- ##### FUNCTION g_option_context_free ##### -->
<para>
</para>
@context:
<!-- ##### FUNCTION g_option_context_parse ##### -->
<para>
</para>
@context:
@argc:
@argv:
@error:
@Returns:
<!-- ##### FUNCTION g_option_context_set_help_enabled ##### -->
<para>
</para>
@context:
@help_enabled:
<!-- ##### FUNCTION g_option_context_get_help_enabled ##### -->
<para>
</para>
@context:
@Returns:
<!-- ##### FUNCTION g_option_context_set_ignore_unknown_options ##### -->
<para>
</para>
@context:
@ignore_unknown:
<!-- ##### FUNCTION g_option_context_get_ignore_unknown_options ##### -->
<para>
</para>
@context:
@Returns:
<!-- ##### FUNCTION g_option_context_get_help ##### -->
<para>
</para>
@context:
@main_help:
@group:
@Returns:
<!-- ##### ENUM GOptionArg ##### -->
<para>
The #GOptionArg enum values determine which type of extra argument the
options expect to find. If an option expects an extra argument, it
can be specified in several ways; with a short option:
<option>-x arg</option>, with a long option: <option>--name arg</option>
or combined in a single argument: <option>--name=arg</option>.
</para>
@G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
@G_OPTION_ARG_STRING: The option takes a string argument.
@G_OPTION_ARG_INT: The option takes an integer argument.
@G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
extra argument.
@G_OPTION_ARG_FILENAME: The option takes a filename as argument.
@G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
uses of the option are collected into an array of strings.
@G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument,
multiple uses of the option are collected into an array of strings.
@G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument
can be formatted either for the user's locale or for the "C" locale. Since 2.12
@G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT
but for larger numbers. The number can be in decimal base, or in hexadecimal
(when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>).
Since 2.12
<!-- ##### ENUM GOptionFlags ##### -->
<para>
Flags which modify individual options.
</para>
@G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
output.
@G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
<option>--help</option> output, even if it is defined in a group.
@G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag
indicates that the sense of the option is reversed.
@G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind,
this flag indicates that the callback does not take any argument
(like a %G_OPTION_ARG_NONE option). Since 2.8
@G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK
kind, this flag indicates that the argument should be passed to the
callback in the GLib filename encoding rather than UTF-8. Since 2.8
@G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK
kind, this flag indicates that the argument supply is optional. If no argument
is given then data of %GOptionParseFunc will be set to NULL. Since 2.8
@G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution
which prefixes long option names with <literal>groupname-</literal> if
there is a conflict. This option should only be used in situations where
aliasing is necessary to model some legacy commandline interface. It is
not safe to use this option, unless all option groups are under your
direct control. Since 2.8.
<!-- ##### MACRO G_OPTION_REMAINING ##### -->
<para>
If a long option in the main group has this name, it is not treated as a
regular option. Instead it collects all non-option arguments which would
otherwise be left in <literal>argv</literal>. The option must be of type
%G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
or %G_OPTION_ARG_FILENAME_ARRAY.
</para>
<para>
Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
for leftover arguments has the advantage that GOption takes care of
necessary encoding conversions for strings or filenames.
</para>
@Since: 2.6
<!-- ##### STRUCT GOptionEntry ##### -->
<para>
A <structname>GOptionEntry</structname> defines a single option.
To have an effect, they must be added to a #GOptionGroup with
g_option_context_add_main_entries() or g_option_group_add_entries().
</para>
@long_name: The long name of an option can be used to specify it
in a commandline as --<replaceable>long_name</replaceable>. Every
option must have a long name. To resolve conflicts if multiple
option groups contain the same long name, it is also possible to
specify the option as
--<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
@short_name: If an option has a short name, it can be specified
-<replaceable>short_name</replaceable> in a commandline. @short_name must be
a printable ASCII character different from '-', or zero if the option has no
short name.
@flags: Flags from #GOptionFlags.
@arg: The type of the option, as a #GOptionArg.
@arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must
point to a #GOptionArgFunc callback function, which will be called to handle
the extra argument. Otherwise, @arg_data is a pointer to a location to store
the value, the required type of the location depends on the @arg type:
<variablelist>
<varlistentry>
<term>%G_OPTION_ARG_NONE</term>
<listitem><para>%gboolean</para></listitem>
</varlistentry>
<varlistentry>
<term>%G_OPTION_ARG_STRING</term>
<listitem><para>%gchar*</para></listitem>
</varlistentry>
<varlistentry>
<term>%G_OPTION_ARG_INT</term>
<listitem><para>%gint</para></listitem>
</varlistentry>
<varlistentry>
<term>%G_OPTION_ARG_FILENAME</term>
<listitem><para>%gchar*</para></listitem>
</varlistentry>
<varlistentry>
<term>%G_OPTION_ARG_STRING_ARRAY</term>
<listitem><para>%gchar**</para></listitem>
</varlistentry>
<varlistentry>
<term>%G_OPTION_ARG_FILENAME_ARRAY</term>
<listitem><para>%gchar**</para></listitem>
</varlistentry>
<varlistentry>
<term>%G_OPTION_ARG_DOUBLE</term>
<listitem><para>%gdouble</para></listitem>
</varlistentry>
</variablelist>
@description: the description for the option in <option>--help</option>
output. The @description is translated using the @translate_func of the
group, see g_option_group_set_translation_domain().
@arg_description: The placeholder to use for the extra argument parsed
by the option in <option>--help</option>
output. The @arg_description is translated using the @translate_func of the
group, see g_option_group_set_translation_domain().
<!-- ##### FUNCTION g_option_context_add_main_entries ##### -->
<para>
</para>
@context:
@entries:
@translation_domain:
<!-- ##### STRUCT GOptionGroup ##### -->
<para>
A <structname>GOptionGroup</structname> struct defines the options in a single
group. The struct has only private fields and should not be directly accessed.
</para>
<para>
All options in a group share the same translation function. Libaries which
need to parse commandline options are expected to provide a function for
getting a <structname>GOptionGroup</structname> holding their options, which
the application can then add to its #GOptionContext.
</para>
<!-- ##### FUNCTION g_option_context_add_group ##### -->
<para>
</para>
@context:
@group:
<!-- ##### FUNCTION g_option_context_set_main_group ##### -->
<para>
</para>
@context:
@group:
<!-- ##### FUNCTION g_option_context_get_main_group ##### -->
<para>
</para>
@context:
@Returns:
<!-- ##### FUNCTION g_option_group_new ##### -->
<para>
</para>
@name:
@description:
@help_description:
@user_data:
@destroy:
@Returns:
<!-- ##### FUNCTION g_option_group_free ##### -->
<para>
</para>
@group:
<!-- ##### FUNCTION g_option_group_add_entries ##### -->
<para>
</para>
@group:
@entries:
<!-- ##### USER_FUNCTION GOptionParseFunc ##### -->
<para>
The type of function that can be called before and after parsing.
</para>
@context: The active #GOptionContext
@group: The group to which the function belongs
@data: User data added to the #GOptionGroup containing the option when it
was created with g_option_group_new()
@error: A return location for error details
@Returns: %TRUE if the function completed successfully, %FALSE if an error
occurred, in which case @error should be set with g_set_error()
<!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
<para>
</para>
@group:
@pre_parse_func:
@post_parse_func:
<!-- ##### USER_FUNCTION GOptionErrorFunc ##### -->
<para>
The type of function to be used as callback when a parse error occurs.
</para>
@context: The active #GOptionContext
@group: The group to which the function belongs
@data: User data added to the #GOptionGroup containing the option when it
was created with g_option_group_new()
@error: The #GError containing details about the parse error
<!-- ##### FUNCTION g_option_group_set_error_hook ##### -->
<para>
</para>
@group:
@error_func:
<!-- ##### FUNCTION g_option_group_set_translate_func ##### -->
<para>
</para>
@group:
@func:
@data:
@destroy_notify:
<!-- ##### FUNCTION g_option_group_set_translation_domain ##### -->
<para>
</para>
@group:
@domain:

113
glib/goption.c
View File

@ -18,6 +18,119 @@
* Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA. * Boston, MA 02111-1307, USA.
*/ */
/**
* SECTION:option
* @Short_description: parses commandline options
* @Title: Commandline option parser
*
* The GOption commandline parser is intended to be a simpler replacement for the
* popt library. It supports short and long commandline options, as shown in the
* following example:
*
*
* <literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
*
*
* The example demonstrates a number of features of the GOption commandline parser
* <itemizedlist>
* Options can be single letters, prefixed by a single dash. Multiple
* short options can be grouped behind a single dash.
* </para></listitem>
* Long options are prefixed by two consecutive dashes.
* </para></listitem>
* Options can have an extra argument, which can be a number, a string or a
* filename. For long options, the extra argument can be appended with an
* equals sign after the option name.
* </para></listitem>
* Non-option arguments are returned to the application as rest arguments.
* </para></listitem>
* An argument consisting solely of two dashes turns off further parsing,
* any remaining arguments (even those starting with a dash) are returned
* to the application as rest arguments.
* </para></listitem>
* </itemizedlist>
*
*
* Another important feature of GOption is that it can automatically generate
* nicely formatted help output. Unless it is explicitly turned off with
* g_option_context_set_help_enabled(), GOption will recognize the
* <option>--help</option>, <option>-?</option>, <option>--help-all</option>
* and <option>--help-</option><replaceable>groupname</replaceable> options
* (where <replaceable>groupname</replaceable> is the name of a #GOptionGroup)
* and write a text similar to the one shown in the following example to stdout.
*
*
* <informalexample><screen>
* Usage:
* testtreemodel [OPTION...] - test tree model performance
*
* Help Options:
* -?, --help Show help options
* --help-all Show all help options
* --help-gtk Show GTK+ Options
*
* Application Options:
* -r, --repeats=N Average over N repetitions
* -m, --max-size=M Test up to 2^M items
* --display=DISPLAY X display to use
* -v, --verbose Be verbose
* -b, --beep Beep when done
* --rand Randomize the data
* </screen></informalexample>
*
* GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
* incorporate options from multiple sources. The intended use for this is
* to let applications collect option groups from the libraries it uses,
* add them to their #GOptionContext, and parse all options by a single call
* to g_option_context_parse(). See gtk_get_option_group() for an example.
*
*
* If an option is declared to be of type string or filename, GOption takes
* care of converting it to the right encoding; strings are returned in UTF-8,
* filenames are returned in the GLib filename encoding. Note that this only
* works if setlocale() has been called before g_option_context_parse().
*
*
* Here is a complete example of setting up GOption to parse the example
* commandline above and produce the example help output.
*
* <informalexample><programlisting>
* static gint repeats = 2;
* static gint max_size = 8;
* static gboolean verbose = FALSE;
* static gboolean beep = FALSE;
* static gboolean rand = FALSE;
*
* static GOptionEntry entries[] =
* {
* { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
* { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
* { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
* { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
* { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Randomize the data", NULL },
* { NULL }
* };
*
* int
* main (int argc, char *argv[])
* {
* GError *error = NULL;
* GOptionContext *context;
*
* context = g_option_context_new ("- test tree model performance");
* g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
* g_option_context_add_group (context, gtk_get_option_group (TRUE));
* if (!g_option_context_parse (context, &argc, &argv, &error))
* {
* g_print ("option parsing failed: %s\n", error->message);
* exit (1);
* }
*
* // ...
*
* }
* </programlisting></informalexample>
*/
#include "config.h" #include "config.h"

204
glib/goption.h
View File

@ -30,10 +30,55 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/**
* GOptionContext:
*
* A <structname>GOptionContext</structname> struct defines which options
* are accepted by the commandline option parser. The struct has only private
* fields and should not be directly accessed.
*/
typedef struct _GOptionContext GOptionContext; typedef struct _GOptionContext GOptionContext;
/**
* GOptionGroup:
*
* A <structname>GOptionGroup</structname> struct defines the options in a single
* group. The struct has only private fields and should not be directly accessed.
*
* All options in a group share the same translation function. Libaries which
* need to parse commandline options are expected to provide a function for
* getting a <structname>GOptionGroup</structname> holding their options, which
* the application can then add to its #GOptionContext.
*/
typedef struct _GOptionGroup GOptionGroup; typedef struct _GOptionGroup GOptionGroup;
typedef struct _GOptionEntry GOptionEntry; typedef struct _GOptionEntry GOptionEntry;
/**
* GOptionFlags:
* @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
* output.
* @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
* <option>--help</option> output, even if it is defined in a group.
* @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag
* indicates that the sense of the option is reversed.
* @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind,
* this flag indicates that the callback does not take any argument
* (like a %G_OPTION_ARG_NONE option). Since 2.8
* @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK
* kind, this flag indicates that the argument should be passed to the
* callback in the GLib filename encoding rather than UTF-8. Since 2.8
* @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK
* kind, this flag indicates that the argument supply is optional. If no argument
* is given then data of %GOptionParseFunc will be set to NULL. Since 2.8
* @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution
* which prefixes long option names with <literal>groupname-</literal> if
* there is a conflict. This option should only be used in situations where
* aliasing is necessary to model some legacy commandline interface. It is
* not safe to use this option, unless all option groups are under your
* direct control. Since 2.8.
*
* Flags which modify individual options.
*/
typedef enum typedef enum
{ {
G_OPTION_FLAG_HIDDEN = 1 << 0, G_OPTION_FLAG_HIDDEN = 1 << 0,
@ -45,6 +90,31 @@ typedef enum
G_OPTION_FLAG_NOALIAS = 1 << 6 G_OPTION_FLAG_NOALIAS = 1 << 6
} GOptionFlags; } GOptionFlags;
/**
* GOptionArg:
* @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
* @G_OPTION_ARG_STRING: The option takes a string argument.
* @G_OPTION_ARG_INT: The option takes an integer argument.
* @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
* extra argument.
* @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
* @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
* uses of the option are collected into an array of strings.
* @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument,
* multiple uses of the option are collected into an array of strings.
* @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument
* can be formatted either for the user's locale or for the "C" locale. Since 2.12
* @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT
* but for larger numbers. The number can be in decimal base, or in hexadecimal
* (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>).
* Since 2.12
*
* The #GOptionArg enum values determine which type of extra argument the
* options expect to find. If an option expects an extra argument, it
* can be specified in several ways; with a short option:
* <option>-x arg</option>, with a long option: <option>--name arg</option>
* or combined in a single argument: <option>--name=arg</option>.
*/
typedef enum typedef enum
{ {
G_OPTION_ARG_NONE, G_OPTION_ARG_NONE,
@ -58,23 +128,80 @@ typedef enum
G_OPTION_ARG_INT64 G_OPTION_ARG_INT64
} GOptionArg; } GOptionArg;
/**
* GOptionArgFunc:
* @option_name: The name of the option being parsed. This will be either a
* single dash followed by a single letter (for a short name) or two dashes
* followed by a long option name.
* @value: The value to be parsed.
* @data: User data added to the #GOptionGroup containing the option when it
* was created with g_option_group_new()
* @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED
* is intended to be used for errors in #GOptionArgFunc callbacks.
*
* The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
* options.
*
* Returns: %TRUE if the option was successfully parsed, %FALSE if an error
* occurred, in which case @error should be set with g_set_error()
*/
typedef gboolean (*GOptionArgFunc) (const gchar *option_name, typedef gboolean (*GOptionArgFunc) (const gchar *option_name,
const gchar *value, const gchar *value,
gpointer data, gpointer data,
GError **error); GError **error);
/**
* GOptionParseFunc:
* @context: The active #GOptionContext
* @group: The group to which the function belongs
* @data: User data added to the #GOptionGroup containing the option when it
* was created with g_option_group_new()
* @error: A return location for error details
*
* The type of function that can be called before and after parsing.
*
* Returns: %TRUE if the function completed successfully, %FALSE if an error
* occurred, in which case @error should be set with g_set_error()
*/
typedef gboolean (*GOptionParseFunc) (GOptionContext *context, typedef gboolean (*GOptionParseFunc) (GOptionContext *context,
GOptionGroup *group, GOptionGroup *group,
gpointer data, gpointer data,
GError **error); GError **error);
/**
* GOptionErrorFunc:
* @context: The active #GOptionContext
* @group: The group to which the function belongs
* @data: User data added to the #GOptionGroup containing the option when it
* was created with g_option_group_new()
* @error: The #GError containing details about the parse error
*
* The type of function to be used as callback when a parse error occurs.
*/
typedef void (*GOptionErrorFunc) (GOptionContext *context, typedef void (*GOptionErrorFunc) (GOptionContext *context,
GOptionGroup *group, GOptionGroup *group,
gpointer data, gpointer data,
GError **error); GError **error);
/**
* G_OPTION_ERROR:
*
* Error domain for option parsing. Errors in this domain will
* be from the #GOptionError enumeration. See #GError for information on
* error domains.
*/
#define G_OPTION_ERROR (g_option_error_quark ()) #define G_OPTION_ERROR (g_option_error_quark ())
/**
* GOptionError:
* @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser.
* This error will only be reported, if the parser hasn't been instructed
* to ignore unknown options, see g_option_context_set_ignore_unknown_options().
* @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
* @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
*
* Error codes returned by option parsing.
*/
typedef enum typedef enum
{ {
G_OPTION_ERROR_UNKNOWN_OPTION, G_OPTION_ERROR_UNKNOWN_OPTION,
@ -84,7 +211,66 @@ typedef enum
GQuark g_option_error_quark (void); GQuark g_option_error_quark (void);
/**
* GOptionEntry:
* @long_name: The long name of an option can be used to specify it
* in a commandline as --<replaceable>long_name</replaceable>. Every
* option must have a long name. To resolve conflicts if multiple
* option groups contain the same long name, it is also possible to
* specify the option as
* --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
* @short_name: If an option has a short name, it can be specified
* -<replaceable>short_name</replaceable> in a commandline. @short_name must be
* a printable ASCII character different from '-', or zero if the option has no
* short name.
* @flags: Flags from #GOptionFlags.
* @arg: The type of the option, as a #GOptionArg.
* @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must
* point to a #GOptionArgFunc callback function, which will be called to handle
* the extra argument. Otherwise, @arg_data is a pointer to a location to store
* the value, the required type of the location depends on the @arg type:
* <variablelist>
* <varlistentry>
* <term>%G_OPTION_ARG_NONE</term>
* <listitem><para>%gboolean</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>%G_OPTION_ARG_STRING</term>
* <listitem><para>%gchar*</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>%G_OPTION_ARG_INT</term>
* <listitem><para>%gint</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>%G_OPTION_ARG_FILENAME</term>
* <listitem><para>%gchar*</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>%G_OPTION_ARG_STRING_ARRAY</term>
* <listitem><para>%gchar**</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>%G_OPTION_ARG_FILENAME_ARRAY</term>
* <listitem><para>%gchar**</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>%G_OPTION_ARG_DOUBLE</term>
* <listitem><para>%gdouble</para></listitem>
* </varlistentry>
* </variablelist>
* @description: the description for the option in <option>--help</option>
* output. The @description is translated using the @translate_func of the
* group, see g_option_group_set_translation_domain().
* @arg_description: The placeholder to use for the extra argument parsed
* by the option in <option>--help</option>
* output. The @arg_description is translated using the @translate_func of the
* group, see g_option_group_set_translation_domain().
*
* A <structname>GOptionEntry</structname> defines a single option.
* To have an effect, they must be added to a #GOptionGroup with
* g_option_context_add_main_entries() or g_option_group_add_entries().
*/
struct _GOptionEntry struct _GOptionEntry
{ {
const gchar *long_name; const gchar *long_name;
@ -98,6 +284,22 @@ struct _GOptionEntry
const gchar *arg_description; const gchar *arg_description;
}; };
/**
* G_OPTION_REMAINING:
*
* If a long option in the main group has this name, it is not treated as a
* regular option. Instead it collects all non-option arguments which would
* otherwise be left in <literal>argv</literal>. The option must be of type
* %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
* or %G_OPTION_ARG_FILENAME_ARRAY.
*
*
* Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
* for leftover arguments has the advantage that GOption takes care of
* necessary encoding conversions for strings or filenames.
*
* Since: 2.6
*/
#define G_OPTION_REMAINING "" #define G_OPTION_REMAINING ""
GOptionContext *g_option_context_new (const gchar *parameter_string); GOptionContext *g_option_context_new (const gchar *parameter_string);

13
glib/gtypes.h
View File

@ -92,6 +92,19 @@ typedef void (*GHFunc) (gpointer key,
gpointer value, gpointer value,
gpointer user_data); gpointer user_data);
typedef void (*GFreeFunc) (gpointer data); typedef void (*GFreeFunc) (gpointer data);
/**
* GTranslateFunc:
* @str: the untranslated string
* @data: user data specified when installing the function, e.g.
* in g_option_group_set_translate_func()
*
* The type of functions which are used to translate user-visible
* strings, for <option>--help</option> output.
*
* Returns: a translation of the string for the current locale.
* The returned string is owned by GLib and must not be freed.
*/
typedef const gchar * (*GTranslateFunc) (const gchar *str, typedef const gchar * (*GTranslateFunc) (const gchar *str,
gpointer data); gpointer data);