glibmm 2.56.0

Public Types | Public Member Functions | Protected Attributes | List of all members
Glib::OptionContext Class Reference

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. More...

## Public Member Functions
| OptionContext (const Glib::ustring& parameter_string=Glib::ustring())
| Creates a new option context. More...
| OptionContext (GOptionContext* castitem, bool take_ownership=false)
| 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. More...
bool | get_help_enabled () const
| Returns whether automatic `--help` generation is turned on for context. More...
void | set_ignore_unknown_options (bool ignore_unknown=true)
| Sets whether to ignore unknown options or not. More...
bool | get_ignore_unknown_options () const
| Returns whether unknown options are ignored or not. More...
void | set_strict_posix (bool strict_posix=true)
| Sets strict POSIX mode. More...
bool | get_strict_posix () const
| Returns whether strict POSIX code is enabled. More...
bool | parse (int& argc, char**& argv)
| Parses the command line arguments, recognizing options which have been added to context. More...
bool | parse (char**& argv)
| Parses the command line arguments. More...
void | add_group (OptionGroup& group)
| Adds an OptionGroup to the context, so that parsing with context will recognize the options in the group. More...
void | set_main_group (OptionGroup& group)
| Sets an OptionGroup as the main group of the context. More...
Glib::ustring | get_help (bool main_help, const OptionGroup& group) const
| Returns a formatted, translated help text for the given context. More...
Glib::ustring | get_help (bool main_help=true) const
| Returns a formatted, translated help text for the given context. More...
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. More...
Glib::ustring | get_summary () const
| Returns the summary. More...
void | set_description (const Glib::ustring& description)
| Adds a string to be displayed in `--help` output after the list of options. More...
Glib::ustring | get_description () const
| Returns the description. More...
void | set_translation_domain (const Glib::ustring& domain)
| A convenience function to use gettext() for translating user-visible strings. More...
void | set_translate_func (const SlotTranslate& slot)
| Sets the function which is used to translate user-visible strings, for –help output. More...

## Protected Attributes
GOptionContext* | gobject_
bool | has_ownership_

## Detailed Description

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:

- Options can be single letters, prefixed by a single dash.
- Multiple short options can be grouped behind a single dash.
- Long options are prefixed by two consecutive dashes.
- 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, which is useful if the extra argument starts with a dash, which would otherwise cause it to be interpreted as another option.
- Non-option arguments are returned to the application as rest arguments.
- An argument consisting solely of two dashes turns off further parsing, any remaining arguments (even those starting with a dash) are returned to the application as rest arguments.

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.

## Member Typedef Documentation

## ◆ SlotTranslate

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

## Constructor & Destructor Documentation

## ◆ OptionContext() [1/3]

Glib::OptionContext::OptionContext | ( | const Glib::ustring& | parameter_string = `Glib::ustring()` | ) |
| explicit

Creates a new option context.

Parameters

  parameter_string | A string which is displayed in the first line of –help output, after programname [OPTION...]

## ◆ OptionContext() [2/3]

Glib::OptionContext::OptionContext | ( | GOptionContext * | castitem,
|  | bool | take_ownership = `false`
| ) |  |
| explicit

## ◆ OptionContext() [3/3]

Glib::OptionContext::OptionContext | ( | OptionContext&& | other | ) |
| noexcept

## ◆ ~OptionContext()

virtual Glib::OptionContext::~OptionContext | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ add_group()

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.

Parameters

  group | The group to add.

## ◆ get_description()

Glib::ustring Glib::OptionContext::get_description | ( |  | ) | const

Returns the description.

See g_option_context_set_description().

Since glibmm 2.12:

Returns
  The description.

