luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-02 15:46:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Document GOption

Browse Source
This commit is contained in:
Matthias Clasen 2004-10-29 18:43:34 +00:00
parent 4d424f4f30
commit a0e217e94a
8 changed files with 475 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ChangeLog
View File

@ -1,3 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Add documentation.
2004-10-28 Matthias Clasen <mclasen@redhat.com>
* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

4
ChangeLog.pre-2-10
View File

@ -1,3 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Add documentation.
2004-10-28 Matthias Clasen <mclasen@redhat.com>
* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

4
ChangeLog.pre-2-12
View File

@ -1,3 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Add documentation.
2004-10-28 Matthias Clasen <mclasen@redhat.com>
* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

4
ChangeLog.pre-2-6
View File

@ -1,3 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Add documentation.
2004-10-28 Matthias Clasen <mclasen@redhat.com>
* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

4
ChangeLog.pre-2-8
View File

@ -1,3 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Add documentation.
2004-10-28 Matthias Clasen <mclasen@redhat.com>
* glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN,

4
docs/reference/ChangeLog
View File

@ -1,3 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/option.sgml: Add docs.
2004-10-28 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/keyfile.sgml: Add some introductory notes.

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

@ -2,11 +2,78 @@
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>test -x 1 --long-y foo --flag --long-z=baz -uvw -- 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>
An argument consisting solely of two dashes turns off further parsing, any remaining
arguments 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...]
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
</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.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,56 +83,47 @@ Commandline option parser
<!-- ##### ENUM GOptionError ##### -->
<para>
Error codes returned by option parsing.
</para>
@G_OPTION_ERROR_UNKNOWN_OPTION:
@G_OPTION_ERROR_BAD_VALUE:
@G_OPTION_ERROR_FAILED:
@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>
<!-- ##### ENUM GOptionFlags ##### -->
<para>
</para>
@G_OPTION_FLAG_HIDDEN:
@G_OPTION_FLAG_IN_MAIN:
<!-- ##### ENUM GOptionArg ##### -->
<para>
</para>
@G_OPTION_ARG_NONE:
@G_OPTION_ARG_STRING:
@G_OPTION_ARG_INT:
@G_OPTION_ARG_CALLBACK:
@G_OPTION_ARG_FILENAME:
@G_OPTION_ARG_STRING_ARRAY:
@G_OPTION_ARG_FILENAME_ARRAY:
<!-- ##### USER_FUNCTION GOptionArgFunc ##### -->
<para>
The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
options.
</para>
@option_name:
@value:
@data:
@error:
@Returns:
@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
<!-- ##### 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>
@ -134,18 +192,87 @@ Commandline option parser
@Returns:
<!-- ##### STRUCT GOptionEntry ##### -->
<!-- ##### 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>
@long_name:
@short_name:
@flags:
@arg:
@arg_data:
@description:
@arg_description:
@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.
<!-- ##### 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.
<!-- ##### 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.
@short_name: If an option has a short name, it can be specified
-<replaceable>short_name</replaceable> in a commandline.
@flags: Flags from #GOptionEntryFlags.
@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>
</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>
@ -159,7 +286,14 @@ Commandline option parser
<!-- ##### 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>
@ -222,14 +356,18 @@ Commandline option parser
<!-- ##### USER_FUNCTION GOptionParseFunc ##### -->
<para>
The type of function that can be called before and after parsing.
</para>
@context The active #GOptionContext
@context:
@group:
@data:
@error:
@Returns:
@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
<!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
@ -244,13 +382,17 @@ Commandline option parser
<!-- ##### USER_FUNCTION GOptionErrorFunc ##### -->
<para>
The type of function to be used as callback when a parse error
occurs.
</para>
@context The active #GOptionContext
@context:
@group:
@data:
@error:
@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 ##### -->
@ -264,12 +406,15 @@ Commandline option parser
<!-- ##### USER_FUNCTION GTranslateFunc ##### -->
<para>
The type of functions which are used to translate user-visible
strings, for <option>--help</option> output.
</para>
@str:
@data:
@Returns:
@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_group_set_translate_func ##### -->

251
glib/goption.c
View File

