+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,
+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,
+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,
+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,
+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,
+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.
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>
-<!-- ##### SECTION See_Also ##### -->
<para>
-
+<literal>test -x 1 --long-y foo --flag --long-z=baz -uvw -- file1 file2</literal>
</para>
-<!-- ##### ENUM GOptionError ##### -->
<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>
-@G_OPTION_ERROR_UNKNOWN_OPTION:
-@G_OPTION_ERROR_BAD_VALUE:
-@G_OPTION_ERROR_FAILED:
+<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>
-<!-- ##### MACRO G_OPTION_ERROR ##### -->
<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 ##### -->
+<para>
+</para>
-<!-- ##### ENUM GOptionFlags ##### -->
+<!-- ##### ENUM GOptionError ##### -->
<para>
-
+Error codes returned by option parsing.
</para>
-@G_OPTION_FLAG_HIDDEN:
-@G_OPTION_FLAG_IN_MAIN:
+@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.
-<!-- ##### ENUM GOptionArg ##### -->
+<!-- ##### 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>
-@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>
@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>
+@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>
-@long_name:
-@short_name:
-@flags:
-@arg:
-@arg_data:
-@description:
-@arg_description:
+@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>
<!-- ##### 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>
<!-- ##### 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 ##### -->
<!-- ##### 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 ##### -->
<!-- ##### 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 ##### -->
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)
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_return_if_fail (context != NULL);
+/**
+ * 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);
g_list_free (context->groups);
g_free (context);
}
-void
-g_option_context_set_help_enabled (GOptionContext *context,
- gboolean help_enabled)
+
+/**
+ * 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)
{
g_return_if_fail (context != NULL);
context->help_enabled = help_enabled;
}
-gboolean
-g_option_context_get_help_enabled (GOptionContext *context)
+/**
+ * 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)
{
g_return_val_if_fail (context != NULL, FALSE);
-
+
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)
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)
{
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)
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)
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)
{
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,
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,
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,
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)
{
}
+/**
+ * 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)
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,
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)
}
+/**
+ * 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);
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)
projects / platform / upstream / glib.git / commitdiff