## ◆ get_help() [1/2]

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)`.

Since glibmm 2.14:

Parameters

  main_help | If `true`, only include the main group.
  group | The OptionGroup to create help for, or `nullptr`.

Returns
  A newly allocated string containing the help text.

## ◆ get_help() [2/2]

Glib::ustring Glib::OptionContext::get_help | ( | bool | main_help = `true` | ) | const

Returns a formatted, translated help text for the given context.

- To obtain the text produced by –help, call get_help(true).
- To obtain the text produced by –help-all, call get_help(false).
- To obtain the help text for an option group, call get_help(false, group).

Parameters

  main_help | If true, only include the main group.

Returns
  string containing the help text.

## ◆ get_help_enabled()

bool Glib::OptionContext::get_help_enabled | ( |  | ) | const

Returns whether automatic `--help` generation is turned on for context.

See g_option_context_set_help_enabled().

Since glibmm 2.6:

Returns
  `true` if automatic help generation is turned on.

## ◆ get_ignore_unknown_options()

bool Glib::OptionContext::get_ignore_unknown_options | ( |  | ) | const

Returns whether unknown options are ignored or not.

See g_option_context_set_ignore_unknown_options().

Since glibmm 2.6:

Returns
  `true` if unknown options are ignored.

## ◆ get_strict_posix()

bool Glib::OptionContext::get_strict_posix | ( |  | ) | const

Returns whether strict POSIX code is enabled.

See g_option_context_set_strict_posix() for more information.

Since glibmm 2.44:

Returns
  `true` if strict POSIX is enabled, `false` otherwise.

## ◆ get_summary()

Glib::ustring Glib::OptionContext::get_summary | ( |  | ) | const

Returns the summary.

See g_option_context_set_summary().

Since glibmm 2.12:

Returns
  The summary.

## ◆ gobj() [1/2]

GOptionContext* Glib::OptionContext::gobj | ( |  | ) |
| inline

## ◆ gobj() [2/2]

const GOptionContext* Glib::OptionContext::gobj | ( |  | ) | const
| inline

## ◆ operator=()

OptionContext& Glib::OptionContext::operator= | ( | OptionContext&& | other | ) |
| noexcept

## ◆ parse() [1/2]

bool Glib::OptionContext::parse | ( | int & | argc,
|  | char **& | argv
| ) |  |

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.

Since glibmm 2.6:

Parameters

  argc | A pointer to the number of command line arguments.
  argv | A pointer to the array of command line arguments.

Returns
  `true` if the parsing was successful, `false` if an error occurred.

Exceptions

  Glib::OptionError |
  Glib::ConvertError |

## ◆ parse() [2/2]

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.

Since glibmm 2.50:

Parameters

  [in,out] | argv | A pointer to the command line arguments (which must be in UTF-8 on Windows).

Returns
  `true` if the parsing was successful, `false` if an error occurred.

Exceptions

  Glib::OptionError |
  Glib::ConvertError |

## ◆ set_description()

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()).

Since glibmm 2.12:

Parameters

  description | A string to be shown in –help output after the list of options.

## ◆ set_help_enabled()

void Glib::OptionContext::set_help_enabled | ( | bool | help_enabled = `true` | ) |

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.

Since glibmm 2.6:

Parameters

  help_enabled | `true` to enable `--help`, `false` to disable it.

## ◆ set_ignore_unknown_options()

void Glib::OptionContext::set_ignore_unknown_options | ( | bool | ignore_unknown = `true` | ) |

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.

Since glibmm 2.6:

Parameters

  ignore_unknown | `true` to ignore unknown options, `false` to produce an error when unknown options are met.

## ◆ set_main_group()

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.

Parameters

  group | The group to add.

## ◆ set_strict_posix()

void Glib::OptionContext::set_strict_posix | ( | bool | strict_posix = `true` | ) |

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).

Since glibmm 2.44:

Parameters

  strict_posix | The new value.

## ◆ set_summary()

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()).

Since glibmm 2.12:

Parameters

  summary | A string to be shown in –help output before the list of options.

## ◆ set_translate_func()

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().

Since glibmm 2.14:

## ◆ set_translation_domain()

void Glib::OptionContext::set_translation_domain | ( | const Glib::ustring& | domain | ) |

A convenience function to use gettext() for translating user-visible strings.

Since glibmm 2.12:

Parameters

  domain | The domain to use.

## Member Data Documentation

## ◆ gobject_

GOptionContext* Glib::OptionContext::gobject_
| protected

## ◆ has_ownership_

bool Glib::OptionContext::has_ownership_
| protected