Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::G::OptionContext Class Reference

A C++ wrapper interface for GOptionContext. More...

#include <xfc/glib/option.hh>

Inheritance diagram for Xfc::G::OptionContext:

Xfc::Object Xfc::Trackable List of all members.

Public Member Functions

Constructors
Accessors
Methods

Detailed Description

A C++ wrapper interface for GOptionContext.

OptionContext defines which options are accepted by the commandline option parser.

The GLib commandline option parser supports the use of short and long commandline options. Short options take one hyphen and a character, like "-a". Long options take two hyphens and a string, like "--all". Both option types can take arguments. When using short options, the argument must be given after the option, separated by a space. When using long options, the argument can either be separated by a space or appended with an equal sign. Look at the following commandline:

    testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2

This example demonstrates a number of features of the GLib commandline option parser:

  1. Options can be single letters, prefixed by a single hyphen.
  2. Multiple short options can be grouped behind a single hyphen.
  3. Long options are prefixed by two consecutive hyphens.
  4. Options can have an extra argument, which can be a number, a string or a filename.
  5. For long options, the extra argument can be appended with an equals sign after the option name.
  6. Non-option arguments are returned to the application as rest arguments.
  7. An argument consisting solely of two hyphens turns off further parsing.
An important feature of the parser is that an argument consisting solely of two hyphens turns off further parsing, and any remaining arguments (even those starting with a hyphen) are returned to the application as rest arguments. Another important feature is that the parser can automatically generate nicely formatted help output. Unless it is explicitly turned off with set_help_enabled(), the parser will recognize the --help, -?, --help-all and --help-groupname options (where groupname is the name of a OptionGroup) and write a text similar to the one shown in the following example to stdout:

    Usage:
      testtreemodel [OPTION...] - test tree model performance
    
    Help Options:
      --help                   Show help options
      --help-all               Show all help options
      --help-gtk               Show GTK+ Options
    
    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

Grouping options into groups makes it easy for applications to incorporate options from multiple sources. This allows an application to collect option groups from the libraries it uses, add them to their option context, and parse all options with a one call to G::OptionContext::parse(). If an option is declared to be of type string or filename, the parser takes care of converting it to the right encoding; strings are returned in UTF-8, filenames are returned in the GLib filename encoding.

Example: Sets up an option parser to parse the above commandline and produce the help output. 

    int repeats = 2;
    int max_size = 8;
    bool verbose = false;
    bool beep = false;
    bool rand = false;
   
    int main (int argc, char *argv[])
    {
        G::OptionGroup main_group;
        main_group->add("repeats", 'r', &repeats, "Average over N repetitions", "N");
        main_group->add("max-size", 'm', &max_size, "Test up to 2^M items", "M");
        main_group->add("verbose", 'v', &verbose, "Be verbose");
        main_group->add("beep", 'b', &beep, "Beep when done");
        main_group->add("rand", 0, &rand, "Randomize the data");
        G::OptionContext context("- test tree model performance", main_group);
        context->add_group(Main::get_option_group());
   
        G::Error error;
        context->parse(&argc, &argv, &error);
        ...
    }

Main::get_option_group() returns an option group for all the commandline arguments recognized by GTK+ and GDK. Adding this group to your context and calling parse() will initialize the XFC library so you wont need to call Main::init().

Constructor & Destructor Documentation

Xfc::G::OptionContext::OptionContext (  const String &  parameter_string  ) 
 

Construct a new option context.

Parameters:
parameter_string The string to display in the first line of --help output, after programname [OPTION...].

Xfc::G::OptionContext::OptionContext (  const String &  parameter_string,
OptionGroup &  main_group
) 
 

Construct a new option context with the specified main group.

Parameters:
parameter_string The string to display in the first line of --help output, after programname [OPTION...].
main_group The group to set as the main group for the option context.
The options in the main group are treated differently when generating --help output.

Xfc::G::OptionContext::OptionContext (  GOptionContext *  context,
bool  can_free
) 
 

Construct a new option context from an existing GOptionContext.

Parameters:
context A GOptionContext.
can_free Set true if the GOptionContext should be freed by this option context.
This constructor is used to wrap a GOptionContext pointer in a temporary G::OptionContext class for passing to G::OptionGroup::on_pre_parse() and G::OptionGroup::on_post_parse(). You should have no need to use this constructor.

Member Function Documentation

void Xfc::G::OptionContext::add_group (  OptionGroup &  group  ) 
 

Adds an OptionGroup to the option context, so that parsing with the option context will recognize the options in the group.

Parameters:
group A group to add to the context.
Note that the group will be destroyed together with the context, when the context is destroyed, so you must not unreference the group yourself after adding it to a context.

void Xfc::G::OptionContext::add_group (  GOptionGroup *  group  ) 
 

Adds a GOptionGroup to the option context, so that parsing with the option context will recognize the options in the group.

Parameters:
group A GOptionGroup to add to the context.
For convenience, this method lets you add an unwrapped GOptionGroup to the context. The purpose of the method is to make it easy to add GOptionGroups returned by other libraries, such as the GTK+ option group returned from Main::get_option_group(). Note that the group will be destroyed together with the context, when the context is destroyed, so you must not unreference the group yourself after adding it to a context.

bool Xfc::G::OptionContext::get_help_enabled (   )  const
 

Determines whether automatic --help generation is turned on for context (see set_help_enabled()).

Returns:
true if automatic help generation is turned on.

bool Xfc::G::OptionContext::get_ignore_unknown_options (   )  const
 

Determines whether unknown options are ignored or not (see set_ignore_unknown_options()).

Returns:
true if unknown options are ignored.

Pointer<OptionGroup> Xfc::G::OptionContext::get_main_group (   )  const
 

Gets a pointer to the main group of context.

Returns:
The main group of context, or null if context doesn't have a main group.
Note that group belongs to context and should not be modified.

bool Xfc::G::OptionContext::parse (  int *  argc,
char ***  argv,
Error *  error
) 
 

Parses the command line arguments, recognizing options which have been added to context.

Parameters:
argc A pointer to the number of command line arguments.
argv A pointer to the array of command line arguments.
error The return location for errors.
Returns:
true if the parsing was successful, false if an error occurred.
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. In case of an error, argc and argv are left unmodified.

If automatic --help support is enabled (see set_help_enabled()), and the argv array contains one of the recognized help options, this method will produce help output to stdout and call exit(0).

void Xfc::G::OptionContext::set_help_enabled (  bool  help_enabled  ) 
 

Enables or disables automatic generation of --help output.

Parameters:
help_enabled Set true to enable --help, false to disable it.
By default, parse() recognizes --help, -?, --help-all and --help-groupname and creates suitable output to stdout.

void Xfc::G::OptionContext::set_ignore_unknown_options (  bool  ignore_unknown  ) 
 

Sets whether to ignore unknown options or not.

Parameters:
ignore_unknown Set true to ignore unknown options.
If ignore_unknown is set to false, an error is produced when unknown options are met. If an argument is ignored, it is left in the argv array after parsing. By default, 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 the option parser cannot reliably determine whether a non-option belongs to a preceding unknown option.

void Xfc::G::OptionContext::set_main_group (  OptionGroup &  group  ) 
 

Sets group to be the main group for the context.

Parameters:
group The group to set as main group for 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, a context can have only one main group.

The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3