|
glibmm 2.82.0
|
An OptionContext defines and parses commandline options, using OptionGroups and option entries . More...
#include <glibmm/optioncontext.h>
Public Types | |
| using | SlotTranslate = sigc::slot< Glib::ustring(const Glib::ustring &)> |
| This function is used to translate user-visible strings, for –help output. | |
Public Member Functions | |
| OptionContext (const Glib::ustring ¶meter_string={}) | |
| Creates a new option context. | |
| OptionContext (GOptionContext *castitem, bool take_ownership=false) | |
| OptionContext (const OptionContext &other)=delete | |
| OptionContext & | operator= (const OptionContext &other)=delete |
| OptionContext (OptionContext &&other) noexcept | |
| OptionContext & | operator= (OptionContext &&other) noexcept |
| virtual | ~OptionContext () |
| void | set_help_enabled (bool help_enabled=true) |
Enables or disables automatic generation of --help output. | |
| bool | get_help_enabled () const |
Returns whether automatic --help generation is turned on for context. | |
| void | set_ignore_unknown_options (bool ignore_unknown=true) |
| Sets whether to ignore unknown options or not. | |
| bool | get_ignore_unknown_options () const |
| Returns whether unknown options are ignored or not. | |
| void | set_strict_posix (bool strict_posix=true) |
| Sets strict POSIX mode. | |
| bool | get_strict_posix () const |
| Returns whether strict POSIX code is enabled. | |
| bool | parse (int &argc, char **&argv) |
| Parses the command line arguments, recognizing options which have been added to context. | |
| bool | parse (char **&argv) |
| Parses the command line arguments. | |
| void | add_group (OptionGroup &group) |
| Adds an OptionGroup to the context, so that parsing with context will recognize the options in the group. | |
| void | set_main_group (OptionGroup &group) |
| Sets an OptionGroup as the main group of the context. | |
| Glib::ustring | get_help (bool main_help, const OptionGroup &group) const |
| Returns a formatted, translated help text for the given context. | |
| Glib::ustring | get_help (bool main_help=true) const |
| Returns a formatted, translated help text for the given context. | |
| GOptionContext * | gobj () |
| const GOptionContext * | gobj () const |
| void | set_summary (const Glib::ustring &summary) |
Adds a string to be displayed in --help output before the list of options. | |
| Glib::ustring | get_summary () const |
| Returns the summary. | |
| void | set_description (const Glib::ustring &description) |
Adds a string to be displayed in --help output after the list of options. | |
| Glib::ustring | get_description () const |
| Returns the description. | |
| void | set_translation_domain (const Glib::ustring & domain) |
| A convenience function to use gettext() for translating user-visible strings. | |
| void | set_translate_func (const SlotTranslate &slot) |
| Sets the function which is used to translate user-visible strings, for –help output. | |
Protected Attributes | |
| GOptionContext * | gobject_ |
| bool | has_ownership_ |
An OptionContext defines and parses commandline options, using OptionGroups and option entries .
It supports short and long commandline options, as shown in the following example:
testtreemodel -r 1 –max-size 20 –rand –display=:1.0 -vb – file1 file2
The example demonstrates a number of features of the GOption commandline parser:
The OptionContext groups options in OptionGroups, 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 OptionContext, and parse all options by a single call to parse(). See Gtk::Main::add_gtk_option_group(), for an example.
Add options by creating OptionEntry instances and appropriately-typed variables, and adding them to an OptionGroup with OptionGroup::add_entry() or OptionGroup::add_entry_filename(). The option group should then be added to the OptionContext with set_main_group() or add_group().
You might find it convenient to derive your own class from OptionGroup to contain these OptionEntry instances and member variables.
If an option is of type string (see OptionGroup::add_entry()) or filename (see OptionGroup::add_entry_filename()), OptionContext takes care of converting it to the right encoding. strings are returned in UTF-8 encoding and filenames are returned in the GLib filename encoding. Note that this only works if setlocale() has been called before OptionContext::parse().
OptionContext can automatically generate nicely formatted help output. Unless it is explicitly turned off with set_help_enabled(), this will recognize the –help, -?, –help-all and –help-groupname options (where groupname is the name of an OptionGroup) and write suitable text to stdout.
| using Glib::OptionContext::SlotTranslate = sigc::slot<Glib::ustring(const Glib::ustring&)> |
This function is used to translate user-visible strings, for –help output.
The function takes an untranslated string and returns a translated string
|
explicit |
Creates a new option context.
| parameter_string | A string which is displayed in the first line of –help output, after programname [OPTION...] |
|
explicit |
|
delete |
|
noexcept |
|
virtual |
| void Glib::OptionContext::add_group | ( | OptionGroup & | group | ) |
Adds an OptionGroup to the context, so that parsing with context will recognize the options in the group.
Note that the group will not be copied, so it should exist for as long as the context exists.
| group | The group to add. |
| Glib::ustring Glib::OptionContext::get_description | ( | ) | const |
| Glib::ustring Glib::OptionContext::get_help | ( | bool | main_help, |
| const OptionGroup & | group | ||
| ) | const |
Returns a formatted, translated help text for the given context.
To obtain the text produced by --help, call g_option_context_get_help (context, <tt>true</tt>, <tt>nullptr</tt>). To obtain the text produced by --help-all, call g_option_context_get_help (context, <tt>false</tt>, <tt>nullptr</tt>). To obtain the help text for an option group, call g_option_context_get_help (context, <tt>false</tt>, group).
| main_help | If true, only include the main group. |
| group | The OptionGroup to create help for, or nullptr. |
| Glib::ustring Glib::OptionContext::get_help | ( | bool | main_help = true | ) | const |
Returns a formatted, translated help text for the given context.
| main_help | If true, only include the main group. |
| bool Glib::OptionContext::get_help_enabled | ( | ) | const |
Returns whether automatic --help generation is turned on for context.
See g_option_context_set_help_enabled().
true if automatic help generation is turned on. | bool Glib::OptionContext::get_ignore_unknown_options | ( | ) | const |
Returns whether unknown options are ignored or not.
See g_option_context_set_ignore_unknown_options().
true if unknown options are ignored. | bool Glib::OptionContext::get_strict_posix | ( | ) | const |
Returns whether strict POSIX code is enabled.
See g_option_context_set_strict_posix() for more information.
true if strict POSIX is enabled, false otherwise. | Glib::ustring Glib::OptionContext::get_summary | ( | ) | const |
|
inline |
|
inline |
|
delete |
|
noexcept |
| bool Glib::OptionContext::parse | ( | char **& | argv | ) |
Parses the command line arguments.
This function is similar to parse(int& argc, char**& argv) except that it respects the normal memory rules when dealing with a strv instead of assuming that the passed-in array is the argv of the main function. In particular, strings that are removed from the arguments list will be freed using g_free().
On Windows, the strings are expected to be in UTF-8. This is in contrast to parse(int& argc, char**& argv) which expects them to be in the system codepage, which is how they are passed as argv to main(). See g_win32_get_command_line() or Gio::ApplicationCommandLine::get_arguments() for a solution.
This function is useful if you are trying to use OptionContext with Gio::Application.
| [in,out] | argv | A pointer to the command line arguments (which must be in UTF-8 on Windows). |
true if the parsing was successful, false if an error occurred. | Glib::OptionError | |
| Glib::ConvertError |
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. A '–' option is stripped from argv unless there are unparsed options before and after it, or some of the options after it start with '-'. In case of an error, argc and argv are left unmodified.
If automatic --help support is enabled (see g_option_context_set_help_enabled()), and the argv array contains one of the recognized help options, this function will produce help output to stdout and call exit (0).
Note that function depends on the [current locale][setlocale] for automatic character set conversion of string and filename arguments.
| argc | A pointer to the number of command line arguments. |
| argv | A pointer to the array of command line arguments. |
true if the parsing was successful, false if an error occurred.| Glib::OptionError | |
| Glib::ConvertError |
| void Glib::OptionContext::set_description | ( | const Glib::ustring & | description | ) |
Adds a string to be displayed in --help output after the list of options.
This text often includes a bug reporting address.
Note that the summary is translated (see g_option_context_set_translate_func()).
| description | A string to be shown in –help output after the list of options. |
Enables or disables automatic generation of --help output.
By default, g_option_context_parse() recognizes --help, -h, -?, --help-all and --help-groupname and creates suitable output to stdout.
| help_enabled | true to enable --help, false to disable it. |
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). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option.
| ignore_unknown | true to ignore unknown options, false to produce an error when unknown options are met. |
| void Glib::OptionContext::set_main_group | ( | OptionGroup & | group | ) |
Sets an OptionGroup as the main group of the context.
This has the same effect as calling add_group(), the only difference is that the options in the main group are treated differently when generating –help output. Note that the group will not be copied, so it should exist for as long as the context exists.
| group | The group to add. |
Sets strict POSIX mode.
By default, this mode is disabled.
In strict POSIX mode, the first non-argument parameter encountered (eg: filename) terminates argument processing. Remaining arguments are treated as non-options and are not attempted to be parsed.
If strict POSIX mode is disabled then parsing is done in the GNU way where option arguments can be freely mixed with non-options.
As an example, consider "ls foo -l". With GNU style parsing, this will list "foo" in long mode. In strict POSIX style, this will list the files named "foo" and "-l".
It may be useful to force strict POSIX mode when creating "verb style" command line tools. For example, the "gsettings" command line tool supports the global option "--schemadir" as well as many subcommands ("get", "set", etc.) which each have their own set of arguments. Using strict POSIX mode will allow parsing the global options up to the verb name while leaving the remaining options to be parsed by the relevant subcommand (which can be determined by examining the verb name, which should be present in argv[1] after parsing).
| strict_posix | The new value. |
| void Glib::OptionContext::set_summary | ( | const Glib::ustring & | summary | ) |
Adds a string to be displayed in --help output before the list of options.
This is typically a summary of the program functionality.
Note that the summary is translated (see g_option_context_set_translate_func() and g_option_context_set_translation_domain()).
| summary | A string to be shown in –help output before the list of options. |
| void Glib::OptionContext::set_translate_func | ( | const SlotTranslate & | slot | ) |
Sets the function which is used to translate user-visible strings, for –help output.
Different groups can use different functions.
If you are using gettext(), you only need to set the translation domain, see set_translation_domain().
| void Glib::OptionContext::set_translation_domain | ( | const Glib::ustring & | domain | ) |
A convenience function to use gettext() for translating user-visible strings.
| domain | The domain to use. |
|
protected |
|
protected |
1.9.8