1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  A <structname>GOptionContext</structname> struct defines which options are 
  26. --  accepted by the commandline option parser. The struct has only private 
  27. --  fields and should not be directly accessed. 
  28. -- 
  29. --  </description> 
  30. pragma Ada_2005; 
  31.  
  32. pragma Warnings (Off, "*is already use-visible*"); 
  33. with Glib;                    use Glib; 
  34. with Glib.Application;        use Glib.Application; 
  35. with Glib.Error;              use Glib.Error; 
  36. with Glib.Generic_Properties; use Glib.Generic_Properties; 
  37. with Gtkada.Bindings;         use Gtkada.Bindings; 
  38. with Interfaces.C.Strings;    use Interfaces.C.Strings; 
  39.  
  40. package Glib.Option is 
  41.  
  42.    type Goption_Context is new Glib.C_Boxed with null record; 
  43.    Null_Goption_Context : constant Goption_Context; 
  44.  
  45.    function From_Object (Object : System.Address) return Goption_Context; 
  46.    function From_Object_Free (B : access Goption_Context'Class) return Goption_Context; 
  47.    pragma Inline (From_Object_Free, From_Object); 
  48.  
  49.    type GOption_Error is ( 
  50.       G_Option_Error_Unknown_Option, 
  51.       G_Option_Error_Bad_Value, 
  52.       G_Option_Error_Failed); 
  53.    pragma Convention (C, GOption_Error); 
  54.    --  Error codes returned by option parsing. 
  55.  
  56.    type GOption_Arg is ( 
  57.       G_Option_Arg_None, 
  58.       G_Option_Arg_String, 
  59.       G_Option_Arg_Int, 
  60.       G_Option_Arg_Callback, 
  61.       G_Option_Arg_Filename, 
  62.       G_Option_Arg_String_Array, 
  63.       G_Option_Arg_Filename_Array, 
  64.       G_Option_Arg_Double, 
  65.       G_Option_Arg_Int64); 
  66.    pragma Convention (C, GOption_Arg); 
  67.    --  The Glib.Option.GOption_Arg enum values determine which type of extra 
  68.    --  argument the options expect to find. If an option expects an extra 
  69.    --  argument, it can be specified in several ways; with a short option: 
  70.    --  <option>-x arg</option>, with a long option: <option>--name arg</option> 
  71.    --  or combined in a single argument: <option>--name=arg</option>. 
  72.  
  73.    type GOption_Flags is mod 2 ** Integer'Size; 
  74.    pragma Convention (C, GOption_Flags); 
  75.    --  Flags which modify individual options. 
  76.  
  77.    G_Option_Flag_Hidden : constant GOption_Flags := 1; 
  78.    G_Option_Flag_In_Main : constant GOption_Flags := 2; 
  79.    G_Option_Flag_Reverse : constant GOption_Flags := 4; 
  80.    G_Option_Flag_No_Arg : constant GOption_Flags := 8; 
  81.    G_Option_Flag_Filename : constant GOption_Flags := 16; 
  82.    G_Option_Flag_Optional_Arg : constant GOption_Flags := 32; 
  83.    G_Option_Flag_Noalias : constant GOption_Flags := 64; 
  84.  
  85.    type GOption_Group is new Glib.C_Proxy; 
  86.    function From_Object_Free (B : access GOption_Group) return GOption_Group; 
  87.    pragma Inline (From_Object_Free); 
  88.    --  A <structname>GOptionGroup</structname> struct defines the options in a 
  89.    --  single group. The struct has only private fields and should not be 
  90.    --  directly accessed. 
  91.    -- 
  92.    --  All options in a group share the same translation function. Libraries 
  93.    --  which need to parse commandline options are expected to provide a 
  94.    --  function for getting a <structname>GOptionGroup</structname> holding 
  95.    --  their options, which the application can then add to its 
  96.    --  Glib.Option.Goption_Context. 
  97.  
  98.    type GOption_Entry is record 
  99.       Long_Name : Interfaces.C.Strings.chars_ptr; 
  100.       Short_Name : Gchar; 
  101.       Flags : GOption_Flags; 
  102.       Arg : GOption_Arg; 
  103.       Arg_Data : System.Address; 
  104.       Description : Interfaces.C.Strings.chars_ptr; 
  105.       Arg_Description : Interfaces.C.Strings.chars_ptr; 
  106.    end record; 
  107.    pragma Convention (C, GOption_Entry); 
  108.  
  109.    function From_Object_Free (B : access GOption_Entry) return GOption_Entry; 
  110.    pragma Inline (From_Object_Free); 
  111.    --  A <structname>GOptionEntry</structname> defines a single option. To 
  112.    --  have an effect, they must be added to a Glib.Option.GOption_Group with 
  113.    --  Glib.Option.Add_Main_Entries or g_option_group_add_entries. 
  114.  
  115.    type GOption_Entry_Array is array (Natural range <>) of GOption_Entry; 
  116.  
  117.    --------------- 
  118.    -- Callbacks -- 
  119.    --------------- 
  120.  
  121.    type Gtranslate_Func is access function (Str : UTF8_String) return UTF8_String; 
  122.    --  The type of functions which are used to translate user-visible strings, 
  123.    --  for <option>--help</option> output. 
  124.    --  "str": the untranslated string 
  125.  
  126.    ---------------------------- 
  127.    -- Enumeration Properties -- 
  128.    ---------------------------- 
  129.  
  130.    package GOption_Error_Properties is 
  131.       new Generic_Internal_Discrete_Property (GOption_Error); 
  132.    type Property_GOption_Error is new GOption_Error_Properties.Property; 
  133.  
  134.    package GOption_Arg_Properties is 
  135.       new Generic_Internal_Discrete_Property (GOption_Arg); 
  136.    type Property_GOption_Arg is new GOption_Arg_Properties.Property; 
  137.  
  138.    package GOption_Flags_Properties is 
  139.       new Generic_Internal_Discrete_Property (GOption_Flags); 
  140.    type Property_GOption_Flags is new GOption_Flags_Properties.Property; 
  141.  
  142.    ------------- 
  143.    -- Methods -- 
  144.    ------------- 
  145.  
  146.    procedure Add_Group (Self : Goption_Context; Group : GOption_Group); 
  147.    --  Adds a Glib.Option.GOption_Group to the Context, so that parsing with 
  148.    --  Context will recognize the options in the group. Note that the group 
  149.    --  will be freed together with the context when Glib.Option.Free is called, 
  150.    --  so you must not free the group yourself after adding it to a context. 
  151.    --  Since: gtk+ 2.6 
  152.    --  "group": the group to add 
  153.  
  154.    procedure Add_Main_Entries 
  155.       (Self               : Goption_Context; 
  156.        Entries            : GOption_Entry_Array; 
  157.        Translation_Domain : UTF8_String := ""); 
  158.    --  A convenience function which creates a main group if it doesn't exist, 
  159.    --  adds the Entries to it and sets the translation domain. 
  160.    --  Since: gtk+ 2.6 
  161.    --  "entries": a null-terminated array of Glib.Option.GOption_Entry<!-- 
  162.    --  -->s 
  163.    --  "translation_domain": a translation domain to use for translating the 
  164.    --  <option>--help</option> output for the options in Entries with gettext, 
  165.    --  or null 
  166.  
  167.    procedure Free (Self : Goption_Context); 
  168.    --  Frees context and all the groups which have been added to it. 
  169.    --  Please note that parsed arguments need to be freed separately (see 
  170.    --  Glib.Option.GOption_Entry). 
  171.    --  Since: gtk+ 2.6 
  172.  
  173.    function Get_Description (Self : Goption_Context) return UTF8_String; 
  174.    --  Returns the description. See Glib.Option.Set_Description. 
  175.    --  Since: gtk+ 2.12 
  176.  
  177.    procedure Set_Description 
  178.       (Self        : Goption_Context; 
  179.        Description : UTF8_String := ""); 
  180.    --  Adds a string to be displayed in <option>--help</option> output after 
  181.    --  the list of options. This text often includes a bug reporting address. 
  182.    --  Note that the summary is translated (see 
  183.    --  Glib.Option.Set_Translate_Func). 
  184.    --  Since: gtk+ 2.12 
  185.    --  "description": a string to be shown in <option>--help</option> output 
  186.    --  after the list of options, or null 
  187.  
  188.    function Get_Help 
  189.       (Self      : Goption_Context; 
  190.        Main_Help : Boolean; 
  191.        Group     : GOption_Group) return UTF8_String; 
  192.    --  Returns a formatted, translated help text for the given context. To 
  193.    --  obtain the text produced by <option>--help</option>, call 
  194.    --  'g_option_context_get_help (context, TRUE, NULL)'. To obtain the text 
  195.    --  produced by <option>--help-all</option>, call 'g_option_context_get_help 
  196.    --  (context, FALSE, NULL)'. To obtain the help text for an option group, 
  197.    --  call 'g_option_context_get_help (context, FALSE, group)'. 
  198.    --  Since: gtk+ 2.14 
  199.    --  "main_help": if True, only include the main group 
  200.    --  "group": the Glib.Option.GOption_Group to create help for, or null 
  201.  
  202.    function Get_Help_Enabled (Self : Goption_Context) return Boolean; 
  203.    --  Returns whether automatic <option>--help</option> generation is turned 
  204.    --  on for Context. See Glib.Option.Set_Help_Enabled. 
  205.    --  Since: gtk+ 2.6 
  206.  
  207.    procedure Set_Help_Enabled 
  208.       (Self         : Goption_Context; 
  209.        Help_Enabled : Boolean); 
  210.    --  Enables or disables automatic generation of <option>--help</option> 
  211.    --  output. By default, g_option_context_parse recognizes 
  212.    --  <option>--help</option>, <option>-h</option>, <option>-?</option>, 
  213.    --  <option>--help-all</option> and 
  214.    --  <option>--help-</option><replaceable>groupname</replaceable> and creates 
  215.    --  suitable output to stdout. 
  216.    --  Since: gtk+ 2.6 
  217.    --  "help_enabled": True to enable <option>--help</option>, False to 
  218.    --  disable it 
  219.  
  220.    function Get_Ignore_Unknown_Options 
  221.       (Self : Goption_Context) return Boolean; 
  222.    --  Returns whether unknown options are ignored or not. See 
  223.    --  Glib.Option.Set_Ignore_Unknown_Options. 
  224.    --  Since: gtk+ 2.6 
  225.  
  226.    procedure Set_Ignore_Unknown_Options 
  227.       (Self           : Goption_Context; 
  228.        Ignore_Unknown : Boolean); 
  229.    --  Sets whether to ignore unknown options or not. If an argument is 
  230.    --  ignored, it is left in the Argv array after parsing. By default, 
  231.    --  g_option_context_parse treats unknown options as error. 
  232.    --  This setting does not affect non-option arguments (i.e. arguments which 
  233.    --  don't start with a dash). But note that GOption cannot reliably 
  234.    --  determine whether a non-option belongs to a preceding unknown option. 
  235.    --  Since: gtk+ 2.6 
  236.    --  "ignore_unknown": True to ignore unknown options, False to produce an 
  237.    --  error when unknown options are met 
  238.  
  239.    function Get_Main_Group (Self : Goption_Context) return GOption_Group; 
  240.    --  Returns a pointer to the main group of Context. 
  241.    --  Since: gtk+ 2.6 
  242.  
  243.    procedure Set_Main_Group (Self : Goption_Context; Group : GOption_Group); 
  244.    --  Sets a Glib.Option.GOption_Group as main group of the Context. This has 
  245.    --  the same effect as calling Glib.Option.Add_Group, the only difference is 
  246.    --  that the options in the main group are treated differently when 
  247.    --  generating <option>--help</option> output. 
  248.    --  Since: gtk+ 2.6 
  249.    --  "group": the group to set as main group 
  250.  
  251.    function Get_Summary (Self : Goption_Context) return UTF8_String; 
  252.    --  Returns the summary. See Glib.Option.Set_Summary. 
  253.    --  Since: gtk+ 2.12 
  254.  
  255.    procedure Set_Summary 
  256.       (Self    : Goption_Context; 
  257.        Summary : UTF8_String := ""); 
  258.    --  Adds a string to be displayed in <option>--help</option> output before 
  259.    --  the list of options. This is typically a summary of the program 
  260.    --  functionality. 
  261.    --  Note that the summary is translated (see Glib.Option.Set_Translate_Func 
  262.    --  and Glib.Option.Set_Translation_Domain). 
  263.    --  Since: gtk+ 2.12 
  264.    --  "summary": a string to be shown in <option>--help</option> output 
  265.    --  before the list of options, or null 
  266.  
  267.    procedure Set_Translate_Func 
  268.       (Self           : Goption_Context; 
  269.        Func           : Gtranslate_Func; 
  270.        Destroy_Notify : Glib.G_Destroy_Notify_Address); 
  271.    --  Sets the function which is used to translate the contexts user-visible 
  272.    --  strings, for <option>--help</option> output. If Func is null, strings 
  273.    --  are not translated. 
  274.    --  Note that option groups have their own translation functions, this 
  275.    --  function only affects the Parameter_String (see Glib.Option.G_New), the 
  276.    --  summary (see Glib.Option.Set_Summary) and the description (see 
  277.    --  Glib.Option.Set_Description). 
  278.    --  If you are using gettext, you only need to set the translation domain, 
  279.    --  see Glib.Option.Set_Translation_Domain. 
  280.    --  Since: gtk+ 2.12 
  281.    --  "func": the Gtranslate_Func, or null 
  282.    --  "destroy_notify": a function which gets called to free Data, or null 
  283.  
  284.    generic 
  285.       type User_Data_Type (<>) is private; 
  286.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  287.    package Set_Translate_Func_User_Data is 
  288.  
  289.       type Gtranslate_Func is access function 
  290.         (Str  : UTF8_String; 
  291.          Data : User_Data_Type) return UTF8_String; 
  292.       --  The type of functions which are used to translate user-visible strings, 
  293.       --  for <option>--help</option> output. 
  294.       --  "str": the untranslated string 
  295.       --  "data": user data specified when installing the function, e.g. in 
  296.       --  g_option_group_set_translate_func 
  297.  
  298.       procedure Set_Translate_Func 
  299.          (Self           : Glib.Option.Goption_Context; 
  300.           Func           : Gtranslate_Func; 
  301.           Data           : User_Data_Type; 
  302.           Destroy_Notify : Glib.G_Destroy_Notify_Address); 
  303.       --  Sets the function which is used to translate the contexts 
  304.       --  user-visible strings, for <option>--help</option> output. If Func is 
  305.       --  null, strings are not translated. 
  306.       --  Note that option groups have their own translation functions, this 
  307.       --  function only affects the Parameter_String (see Glib.Option.G_New), 
  308.       --  the summary (see Glib.Option.Set_Summary) and the description (see 
  309.       --  Glib.Option.Set_Description). 
  310.       --  If you are using gettext, you only need to set the translation 
  311.       --  domain, see Glib.Option.Set_Translation_Domain. 
  312.       --  Since: gtk+ 2.12 
  313.       --  "func": the Gtranslate_Func, or null 
  314.       --  "data": user data to pass to Func, or null 
  315.       --  "destroy_notify": a function which gets called to free Data, or null 
  316.  
  317.    end Set_Translate_Func_User_Data; 
  318.  
  319.    procedure Set_Translation_Domain 
  320.       (Self   : Goption_Context; 
  321.        Domain : UTF8_String); 
  322.    --  A convenience function to use gettext for translating user-visible 
  323.    --  strings. 
  324.    --  Since: gtk+ 2.12 
  325.    --  "domain": the domain to use 
  326.  
  327.    ---------------------- 
  328.    -- GtkAda additions -- 
  329.    ---------------------- 
  330.  
  331.    Null_GOption_Entry : constant GOption_Entry; 
  332.  
  333.    type Parse_Filter is access function (Param : String) return Boolean; 
  334.    --  Returns True if the parameter is to be passed from Command_Line to 
  335.    --  Goption_Context 
  336.  
  337.    procedure Parse 
  338.      (Self         : Goption_Context; 
  339.       Command_Line : not null access Glib.Application.Gapplication_Command_Line_Record'Class; 
  340.       Filter       : Parse_Filter := null; 
  341.       Success      : out Boolean; 
  342.       Error        : out Glib.Error.GError); 
  343.    --  Parses the arguments given via Command_Line, removing from the arguments 
  344.    --  list all parsed switches. 
  345.  
  346.    --------------- 
  347.    -- Functions -- 
  348.    --------------- 
  349.  
  350.    function G_New 
  351.       (Parameter_String : UTF8_String := "") return Goption_Context; 
  352.    --  Creates a new option context. 
  353.    --  The Parameter_String can serve multiple purposes. It can be used to add 
  354.    --  descriptions for "rest" arguments, which are not parsed by the 
  355.    --  Glib.Option.Goption_Context, typically something like "FILES" or "FILE1 
  356.    --  FILE2...". If you are using G_OPTION_REMAINING for collecting "rest" 
  357.    --  arguments, GLib handles this automatically by using the Arg_Description 
  358.    --  of the corresponding Glib.Option.GOption_Entry in the usage summary. 
  359.    --  Another usage is to give a short summary of the program functionality, 
  360.    --  like " - frob the strings", which will be displayed in the same line as 
  361.    --  the usage. For a longer description of the program functionality that 
  362.    --  should be displayed as a paragraph below the usage line, use 
  363.    --  Glib.Option.Set_Summary. 
  364.    --  Note that the Parameter_String is translated using the function set 
  365.    --  with Glib.Option.Set_Translate_Func, so it should normally be passed 
  366.    --  untranslated. 
  367.    --  Since: gtk+ 2.6 
  368.    --  "parameter_string": a string which is displayed in the first line of 
  369.    --  <option>--help</option> output, after the usage summary 
  370.    --  '<replaceable>programname</replaceable> [OPTION...]' 
  371.  
  372. private 
  373.  
  374.    Null_Goption_Context : constant Goption_Context := (Glib.C_Boxed with null record); 
  375.  
  376.  
  377.    Null_GOption_Entry : constant GOption_Entry := 
  378.                           (ICS.Null_Ptr, Gchar(ASCII.NUL), 
  379.                            0, G_Option_Arg_None, System.Null_Address, 
  380.                            ICS.Null_Ptr, ICS.Null_Ptr); 
  381.         
  382. end Glib.Option;