glib.OptionContext.OptionContext Class Reference

List of all members.

Detailed Description

Description The GOption commandline parser is intended to be a simpler replacement for the popt library.

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. 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. Another important feature of GOption is that it can automatically generate nicely formatted help output. Unless it is explicitly turned off with g_option_context_set_help_enabled(), GOption will recognize the --help, -?, --help-all and --help-groupname options (where groupname is the name of a GOptionGroup) 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 GOption groups options in GOptionGroups, 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 GOptionContext, and parse all options by a single call to g_option_context_parse(). See gtk_get_option_group() for an example. If an option is declared to be of type string or filename, GOption takes care of converting it to the right encoding; strings are returned in UTF-8, filenames are returned in the GLib filename encoding. Note that this only works if setlocale() has been called before g_option_context_parse(). Here is a complete example of setting up GOption to parse the example commandline above and produce the example help output. 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, repeats, "Average over N repetitions", "N" }, { "max-size", 'm', 0, G_OPTION_ARG_INT, max_size, "Test up to 2^M items", "M" }, { "verbose", 'v', 0, G_OPTION_ARG_NONE, verbose, "Be verbose", NULL }, { "beep", 'b', 0, G_OPTION_ARG_NONE, beep, "Beep when done", NULL }, { "rand", 0, 0, G_OPTION_ARG_NONE, rand, "Randomize the data", NULL }, { NULL } }; int main (int argc, char *argv[]) { GError *error = NULL; GOptionContext *context; context = g_option_context_new ("- test tree model performance"); 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, argc, argv, error); /+* ... +/ }


Public Member Functions

GOptionContextgetOptionContextStruct ()
 this (GOptionContext *gOptionContext)
 Sets our main struct and passes it to the parent class.
 this (char[] parameterString)
 Creates a new option context.
void setSummary (char[] summary)
 Adds a string to be displayed in --help output before the list of options.
char[] getSummary ()
 Returns the summary.
void setDescription (char[] description)
 Adds a string to be displayed in --help output after the list of options.
char[] getDescription ()
 Returns the description.
void setTranslateFunc (GTranslateFunc func, void *data, GDestroyNotify destroyNotify)
 Sets the function which is used to translate the contexts user-visible strings, for --help output.
void setTranslationDomain (char[] domain)
 A convenience function to use gettext() for translating user-visible strings.
void free ()
 Frees context and all the groups which have been added to it.
int parse (int *argc, char ***argv, GError **error)
 Parses the command line arguments, recognizing options which have been added to context.
void setHelpEnabled (int helpEnabled)
 Enables or disables automatic generation of --help output.
int getHelpEnabled ()
 Returns whether automatic --help generation is turned on for context.
void setIgnoreUnknownOptions (int ignoreUnknown)
 Sets whether to ignore unknown options or not.
int getIgnoreUnknownOptions ()
 Returns whether unknown options are ignored or not.
void addMainEntries (GOptionEntry *entries, char[] translationDomain)
 A convenience function which creates a main group if it doesn't exist, adds the entries to it and sets the translation domain.
void addGroup (OptionGroup group)
 Adds a GOptionGroup to the context, so that parsing with context will recognize the options in the group.
void setMainGroup (OptionGroup group)
 Sets a GOptionGroup as main group of the context.
OptionGroup getMainGroup ()
 Returns a pointer to the main group of context.

Protected Member Functions

void * getStruct ()
 the main Gtk struct as a void*

Protected Attributes

GOptionContextgOptionContext
 the main Gtk struct


Constructor & Destructor Documentation

glib.OptionContext.OptionContext.this ( GOptionContext gOptionContext  ) 

Sets our main struct and passes it to the parent class.

glib.OptionContext.OptionContext.this ( char[]  parameterString  ) 

Creates a new option context.

The parameter_string can serve multiple purposes. It can be used to add descriptions for "rest" arguments, which are not parsed by the GOptionContext, typically something like "FILES" or "FILE1 FILE2...". If you are using G_OPTION_REMAINING for collecting "rest" arguments, GLib handles this automatically by using the arg_description of the corresponding GOptionEntry in the usage summary. Another usage is to give a short summary of the program functionality, like " - frob the strings", which will be displayed in the same line as the usage. For a longer description of the program functionality that should be displayed as a paragraph below the usage line, use g_option_context_set_summary(). Note that the parameter_string is translated (see g_option_context_set_translate_func()). parameter_string: a string which is displayed in the first line of --help output, after the usage summary programname [OPTION...] Returns: a newly created GOptionContext, which must be freed with g_option_context_free() after use. Since 2.6


Member Function Documentation

