------------------------------------------------------------------------------ -- -- -- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet -- -- Copyright (C) 2000-2014, AdaCore -- -- -- -- This library is free software; you can redistribute it and/or modify it -- -- under terms of the GNU General Public License as published by the Free -- -- Software Foundation; either version 3, or (at your option) any later -- -- version. This library is distributed in the hope that it will be useful, -- -- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- -- -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. -- -- -- -- As a special exception under Section 7 of GPL version 3, you are granted -- -- additional permissions described in the GCC Runtime Library Exception, -- -- version 3.1, as published by the Free Software Foundation. -- -- -- -- You should have received a copy of the GNU General Public License and -- -- a copy of the GCC Runtime Library Exception along with this program; -- -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- -- <http://www.gnu.org/licenses/>. -- -- -- ------------------------------------------------------------------------------ -- <description> -- A <structname>GOptionContext</structname> struct defines which options are -- accepted by the commandline option parser. The struct has only private -- fields and should not be directly accessed. -- -- </description> pragma Ada_2005; pragma Warnings (Off, "*is already use-visible*");
with Glib; use Glib;
with Glib.Application; use Glib.Application;
with Glib.Error; use Glib.Error;
with Glib.Generic_Properties; use Glib.Generic_Properties;
with Gtkada.Bindings; use Gtkada.Bindings;
with Interfaces.C.Strings; use Interfaces.C.Strings;
package Glib.Option is
type Goption_Context is new Glib.C_Boxed with null record;
Null_Goption_Context : constant Goption_Context;
function From_Object (Object : System.Address) return Goption_Context;
function From_Object_Free (B : access Goption_Context'Class) return Goption_Context;
pragma Inline (From_Object_Free, From_Object);
type GOption_Error is (
G_Option_Error_Unknown_Option,
G_Option_Error_Bad_Value,
G_Option_Error_Failed);
pragma Convention (C, GOption_Error);
-- Error codes returned by option parsing. 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);
pragma Convention (C, GOption_Arg);
-- 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: -- <option>-x arg</option>, with a long option: <option>--name arg</option> -- or combined in a single argument: <option>--name=arg</option>. type GOption_Flags is mod 2 ** Integer'Size;
pragma Convention (C, GOption_Flags);
-- Flags which modify individual options. G_Option_Flag_Hidden : constant GOption_Flags := 1;
G_Option_Flag_In_Main : constant GOption_Flags := 2;
G_Option_Flag_Reverse : constant GOption_Flags := 4;
G_Option_Flag_No_Arg : constant GOption_Flags := 8;
G_Option_Flag_Filename : constant GOption_Flags := 16;
G_Option_Flag_Optional_Arg : constant GOption_Flags := 32;
G_Option_Flag_Noalias : constant GOption_Flags := 64;
type GOption_Group is new Glib.C_Proxy;
function From_Object_Free (B : access GOption_Group) return GOption_Group;
pragma Inline (From_Object_Free);
-- A <structname>GOptionGroup</structname> 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 <structname>GOptionGroup</structname> holding -- their options, which the application can then add to its -- Glib.Option.Goption_Context. type GOption_Entry is record
Long_Name : Interfaces.C.Strings.chars_ptr;
Short_Name : Gchar; Flags : GOption_Flags; Arg : GOption_Arg; Arg_Data : System.Address;
Description : Interfaces.C.Strings.chars_ptr;
Arg_Description : Interfaces.C.Strings.chars_ptr;
end record;
pragma Convention (C, GOption_Entry);
function From_Object_Free (B : access GOption_Entry) return GOption_Entry;
pragma Inline (From_Object_Free);
-- A <structname>GOptionEntry</structname> 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;
--------------- -- Callbacks -- --------------- 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. -- "str": the untranslated string ---------------------------- -- Enumeration Properties -- ---------------------------- package GOption_Error_Properties is
new Generic_Internal_Discrete_Property (GOption_Error);
type Property_GOption_Error is new GOption_Error_Properties.Property;
package GOption_Arg_Properties is
new Generic_Internal_Discrete_Property (GOption_Arg);
type Property_GOption_Arg is new GOption_Arg_Properties.Property;
package GOption_Flags_Properties is
new Generic_Internal_Discrete_Property (GOption_Flags);
type Property_GOption_Flags is new GOption_Flags_Properties.Property;
------------- -- Methods -- ------------- 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 the group -- will be freed together with the context when Glib.Option.Free is called, -- so you must not free the group yourself after adding it to a context. -- Since: gtk+ 2.6 -- "group": 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 -- "entries": a null-terminated array of Glib.Option.GOption_Entry<!-- -- -->s -- "translation_domain": a translation domain to use for translating the -- <option>--help</option> 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 function Get_Description (Self : Goption_Context) return UTF8_String;
-- Returns the description. See Glib.Option.Set_Description. -- Since: gtk+ 2.12 procedure Set_Description
(Self : Goption_Context;
Description : UTF8_String := "");
-- Adds a string to be displayed in <option>--help</option> 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 -- "description": a string to be shown in <option>--help</option> output -- after the list of options, or null 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 <option>--help</option>, call -- 'g_option_context_get_help (context, TRUE, NULL)'. To obtain the text -- produced by <option>--help-all</option>, 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 -- "main_help": if True, only include the main group -- "group": the Glib.Option.GOption_Group to create help for, or null function Get_Help_Enabled (Self : Goption_Context) return Boolean;
-- Returns whether automatic <option>--help</option> generation is turned -- on for Context. See Glib.Option.Set_Help_Enabled. -- Since: gtk+ 2.6 procedure Set_Help_Enabled
(Self : Goption_Context;
Help_Enabled : Boolean);
-- Enables or disables automatic generation of <option>--help</option> -- output. By default, g_option_context_parse recognizes -- <option>--help</option>, <option>-h</option>, <option>-?</option>, -- <option>--help-all</option> and -- <option>--help-</option><replaceable>groupname</replaceable> and creates -- suitable output to stdout. -- Since: gtk+ 2.6 -- "help_enabled": True to enable <option>--help</option>, False to -- disable it 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 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 -- "ignore_unknown": True to ignore unknown options, False to produce an -- error when unknown options are met function Get_Main_Group (Self : Goption_Context) return GOption_Group;
-- Returns a pointer to the main group of Context. -- Since: gtk+ 2.6 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 <option>--help</option> output. -- Since: gtk+ 2.6 -- "group": the group to set as main group function Get_Summary (Self : Goption_Context) return UTF8_String;
-- Returns the summary. See Glib.Option.Set_Summary. -- Since: gtk+ 2.12 procedure Set_Summary
(Self : Goption_Context;
Summary : UTF8_String := "");
-- Adds a string to be displayed in <option>--help</option> 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 -- "summary": a string to be shown in <option>--help</option> 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 <option>--help</option> 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 -- "func": the Gtranslate_Func, or null -- "destroy_notify": a function which gets called to free Data, or null generic type User_Data_Type (<>) is private;
with procedure Destroy (Data : in out User_Data_Type) is null;
package Set_Translate_Func_User_Data is
type Gtranslate_Func is access function
(Str : UTF8_String; Data : User_Data_Type) return UTF8_String;
-- The type of functions which are used to translate user-visible strings, -- for <option>--help</option> output. -- "str": the untranslated string -- "data": user data specified when installing the function, e.g. in -- g_option_group_set_translate_func procedure Set_Translate_Func
(Self : Glib.Option.Goption_Context;
Func : Gtranslate_Func;
Data : User_Data_Type;
Destroy_Notify : Glib.G_Destroy_Notify_Address);
-- Sets the function which is used to translate the contexts -- user-visible strings, for <option>--help</option> 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 -- "func": the Gtranslate_Func, or null -- "data": user data to pass to Func, or null -- "destroy_notify": a function which gets called to free Data, or null end Set_Translate_Func_User_Data;
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 -- "domain": the domain to use ---------------------- -- GtkAda additions -- ---------------------- Null_GOption_Entry : constant GOption_Entry;
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 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. --------------- -- Functions -- --------------- 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 -- "parameter_string": a string which is displayed in the first line of -- <option>--help</option> output, after the usage summary -- '<replaceable>programname</replaceable> [OPTION...]' private Null_Goption_Context : constant Goption_Context := (Glib.C_Boxed with null record);
Null_GOption_Entry : constant GOption_Entry :=
(ICS.Null_Ptr, Gchar(ASCII.NUL), 0, G_Option_Arg_None, System.Null_Address,
ICS.Null_Ptr, ICS.Null_Ptr);
end Glib.Option;