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

Doc additions.

Browse Source
This commit is contained in:
Matthias Clasen 2004-10-30 05:06:15 +00:00
parent b190dce984
commit eb0b4db5ff
8 changed files with 96 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
ChangeLog
View File

@ -1,5 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows.

2
ChangeLog.pre-2-10
View File

@ -1,5 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows.

2
ChangeLog.pre-2-12
View File

@ -1,5 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows.

2
ChangeLog.pre-2-6
View File

@ -1,5 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows.

2
ChangeLog.pre-2-8
View File

@ -1,5 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/goption.c: Doc additions.
* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
Windows.

2
docs/reference/ChangeLog
View File

@ -1,5 +1,7 @@
2004-10-29 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/option.sgml: Add an example.
* glib/glib-sections.txt: Add G_OPTION_REMAINING
* glib/tmpl/option.sgml: Add docs.

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

@ -12,7 +12,7 @@ following example:
</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>
@ -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
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.
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>
@ -64,6 +64,9 @@ 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>
@ -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.
</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 ##### -->
<para>
</para>
<!-- ##### ENUM GOptionError ##### -->
<para>
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.
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_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
@ -106,36 +143,6 @@ error domains.
</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 ##### -->
<para>
@ -228,6 +235,36 @@ fields and should not be directly accessed.
@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 ##### -->
<para>
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().
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.
-<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
@ -382,7 +419,9 @@ the application can then add to its #GOptionContext.
The type of function that can be called before and after parsing.
</para>
@context The active #GOptionContext
@context The active #GOptionContext
@context:
@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()
@ -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
occurred
<!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
<para>
@ -406,7 +446,9 @@ The type of function to be used as callback when a parse error
occurs.
</para>
@context The active #GOptionContext
@context The active #GOptionContext
@context:
@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()

3
glib/goption.c
View File

@ -221,7 +221,8 @@ g_option_context_get_help_enabled (GOptionContext *context)
* 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).
* 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
**/