void glib.OptionContext.OptionContext.addGroup ( OptionGroup  group  ) 

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

Note that the group will be freed together with the context when g_option_context_free() is called, so you must not free the group yourself after adding it to a context. context: a GOptionContext group: the group to add Since 2.6

void glib.OptionContext.OptionContext.addMainEntries ( GOptionEntry entries,
char[]  translationDomain 
)

A convenience function which creates a main group if it doesn't exist, adds the entries to it and sets the translation domain.

context: a GOptionContext entries: a NULL-terminated array of GOptionEntrys translation_domain: a translation domain to use for translating the --help output for the options in entries with gettext(), or NULL Since 2.6

void glib.OptionContext.OptionContext.free (  ) 

Frees context and all the groups which have been added to it.

context: a GOptionContext Since 2.6

char [] glib.OptionContext.OptionContext.getDescription (  ) 

Returns the description.

See g_option_context_set_description(). context: a GOptionContext Returns: the description Since 2.12

int glib.OptionContext.OptionContext.getHelpEnabled (  ) 

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

See g_option_context_set_help_enabled(). context: a GOptionContext Returns: TRUE if automatic help generation is turned on. Since 2.6

int glib.OptionContext.OptionContext.getIgnoreUnknownOptions (  ) 

Returns whether unknown options are ignored or not.

See g_option_context_set_ignore_unknown_options(). context: a GOptionContext Returns: TRUE if unknown options are ignored. Since 2.6

OptionGroup glib.OptionContext.OptionContext.getMainGroup (  ) 

Returns a pointer to the main group of context.

context: a GOptionContext 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 or freed. Since 2.6

GOptionContext* glib.OptionContext.OptionContext.getOptionContextStruct (  ) 

void* glib.OptionContext.OptionContext.getStruct (  )  [protected]

the main Gtk struct as a void*

char [] glib.OptionContext.OptionContext.getSummary (  ) 

Returns the summary.

See g_option_context_set_summary(). context: a GOptionContext Returns: the summary Since 2.12

int glib.OptionContext.OptionContext.parse ( int argc,
char ***  argv,
GError **  error 
)

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 for automatic character set conversion of string and filename arguments. context: a GOptionContext argc: a pointer to the number of command line arguments argv: a pointer to the array of command line arguments error: a return location for errors Returns: TRUE if the parsing was successful, FALSE if an error occurred Since 2.6

void glib.OptionContext.OptionContext.setDescription ( char[]  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()). context: a GOptionContext description: a string to be shown in --help output after the list of options, or NULL Since 2.12

void glib.OptionContext.OptionContext.setHelpEnabled ( int  helpEnabled  ) 

Enables or disables automatic generation of --help output.

By default, g_option_context_parse() recognizes --help, -?, --help-all and --help-groupname and creates suitable output to stdout. context: a GOptionContext help_enabled: TRUE to enable --help, FALSE to disable it Since 2.6

void glib.OptionContext.OptionContext.setIgnoreUnknownOptions ( int  ignoreUnknown  ) 

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. context: a GOptionContext ignore_unknown: TRUE to ignore unknown options, FALSE to produce an error when unknown options are met Since 2.6

void glib.OptionContext.OptionContext.setMainGroup ( OptionGroup  group  ) 

Sets a GOptionGroup as main group of the context.

This has the same effect as calling g_option_context_add_group(), the only difference is that the options in the main group are treated differently when generating --help output. context: a GOptionContext group: the group to set as main group Since 2.6

void glib.OptionContext.OptionContext.setSummary ( char[]  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()). context: a GOptionContext summary: a string to be shown in --help output before the list of options, or NULL Since 2.12

void glib.OptionContext.OptionContext.setTranslateFunc ( GTranslateFunc  func,
void *  data,
GDestroyNotify  destroyNotify 
)

Sets the function which is used to translate the contexts user-visible strings, for --help output.

If func is NULL, strings are not translated. Note that option groups have their own translation functions, this function only affects the parameter_string (see g_option_context_nex()), the summary (see g_option_context_set_summary()) and the description (see g_option_context_set_description()). If you are using gettext(), you only need to set the translation domain, see g_context_group_set_translation_domain(). context: a GOptionContext func: the GTranslateFunc, or NULL data: user data to pass to func, or NULL destroy_notify: a function which gets called to free data, or NULL Since 2.12

void glib.OptionContext.OptionContext.setTranslationDomain ( char[]  domain  ) 

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

context: a GOptionContext domain: the domain to use Since 2.12


Member Data Documentation

GOptionContext* glib.OptionContext.OptionContext.gOptionContext [protected]

the main Gtk struct


SourceForge.net Logo DSource.org Logo digitalmars.com Logo