A GOptionContext struct defines which options are accepted by the commandline option parser. The struct has only private fields and should not be directly accessed.
procedure Add_Group (Self : Goption_Context; Group : GOption_Group)
Adds a Glib.Option.GOption_Group to the Context, so that parsing with Context will recognize the options in the group. Note that this will take ownership of the Group and thus the Group should not be freed. Since: gtk+ 2.6
the group to add
procedure Add_Main_Entries
(Self : Goption_Context;
Entries : GOption_Entry_Array;
Translation_Domain : UTF8_String := "")
A convenience function which creates a main group if it doesn't exist, adds the Entries to it and sets the translation domain. Since: gtk+ 2.6
a null-terminated array of GOption_Entrys
a translation domain to use for translating the --help output for the options in Entries with gettext, or null
procedure Free (Self : Goption_Context)
Frees context and all the groups which have been added to it. Please note that parsed arguments need to be freed separately (see Glib.Option.GOption_Entry). Since: gtk+ 2.6
has transfer-ownership='full'.
function From_Object (Object : System.Address) return Goption_Context
function From_Object_Free (B : access Goption_Context'Class) return Goption_Context
function From_Object_Free
(B : not null access GOption_Entry) return GOption_Entry
Return the underlying object and free the pointer. This is meant to be used internally by GtkAda, and should not in general be called by user code.
function From_Object_Free
(B : not null access GOption_Group) return GOption_Group
Return the underlying object and free the pointer. This is meant to be used internally by GtkAda, and should not in general be called by user code.
function G_New
(Parameter_String : UTF8_String := "") return Goption_Context
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 Glib.Option.Goption_Context, 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 Glib.Option.GOption_Entry 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 Glib.Option.Set_Summary. Note that the Parameter_String is translated using the function set with Glib.Option.Set_Translate_Func, so it should normally be passed untranslated. Since: gtk+ 2.6
a string which is displayed in the first line of --help output, after the usage summary programname [OPTION...]
a newly created Glib.Option.Goption_Context, which must be freed with Glib.Option.Free after use. Has transfer-ownership='full'.
G_Option_Flag_Deprecated : constant GOption_Flags := 128;
G_Option_Flag_Filename : constant GOption_Flags := 16;
G_Option_Flag_Hidden : constant GOption_Flags := 1;
G_Option_Flag_In_Main : constant GOption_Flags := 2;
G_Option_Flag_No_Arg : constant GOption_Flags := 8;
G_Option_Flag_Noalias : constant GOption_Flags := 64;
G_Option_Flag_None : constant GOption_Flags := 0;
G_Option_Flag_Optional_Arg : constant GOption_Flags := 32;
G_Option_Flag_Reverse : constant GOption_Flags := 4;
function Get_Description (Self : Goption_Context) return UTF8_String
Returns the description. See Glib.Option.Set_Description. Since: gtk+ 2.12
the description
function Get_Help
(Self : Goption_Context;
Main_Help : Boolean;
Group : GOption_Group) return UTF8_String
Returns a formatted, translated help text for the given context. To obtain the text produced by --help, call g_option_context_get_help (context, TRUE, NULL). To obtain the text produced by --help-all, call g_option_context_get_help (context, FALSE, NULL). To obtain the help text for an option group, call g_option_context_get_help (context, FALSE, group). Since: gtk+ 2.14
if True, only include the main group
the Glib.Option.GOption_Group to create help for, or null
A newly allocated string containing the help text
function Get_Help_Enabled (Self : Goption_Context) return Boolean
Returns whether automatic --help generation is turned on for Context. See Glib.Option.Set_Help_Enabled. Since: gtk+ 2.6
True if automatic help generation is turned on.
function Get_Ignore_Unknown_Options
(Self : Goption_Context) return Boolean
Returns whether unknown options are ignored or not. See Glib.Option.Set_Ignore_Unknown_Options. Since: gtk+ 2.6
True if unknown options are ignored.
function Get_Main_Group (Self : Goption_Context) return GOption_Group
Returns a pointer to the main group of Context. Since: gtk+ 2.6
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.
function Get_Strict_Posix (Self : Goption_Context) return Boolean
Returns whether strict POSIX code is enabled. See Glib.Option.Set_Strict_Posix for more information. Since: gtk+ 2.44
True if strict POSIX is enabled, False otherwise.
function Get_Summary (Self : Goption_Context) return UTF8_String
Returns the summary. See Glib.Option.Set_Summary. Since: gtk+ 2.12
the summary
type GOption_Arg is (
G_Option_Arg_None,
G_Option_Arg_String,
G_Option_Arg_Int,
G_Option_Arg_Callback,
G_Option_Arg_Filename,
G_Option_Arg_String_Array,
G_Option_Arg_Filename_Array,
G_Option_Arg_Double,
G_Option_Arg_Int64);
The Glib.Option.GOption_Arg enum values determine which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways; with a short option: -x arg, with a long option: --name arg or combined in a single argument: --name=arg.
package GOption_Arg_Properties is
new Generic_Internal_Discrete_Property (GOption_Arg);
type Goption_Context is new Glib.C_Boxed with null record;
type GOption_Entry is record
Long_Name : Gtkada.Types.Chars_Ptr;
Short_Name : Gchar;
Flags : GOption_Flags;
Arg : GOption_Arg;
Arg_Data : System.Address := System.Null_Address;
Description : Gtkada.Types.Chars_Ptr;
Arg_Description : Gtkada.Types.Chars_Ptr;
end record;
Glib.Option.G_Option_Arg_None: %gboolean -
Glib.Option.G_Option_Arg_String: %gchar* - Glib.Option.G_Option_Arg_Int: %gint - Glib.Option.G_Option_Arg_Filename: %gchar* - Glib.Option.G_Option_Arg_String_Array: %gchar** - Glib.Option.G_Option_Arg_Filename_Array: %gchar** - Glib.Option.G_Option_Arg_Double: %gdouble
If Arg type is Glib.Option.G_Option_Arg_String or Glib.Option.G_Option_Arg_Filename, the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free. Likewise if Arg type is Glib.Option.G_Option_Arg_String_Array or Glib.Option.G_Option_Arg_Filename_Array, the data should be freed using g_strfreev. A GOptionEntry struct defines a single option. To have an effect, they must be added to a Glib.Option.GOption_Group with Glib.Option.Add_Main_Entries or g_option_group_add_entries.
type GOption_Entry_Array is array (Natural range <>) of GOption_Entry;
type GOption_Error is (
G_Option_Error_Unknown_Option,
G_Option_Error_Bad_Value,
G_Option_Error_Failed);
Error codes returned by option parsing.
GOption_Error_Domain : constant GQuark := Quark_From_String (GOption_Error_Name);
Used to identify error domain in a GError
function GOption_Error_Matches
(Error : GError; Code : GOption_Error) return Boolean
Convenience helper to match error codes
GOption_Error_Name : constant UTF8_String := "g-option-context-error-quark";
Used to identify error domain in a GError
package GOption_Error_Properties is
new Generic_Internal_Discrete_Property (GOption_Error);
type GOption_Flags is mod 2 ** Integer'Size;
Flags which modify individual options.
package GOption_Flags_Properties is
new Generic_Internal_Flags_Property (GOption_Flags);
type GOption_Group is new Glib.C_Proxy;
A GOptionGroup struct defines the options in a single group. The struct has only private fields and should not be directly accessed.
All options in a group share the same translation function. Libraries which need to parse commandline options are expected to provide a function for getting a GOptionGroup holding their options, which the application can then add to its Glib.Option.Goption_Context.
type Gtranslate_Func is access function (Str : UTF8_String) return UTF8_String;
The type of functions which are used to translate user-visible strings, for <option>--help</option> output.
the untranslated string
a translation of the string for the current locale. The returned string is owned by GLib and must not be freed.
Null_Goption_Context : constant Goption_Context;
Null_GOption_Entry : constant GOption_Entry;
procedure Parse
(Self : Goption_Context;
Argv : access chars_ptr_array_access
Success : out Boolean;
Error : out Glib.Error.GError)
This version is suitable for use from Glib.Application.Local_Command_Line
Null-terminated
procedure Parse
(Self : Goption_Context;
Command_Line : not null access Glib.Application.Gapplication_Command_Line_Record'Class;
Filter : Parse_Filter := null;
Success : out Boolean;
Error : out Glib.Error.GError)
Parses the arguments given via Command_Line, removing from the arguments list all parsed switches.
type Parse_Filter is access function (Param : String) return Boolean;
Returns True if the parameter is to be passed from Command_Line to Goption_Context
type Property_GOption_Arg is new GOption_Arg_Properties.Property;
type Property_GOption_Error is new GOption_Error_Properties.Property;
type Property_GOption_Flags is new GOption_Flags_Properties.Property;
procedure Set_Description
(Self : Goption_Context;
Description : UTF8_String := "")
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 Glib.Option.Set_Translate_Func). Since: gtk+ 2.12
a string to be shown in --help output after the list of options, or null
procedure Set_Help_Enabled
(Self : Goption_Context;
Help_Enabled : Boolean)
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: gtk+ 2.6
True to enable --help, False to disable it
procedure Set_Ignore_Unknown_Options
(Self : Goption_Context;
Ignore_Unknown : Boolean)
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: gtk+ 2.6
True to ignore unknown options, False to produce an error when unknown options are met
procedure Set_Main_Group (Self : Goption_Context; Group : GOption_Group)
Sets a Glib.Option.GOption_Group as main group of the Context. This has the same effect as calling Glib.Option.Add_Group, the only difference is that the options in the main group are treated differently when generating --help output. Since: gtk+ 2.6
the group to set as main group
procedure Set_Strict_Posix
(Self : Goption_Context;
Strict_Posix : Boolean)
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: gtk+ 2.44
the new value
procedure Set_Summary
(Self : Goption_Context;
Summary : UTF8_String := "")
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 Glib.Option.Set_Translate_Func and Glib.Option.Set_Translation_Domain). Since: gtk+ 2.12
a string to be shown in --help output before the list of options, or null
procedure Set_Translate_Func
(Self : Goption_Context;
Func : Gtranslate_Func;
Destroy_Notify : Glib.G_Destroy_Notify_Address)
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 Glib.Option.G_New), the summary (see Glib.Option.Set_Summary) and the description (see Glib.Option.Set_Description). If you are using gettext, you only need to set the translation domain, see Glib.Option.Set_Translation_Domain. Since: gtk+ 2.12
the Gtranslate_Func, or null
a function which gets called to free Data, or null
procedure Set_Translation_Domain
(Self : Goption_Context;
Domain : UTF8_String)
A convenience function to use gettext for translating user-visible strings. Since: gtk+ 2.12
the domain to use