glibmm: 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={})
 Creates a new option context. More...

 
 OptionContext (GOptionContext* castitem, bool take_ownership=false)
 
 OptionContext (const OptionContext& other)=delete
 
OptionContextoperator= (const OptionContext& other)=delete
 
 OptionContext (OptionContext&& other) noexcept
 
OptionContextoperator= (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

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

Glib::OptionContext::OptionContext ( const Glib::ustring parameter_string = {})
explicit

Creates a new option context.

Parameters
parameter_stringA string which is displayed in the first line of –help output, after programname [OPTION...]
Glib::OptionContext::OptionContext ( GOptionContext *  castitem,
bool  take_ownership = false 
)
explicit
Glib::OptionContext::OptionContext ( const OptionContext other)
delete
Glib::OptionContext::OptionContext ( OptionContext&&  other)
noexcept
virtual Glib::OptionContext::~OptionContext ( )
virtual

Member Function Documentation

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
groupThe group to add.
Glib::ustring Glib::OptionContext::get_description ( ) const

Returns the description.

See g_option_context_set_description().

Since glibmm 2.12:
Returns
The description.
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_helpIf true, only include the main group.
groupThe OptionGroup to create help for, or nullptr.
Returns
A newly allocated string containing the help text.
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_helpIf true, only include the main group.
Returns
string containing the help text.
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.
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.
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.
Glib::ustring Glib::OptionContext::get_summary ( ) const

Returns the summary.

See g_option_context_set_summary().

Since glibmm 2.12:
Returns
The summary.
GOptionContext* Glib::OptionContext::gobj ( )
inline
const GOptionContext* Glib::OptionContext::gobj ( ) const
inline
OptionContext& Glib::OptionContext::operator= ( const OptionContext other)
delete
OptionContext& Glib::OptionContext::operator= ( OptionContext&&  other)
noexcept
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
argcA pointer to the number of command line arguments.
argvA 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
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]argvA 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
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
descriptionA string to be shown in –help output after the list of options.
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_enabledtrue to enable --help, false to disable it.
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_unknowntrue 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.

Parameters
groupThe group to add.
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_posixThe 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()).

Since glibmm 2.12:
Parameters
summaryA 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().

Since glibmm 2.14:
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
domainThe domain to use.

Member Data Documentation

GOptionContext* Glib::OptionContext::gobject_
protected
bool Glib::OptionContext::has_ownership_
protected