@ -112,6 +112,18 @@ g_option_error_quark (void)
return q;
}
/**
* g_option_context_new:
* @parameter_string: the parameter string to be used in
* <option>--help</option> output.
*
* Creates a new option context.
*
* Returns: a newly created #GOptionContext, which must be
* freed with g_option_context_free() after use.
*
* Since: 2.6
*/
GOptionContext *
g_option_context_new (const gchar *parameter_string)
@ -122,13 +134,21 @@ g_option_context_new (const gchar *parameter_string)
context->parameter_string = g_strdup (parameter_string);
context->help_enabled = TRUE;
context->ignore_unknown = FALSE;
return context;
}
void
g_option_context_free (GOptionContext *context)
{
/**
* g_option_context_free:
* @context: a #GOptionContext
*
* Frees context and all the groups which have been
* added to it.
*
* Since: 2.6
*/
void g_option_context_free (GOptionContext *context) {
g_return_if_fail (context != NULL);
g_list_foreach (context->groups, (GFunc)g_option_group_free, NULL);
@ -145,8 +165,21 @@ g_option_context_free (GOptionContext *context)
g_free (context);
}
void
g_option_context_set_help_enabled (GOptionContext *context,
/**
* g_option_context_set_help_enabled:
* @context: a #GOptionContext
* @help_enabled: %TRUE to enable <option>--help</option>, %FALSE to disable it
*
* Enables or disables automatic generation of <option>--help</option>
* output. By default, g_option_context_parse() recognizes
* <option>--help</option>, <option>-?</option>, <option>--help-all</option>
* and <option>--help-</option><replaceable>groupname</replaceable> and creates
* suitable output to stdout.
*
* Since: 2.6
*/
void g_option_context_set_help_enabled (GOptionContext *context,
gboolean help_enabled)
{
@ -155,6 +188,17 @@ g_option_context_set_help_enabled (GOptionContext *context,
context->help_enabled = help_enabled;
}
/**
* g_option_context_get_help_enabled:
* @context: a #GOptionContext
*
* Returns whether automatic <option>--help</option> generation
* is turned on for @context. See g_option_context_set_help_enabled().
*
* Returns: %TRUE if automatic help generation is turned on.
*
* Since: 2.6
*/
gboolean
g_option_context_get_help_enabled (GOptionContext *context)
{
@ -163,6 +207,21 @@ g_option_context_get_help_enabled (GOptionContext *context)
return context->help_enabled;
}
/**
* g_option_context_set_ignore_unknown_options:
* @context: a #GOptionContext
* @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce
* an error when unknown options are met
*
* Sets whether to ignore unknown options or not. If an argument is
* ignored, it is left in the @argv array after parsing. By default,
* g_option_context_parse() treats unknown options as error.
*
* This setting does not affect non-option arguments (i.e. arguments
* which don't start with a dash).
*
* Since: 2.6
**/
void
g_option_context_set_ignore_unknown_options (GOptionContext *context,
gboolean ignore_unknown)
@ -172,6 +231,17 @@ g_option_context_set_ignore_unknown_options (GOptionContext *context,
context->ignore_unknown = ignore_unknown;
}
/**
* g_option_context_get_ignore_unknown_options:
* @context: a #GOptionContext
*
* Returns whether unknown options are ignored or not. See
* g_option_context_set_ignore_unknown_options().
*
* Returns: %TRUE if unknown options are ignored.
*
* Since: 2.6
**/
gboolean
g_option_context_get_ignore_unknown_options (GOptionContext *context)
{
@ -180,6 +250,19 @@ g_option_context_get_ignore_unknown_options (GOptionContext *context)
return context->ignore_unknown;
}
/**
* g_option_context_add_group:
* @context: a #GOptionContext
* @group: the group to add
*
* Adds a #GOptionGroup to the @context, so that parsing with @context
* will recognize the options in the group. Note that the group will
* be freed together with the context when g_option_context_free() is
* called, so you must not free the group yourself after adding it
* to a context.
*
* Since: 2.6
**/
void
g_option_context_add_group (GOptionContext *context,
GOptionGroup *group)
@ -193,6 +276,18 @@ g_option_context_add_group (GOptionContext *context,
context->groups = g_list_prepend (context->groups, group);
}
/**
* g_option_context_set_main_group:
* @context: a #GOptionContext
* @group: the group to set as main group
*
* Sets a #GOptionGroup as main group of the @context.
* This has the same effect as calling g_option_context_add_group(),
* the only difference is that the options in the main group are
* treated differently when generating <option>--help</option> output.
*
* Since: 2.6
**/
void
g_option_context_set_main_group (GOptionContext *context,
GOptionGroup *group)
@ -203,6 +298,18 @@ g_option_context_set_main_group (GOptionContext *context,
context->main_group = group;
}
/**
* g_option_context_get_main_group:
* @context: a #GOptionContext
*
* Returns a pointer to the main group of @context.
*
* Return value: the main group of @context, or %NULL if @context doesn't
* have a main group. Note that group belongs to @context and should
* not be modified or freed.
*
* Since: 2.6
**/
GOptionGroup *
g_option_context_get_main_group (GOptionContext *context)
{
@ -211,6 +318,19 @@ g_option_context_get_main_group (GOptionContext *context)
return context->main_group;
}
/**
* g_option_context_add_main_entries:
* @context: a #GOptionContext
* @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
* @translation_domain: a translation domain to use for translating
* the <option>--help</option> output for the options in @entries
* with gettext(), or %NULL
*
* A convenience function which creates a main group if it doesn't
* exist, adds the @entries to it and sets the translation domain.
*
* Since: 2.6
**/
void
g_option_context_add_main_entries (GOptionContext *context,
const GOptionEntry *entries,
@ -814,6 +934,28 @@ free_pending_nulls (GOptionContext *context,
context->pending_nulls = NULL;
}
/**
* g_option_context_parse:
* @context: a #GOptionContext
* @argc: a pointer to the number of command line arguments.
* @argv: a pointer to the array of command line arguments.
* @error: a return location for errors
*
* Parses the command line arguments, recognizing options
* which have been added to @context. A side-effect of
* calling this function is that g_set_prgname() will be
* called.
*
* If the parsing is successful, any parsed arguments are
* removed from the array and @argc and @argv are updated
* accordingly. In case of an error, @argc and @argv are
* left unmodified.
*
* Return value: %TRUE if the parsing was successful,
* %FALSE if an error occurred
*
* Since: 2.6
**/
gboolean
g_option_context_parse (GOptionContext *context,
gint *argc,
@ -1095,7 +1237,27 @@ g_option_context_parse (GOptionContext *context,
return FALSE;
}
/**
* g_option_group_new:
* @name: the name for the option group, this is used to provide
* help for the options in this group with <option>--help-</option>@name
* @description: a description for this group to be shown in
* <option>--help</option>. This string is translated using the translation
* domain or translation function of the group
* @help_description: a description for the <option>--help-</option>@name option.
* This string is translated using the translation domain or translation function
* of the group
* @user_data: user data that will be passed to the pre- and post-parse hooks,
* the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL
* @destroy: a function that will be called to free @user_data, or %NULL
*
* Creates a new #GOptionGroup.
*
* Return value: a newly created option group. It should be added
* to a #GOptionContext or freed with g_option_group_free().
*
* Since: 2.6
**/
GOptionGroup *
g_option_group_new (const gchar *name,
const gchar *description,
@ -1116,6 +1278,15 @@ g_option_group_new (const gchar *name,
return group;
}
/**
* g_option_group_free:
* @group: a #GOptionGroup
*
* Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis>
* free groups which have been added to a #GOptionContext.
*
* Since: 2.6
**/
void
g_option_group_free (GOptionGroup *group)
{
@ -1137,6 +1308,15 @@ g_option_group_free (GOptionGroup *group)
}
/**
* g_option_group_add_entries:
* @group: a #GOptionGroup
* @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
*
* Adds the options specified in @entries to @group.
*
* Since: 2.6
**/
void
g_option_group_add_entries (GOptionGroup *group,
const GOptionEntry *entries)
@ -1154,6 +1334,22 @@ g_option_group_add_entries (GOptionGroup *group,
group->n_entries += n_entries;
}
/**
* g_option_group_set_parse_hooks:
* @group: a #GOptionGroup
* @pre_parse_func: a function to call before parsing, or %NULL
* @post_parse_func: a function to call after parsing, or %NULL
*
* Associates two functions with @group which will be called
* from g_option_context_parse() before the first option is parsed
* and after the last option has been parsed, respectively.
*
* Note that the user data to be passed to @pre_parse_func and
* @post_parse_func can be specified when constructing the group
* with g_option_group_new().
*
* Since: 2.6
**/
void
g_option_group_set_parse_hooks (GOptionGroup *group,
GOptionParseFunc pre_parse_func,
@ -1165,6 +1361,20 @@ g_option_group_set_parse_hooks (GOptionGroup *group,
group->post_parse_func = post_parse_func;
}
/**
* g_option_group_set_error_hook:
* @group: a #GOptionGroup
* @error_func: a function to call when an error occurs
*
* Associates a function with @group which will be called
* from g_option_context_parse() when an error occurs.
*
* Note that the user data to be passed to @pre_parse_func and
* @post_parse_func can be specified when constructing the group
* with g_option_group_new().
*
* Since: 2.6
**/
void
g_option_group_set_error_hook (GOptionGroup *group,
GOptionErrorFunc error_func)
@ -1175,11 +1385,28 @@ g_option_group_set_error_hook (GOptionGroup *group,
}
/**
* g_option_group_set_translate_func:
* @group: a #GOptionGroup
* @func: the #GTranslateFunc, or %NULL
* @data: user data to pass to @func, or %NULL
* @destroy_notify: a function which gets called to free @data, or %NULL
*
* Sets the function which is used to translate user-visible
* strings, for <option>--help</option> output. Different
* groups can use different #GTranslateFunc<!-- -->s. If @func
* is %NULL, strings are not translated.
*
* If you are using gettext(), you only need to set the translation
* domain, see g_option_group_set_translation_domain().
*
* Since: 2.6
**/
void
g_option_group_set_translate_func (GOptionGroup *group,
GTranslateFunc func,
gpointer data,
GDestroyNotify notify)
GDestroyNotify destroy_notify)
{
g_return_if_fail (group != NULL);
@ -1198,6 +1425,16 @@ dgettext_swapped (const gchar *msgid,
return dgettext (domainname, msgid);
}
/**
* g_option_group_set_translation_domain:
* @group: a #GOptionGroup
* @domain: the domain to use
*
* A convenience function to use gettext() for translating
* user-visible strings.
*
* Since: 2.6
**/
void
g_option_group_set_translation_domain (GOptionGroup *group,
const gchar *domain)