Commit eb0b4db5 authored by Matthias Clasen's avatar Matthias Clasen

Doc additions.

parent b190dce9
2004-10-29 Matthias Clasen <mclasen@redhat.com> 2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on * glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows. Windows.
......
2004-10-29 Matthias Clasen <mclasen@redhat.com> 2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on * glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows. Windows.
......
2004-10-29 Matthias Clasen <mclasen@redhat.com> 2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on * glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows. Windows.
......
2004-10-29 Matthias Clasen <mclasen@redhat.com> 2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on * glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows. Windows.
......
2004-10-29 Matthias Clasen <mclasen@redhat.com> 2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on * glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows. Windows.
......
2004-10-29 Matthias Clasen <mclasen@redhat.com> 2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/option.sgml: Add an example.
* glib/glib-sections.txt: Add G_OPTION_REMAINING * glib/glib-sections.txt: Add G_OPTION_REMAINING
* glib/tmpl/option.sgml: Add docs. * glib/tmpl/option.sgml: Add docs.
......
...@@ -12,7 +12,7 @@ following example: ...@@ -12,7 +12,7 @@ following example:
</para> </para>
<para> <para>
<literal>test -x 1 --long-y foo --flag --long-z=baz -uvw -- file1 file2</literal> <literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
</para> </para>
<para> <para>
...@@ -46,9 +46,9 @@ Another important feature of GOption is that it can automatically generate nicel ...@@ -46,9 +46,9 @@ Another important feature of GOption is that it can automatically generate nicel
formatted help output. Unless it is explicitly turned off with formatted help output. Unless it is explicitly turned off with
g_option_context_set_help_enabled(), GOption will recognize the g_option_context_set_help_enabled(), GOption will recognize the
<option>--help</option>, <option>-?</option>, <option>--help-all</option> <option>--help</option>, <option>-?</option>, <option>--help-all</option>
and <option>--help-</option><replaceable>groupname</replaceable> options (where and <option>--help-</option><replaceable>groupname</replaceable> options
<replaceable>groupname</replaceable> is the name of a #GOptionGroup) and (where <replaceable>groupname</replaceable> is the name of a #GOptionGroup)
write a text similar to the one shown in the following example to stdout. and write a text similar to the one shown in the following example to stdout.
</para> </para>
<informalexample><screen> <informalexample><screen>
...@@ -64,6 +64,9 @@ Application Options: ...@@ -64,6 +64,9 @@ Application Options:
-r, --repeats=N Average over N repetitions -r, --repeats=N Average over N repetitions
-m, --max-size=M Test up to 2^M items -m, --max-size=M Test up to 2^M items
--display=DISPLAY X display to use --display=DISPLAY X display to use
-v, --verbose Be verbose
-b, --beep Beep when done
--rand Randomize the data
</screen></informalexample> </screen></informalexample>
<para> <para>
...@@ -80,12 +83,47 @@ care of converting it to the right encoding; strings are returned in UTF-8, ...@@ -80,12 +83,47 @@ care of converting it to the right encoding; strings are returned in UTF-8,
filenames are returned in the GLib filename encoding. filenames are returned in the GLib filename encoding.
</para> </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;
context = g_option_context_new ("[OPTION...]");
g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
g_option_context_add_group (context, gtk_get_option_group (TRUE));
g_option_context_parse (context, &amp;argc, &amp;argv, &amp;error);
/* ... */
}
</programlisting></informalexample>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
<para> <para>
</para> </para>
<!-- ##### ENUM GOptionError ##### --> <!-- ##### ENUM GOptionError ##### -->
<para> <para>
Error codes returned by option parsing. Error codes returned by option parsing.
...@@ -94,10 +132,9 @@ Error codes returned by option parsing. ...@@ -94,10 +132,9 @@ Error codes returned by option parsing.
@G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. @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 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(). 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_BAD_VALUE: A value couldn't be parsed.
@G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
<!-- ##### MACRO G_OPTION_ERROR ##### --> <!-- ##### MACRO G_OPTION_ERROR ##### -->
<para> <para>
Error domain for option parsing. Errors in this domain will Error domain for option parsing. Errors in this domain will
...@@ -106,36 +143,6 @@ error domains. ...@@ -106,36 +143,6 @@ error domains.
</para> </para>
<!-- ##### 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.
<!-- ##### 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.
<!-- ##### USER_FUNCTION GOptionArgFunc ##### --> <!-- ##### USER_FUNCTION GOptionArgFunc ##### -->
<para> <para>
...@@ -228,6 +235,36 @@ fields and should not be directly accessed. ...@@ -228,6 +235,36 @@ fields and should not be directly accessed.
@Returns: @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.
<!-- ##### 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.
<!-- ##### MACRO G_OPTION_REMAINING ##### --> <!-- ##### MACRO G_OPTION_REMAINING ##### -->
<para> <para>
If a long option in the main group has this name, it is not treated as a If a long option in the main group has this name, it is not treated as a
...@@ -256,7 +293,7 @@ g_option_context_add_main_entries() or g_option_group_add_entries(). ...@@ -256,7 +293,7 @@ g_option_context_add_main_entries() or g_option_group_add_entries().
in a commandline as --<replaceable>long_name</replaceable>. Every in a commandline as --<replaceable>long_name</replaceable>. Every
option must have a long name. option must have a long name.
@short_name: If an option has a short name, it can be specified @short_name: If an option has a short name, it can be specified
-<replaceable>short_name</replaceable> in a commandline. -<replaceable>short_name</replaceable> in a commandline.
@flags: Flags from #GOptionEntryFlags. @flags: Flags from #GOptionEntryFlags.
@arg: The type of the option, as a #GOptionArg. @arg: The type of the option, as a #GOptionArg.
@arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must
...@@ -382,7 +419,9 @@ the application can then add to its #GOptionContext. ...@@ -382,7 +419,9 @@ the application can then add to its #GOptionContext.
The type of function that can be called before and after parsing. The type of function that can be called before and after parsing.
</para> </para>
@context The active #GOptionContext @context The active #GOptionContext
@context:
@group: The group to which the function belongs @group: The group to which the function belongs
@data: User data added to the #GOptionGroup containing the option when it @data: User data added to the #GOptionGroup containing the option when it
was created with g_option_group_new() was created with g_option_group_new()
...@@ -390,6 +429,7 @@ The type of function that can be called before and after parsing. ...@@ -390,6 +429,7 @@ The type of function that can be called before and after parsing.
@Returns: %TRUE if the function completed successfully, %FALSE if an error @Returns: %TRUE if the function completed successfully, %FALSE if an error
occurred occurred
<!-- ##### FUNCTION g_option_group_set_parse_hooks ##### --> <!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
<para> <para>
...@@ -406,7 +446,9 @@ The type of function to be used as callback when a parse error ...@@ -406,7 +446,9 @@ The type of function to be used as callback when a parse error
occurs. occurs.
</para> </para>
@context The active #GOptionContext @context The active #GOptionContext
@context:
@group: The group to which the function belongs @group: The group to which the function belongs
@data: User data added to the #GOptionGroup containing the option when it @data: User data added to the #GOptionGroup containing the option when it
was created with g_option_group_new() was created with g_option_group_new()
......
...@@ -221,7 +221,8 @@ g_option_context_get_help_enabled (GOptionContext *context) ...@@ -221,7 +221,8 @@ g_option_context_get_help_enabled (GOptionContext *context)
* g_option_context_parse() treats unknown options as error. * g_option_context_parse() treats unknown options as error.
* *
* This setting does not affect non-option arguments (i.e. arguments * This setting does not affect non-option arguments (i.e. arguments
* which don't start with a dash). * which don't start with a dash). But note that GOption cannot reliably
* determine whether a non-option belongs to a preceding unknown option.
* *
* Since: 2.6 * Since: 2.6
**/ **/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment