1. ------------------------------------------------------------------------------ 
  2. --                  GtkAda - Ada95 binding for Gtk+/Gnome                   -- 
  3. --                                                                          -- 
  4. --                     Copyright (C) 2010-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. --  G_Key_File lets you parse, edit or create files containing groups of 
  26. --  key-value pairs, which we call key files for lack of a better name. Several 
  27. --  freedesktop.org specifications use key files now, e.g the Desktop Entry 
  28. --  Specification and the Icon Theme Specification. 
  29. -- 
  30. --  The syntax of key files is described in detail in the Desktop Entry 
  31. --  Specification, here is a quick summary: Key files consists of groups of 
  32. --  key-value pairs, interspersed with comments. 
  33. -- 
  34. --       # this is just an example 
  35. --       # there can be comments before the first group 
  36. --       [First Group] 
  37. --       Name=Key File Example\tthis value shows\nescaping 
  38. --       # localized strings are stored in multiple key-value pairs 
  39. --       Welcome=Hello 
  40. --       Welcome[de]=Hallo 
  41. --       Welcome[fr_FR]=Bonjour 
  42. --       Welcome[it]=Ciao 
  43. --       Welcome[be@latin]=Hello 
  44. --       [Another Group] 
  45. --       Numbers=2;20;-200;0 
  46. --       Booleans=true;false;true;true 
  47. -- 
  48. --  Groups are started by a header line containing the group name enclosed in 
  49. --  '[' and ']', and ended implicitly by the start of the next group or the end 
  50. --  of the file. Each key-value pair must be contained in a group. 
  51. -- 
  52. --  Key-value pairs generally have the form key=value, with the exception of 
  53. --  localized strings, which have the form key[locale]=value, with a locale 
  54. --  identifier of the form lang_COUNTRYMODIFIER where COUNTRY and MODIFIER are 
  55. --  optional. Space before and after the '=' character are ignored. Newline, 
  56. --  tab, carriage return and backslash characters in value are escaped as \n, 
  57. --  \t, \r, and \\, respectively. To preserve leading spaces in values, these 
  58. --  can also be escaped as \s. 
  59. -- 
  60. --  Key files can store strings (possibly with localized variants), integers, 
  61. --  booleans and lists of these. Lists are separated by a separator character, 
  62. --  typically ';' or ','. To use the list separator character in a value in a 
  63. --  list, it has to be escaped by prefixing it with a backslash. 
  64. -- 
  65. --  This syntax is obviously inspired by the .ini files commonly met on 
  66. --  Windows, but there are some important differences: 
  67. -- 
  68. --  .ini files use the ';' character to begin comments, key files use the '#' 
  69. --  character. 
  70. -- 
  71. --  Key files do not allow for ungrouped keys meaning only comments can 
  72. --  precede the first group. 
  73. -- 
  74. --  Key files are always encoded in UTF-8. 
  75. -- 
  76. --  Key and Group names are case-sensitive, for example a group called [GROUP] 
  77. --  is a different group from [group]. 
  78. -- 
  79. --  .ini files don't have a strongly typed boolean entry type, they only have 
  80. --  GetProfileInt. In G_Key_File only true and false (in lower case) are 
  81. --  allowed. 
  82. -- 
  83. --  Note that in contrast to the Desktop Entry Specification, groups in key 
  84. --  files may contain the same key multiple times; the last entry wins. Key 
  85. --  files may also contain multiple groups with the same name; they are merged 
  86. --  together. Another difference is that keys and group names in key files are 
  87. --  not restricted to ASCII characters. 
  88. --  </description> 
  89. --  <c_version>2.16.6</c_version> 
  90.  
  91. with GNAT.Strings; 
  92.  
  93. with Glib.Error; 
  94.  
  95. package Glib.Key_File is 
  96.  
  97.    type G_Key_File is new Glib.C_Proxy; 
  98.  
  99.    type G_Key_File_Error is 
  100.      (Error_Unknown_Encoding, 
  101.       Error_Parse, 
  102.       Error_Not_Found, 
  103.       Error_Key_Not_Found, 
  104.       Error_Group_Not_Found, 
  105.       Error_Invalid_Value); 
  106.    pragma Convention (C, G_Key_File_Error); 
  107.  
  108.    type G_Key_File_Flags is (None, Keep_Comments, Keep_Translations); 
  109.    pragma Convention (C, G_Key_File_Flags); 
  110.  
  111.    --  Constants for handling freedesktop.org Desktop files 
  112.    Desktop_Group                : constant String := "Desktop Entry"; 
  113.  
  114.    Desktop_Key_Type             : constant String := "Type"; 
  115.    Desktop_Key_Version          : constant String := "Version"; 
  116.    Desktop_Key_Name             : constant String := "Name"; 
  117.    Desktop_Key_Generic_Name     : constant String := "GenericName"; 
  118.    Desktop_Key_No_Display       : constant String := "NoDisplay"; 
  119.    Desktop_Key_Comment          : constant String := "Comment"; 
  120.    Desktop_Key_Icon             : constant String := "Icon"; 
  121.    Desktop_Key_Hidden           : constant String := "Hidden"; 
  122.    Desktop_Key_Only_Show_In     : constant String := "OnlyShowIn"; 
  123.    Desktop_Key_Not_Show_In      : constant String := "NotShowIn"; 
  124.    Desktop_Key_Try_Exec         : constant String := "TryExec"; 
  125.    Desktop_Key_Exec             : constant String := "Exec"; 
  126.    Desktop_Key_Path             : constant String := "Path"; 
  127.    Desktop_Key_Terminal         : constant String := "Terminal"; 
  128.    Desktop_Key_Mime_Type        : constant String := "MimeType"; 
  129.    Desktop_Key_Categories       : constant String := "Categories"; 
  130.    Desktop_Key_Startup_Notify   : constant String := "StartupNotify"; 
  131.    Desktop_Key_Startup_Wm_Class : constant String := "StartupWMClass"; 
  132.    Desktop_Key_Url              : constant String := "URL"; 
  133.  
  134.    Desktop_Type_Application     : constant String := "Application"; 
  135.    Desktop_Type_Link            : constant String := "Link"; 
  136.    Desktop_Type_Directory       : constant String := "Directory"; 
  137.  
  138.    function Error_Quark return GQuark; 
  139.  
  140.    procedure Gtk_New (Key_File : out G_Key_File); 
  141.    --  Creates a new empty G_Key_File object. Use Load_From_File, 
  142.    --  Load_From_Data, Load_From_Dirs or Load_From_Data_Dirs to read an 
  143.    --  existing key file. 
  144.  
  145.    procedure Free (Key_File : in out G_Key_File); 
  146.    --  Frees a G_Key_File. 
  147.  
  148.    procedure Set_List_Separator 
  149.      (Key_File  : G_Key_File; 
  150.       Separator : Gchar); 
  151.    --  Sets the character which is used to separate 
  152.    --  values in lists. Typically ';' or ',' are used 
  153.    --  as separators. The default list separator is ';'. 
  154.  
  155.    function To_Data (Key_File : G_Key_File) return String; 
  156.    --  Output Key_File as a String. 
  157.  
  158.    ------------ 
  159.    -- Groups -- 
  160.    ------------ 
  161.  
  162.    function Get_Start_Group (Key_File : G_Key_File) return String; 
  163.    --  Returns the name of the start group of the file. 
  164.  
  165.    function Get_Groups (Key_File : G_Key_File) return GNAT.Strings.String_List; 
  166.    --  Returns all groups in the key file loaded with Key_File. 
  167.  
  168.    function Has_Group 
  169.      (Key_File   : G_Key_File; 
  170.       Group_Name : String) 
  171.       return Boolean; 
  172.    --  Looks whether the key file has the group Group_Name. 
  173.  
  174.    function Remove_Group 
  175.      (Key_File   : G_Key_File; 
  176.       Group_Name : String; 
  177.       Error      : Glib.Error.GError := null) 
  178.       return Boolean; 
  179.    --  Removes the specified group, Group_Name, from the key file. 
  180.    --  Returns True if the group was removed, False otherwise. 
  181.  
  182.    ---------- 
  183.    -- Keys -- 
  184.    ---------- 
  185.  
  186.    function Get_Keys 
  187.      (Key_File   : G_Key_File; 
  188.       Group_Name : String; 
  189.       Error      : Glib.Error.GError := null) 
  190.       return GNAT.Strings.String_List; 
  191.    --  Returns all keys for the group name Group_Name.  In the event that the 
  192.    --  Group_Name cannot be found, an empty list is returned and Error is set 
  193.    --  to Error_Group_Not_Found. 
  194.  
  195.    function Has_Key 
  196.      (Key_File   : G_Key_File; 
  197.       Group_Name : String; 
  198.       Key        : String; 
  199.       Error      : Glib.Error.GError := null) 
  200.       return Boolean; 
  201.    --  Looks whether the key file has the key Key in the group Group_Name. 
  202.  
  203.    function Remove_Key 
  204.      (Key_File   : G_Key_File; 
  205.       Group_Name : String; 
  206.       Key        : String; 
  207.       Error      : Glib.Error.GError := null) 
  208.       return Boolean; 
  209.    --  Removes Key in Group_Name from the key file. 
  210.    --  Returns True if the key was removed, False otherwise. 
  211.  
  212.    -------------- 
  213.    -- Comments -- 
  214.    -------------- 
  215.  
  216.    function Get_Comment 
  217.      (Key_File   : G_Key_File; 
  218.       Group_Name : String; 
  219.       Key        : String; 
  220.       Error      : Glib.Error.GError := null) 
  221.       return String; 
  222.    function Set_Comment 
  223.      (Key_File   : G_Key_File; 
  224.       Group_Name : String := ""; 
  225.       Key        : String := ""; 
  226.       Comment    : String; 
  227.       Error      : Glib.Error.GError := null) 
  228.       return Boolean; 
  229.    function Remove_Comment 
  230.      (Key_File   : G_Key_File; 
  231.       Group_Name : String := ""; 
  232.       Key        : String := ""; 
  233.       Error      : Glib.Error.GError := null) 
  234.       return Boolean; 
  235.    --  Places a comment above Key from Group_Name. 
  236.    --  If Key is null then Comment will be removed/written above Group_Name. 
  237.    --  If both Key and Group_Name are null, then Comment will be 
  238.    --  removed/written above the first group in the file. 
  239.    -- 
  240.    --  Returns whether the operation was successful. 
  241.  
  242.    ------------- 
  243.    -- Boolean -- 
  244.    ------------- 
  245.  
  246.    function Get_Boolean 
  247.      (Key_File   : G_Key_File; 
  248.       Group_Name : String; 
  249.       Key        : String; 
  250.       Error      : Glib.Error.GError := null) 
  251.       return Boolean; 
  252.    procedure Set_Boolean 
  253.      (Key_File   : G_Key_File; 
  254.       Group_Name : String := ""; 
  255.       Key        : String; 
  256.       Value      : Boolean); 
  257.    --  Association of a boolean value with Key under Group_Name. 
  258.    -- 
  259.    --  Set_Boolean creates a key if Key cannot be found. 
  260.    -- 
  261.    --  Get_Boolean returns the value associated with Key under Group_Name as a 
  262.    --  boolean.  If Key cannot be found then False is returned and error is set 
  263.    --  to Error_Not_Found. Likewise, if the value associated with Key cannot be 
  264.    --  interpreted as a boolean then False is returned and error is set to 
  265.    --  Error_Invalid_Value. 
  266.  
  267.    type Boolean_List is array (Integer range <>) of Boolean; 
  268.  
  269.    function Get_Boolean_List 
  270.      (Key_File   : G_Key_File; 
  271.       Group_Name : String; 
  272.       Key        : String; 
  273.       Error      : Glib.Error.GError := null) 
  274.       return Boolean_List; 
  275.    procedure Set_Boolean_List 
  276.      (Key_File   : G_Key_File; 
  277.       Group_Name : String := ""; 
  278.       Key        : String; 
  279.       List       : Boolean_List); 
  280.    --  Associates a list of boolean values with Key under Group_Name. 
  281.    --  If Key cannot be found then it is created. 
  282.    --  If Group_Name is "", the start_group is used. 
  283.  
  284.    ---------------------- 
  285.    -- Gdouble (Double) -- 
  286.    ---------------------- 
  287.  
  288.    function Get_Double 
  289.      (Key_File   : G_Key_File; 
  290.       Group_Name : String; 
  291.       Key        : String; 
  292.       Error      : Glib.Error.GError := null) 
  293.       return Gdouble; 
  294.    procedure Set_Double 
  295.      (Key_File   : G_Key_File; 
  296.       Group_Name : String := ""; 
  297.       Key        : String; 
  298.       Value      : Gdouble); 
  299.    --  Association of a double value with Key under Group_Name. 
  300.    -- 
  301.    --  Set_Double creates a key if Key cannot be found. 
  302.    -- 
  303.    --  Get_Double returns the value associated with Key under Group_Name as a 
  304.    --  double. If Group_Name is "", the start_group is used. 
  305.    -- 
  306.    --  If Key cannot be found then 0.0 is returned and error is set to 
  307.    --  Error_Key_Not_Found. Likewise, if the value associated 
  308.    --  with Key cannot be interpreted as a double then 0.0 is returned 
  309.    --  and error is set to Error_Invalid_Value. 
  310.  
  311.    type Double_List is array (Integer range <>) of Gdouble; 
  312.    pragma Convention (C, Double_List); 
  313.  
  314.    function Get_Double_List 
  315.      (Key_File   : G_Key_File; 
  316.       Group_Name : String; 
  317.       Key        : String; 
  318.       Error      : Glib.Error.GError := null) 
  319.       return Double_List; 
  320.    procedure Set_Double_List 
  321.      (Key_File   : G_Key_File; 
  322.       Group_Name : String := ""; 
  323.       Key        : String; 
  324.       List       : Double_List); 
  325.    --  Associates a list of double values with Key under 
  326.    --  Group_Name.  If Key cannot be found then it is created. 
  327.  
  328.    -------------------- 
  329.    -- Gint (Integer) -- 
  330.    -------------------- 
  331.  
  332.    function Get_Integer 
  333.      (Key_File   : G_Key_File; 
  334.       Group_Name : String; 
  335.       Key        : String; 
  336.       Error      : Glib.Error.GError := null) 
  337.       return Gint; 
  338.    procedure Set_Integer 
  339.      (Key_File   : G_Key_File; 
  340.       Group_Name : String := ""; 
  341.       Key        : String; 
  342.       Value      : Gint); 
  343.    --  Association of an integer value with Key under Group_Name. 
  344.    -- 
  345.    --  Set_Integer creates a key if Key cannot be found. 
  346.    -- 
  347.    --  If Get_Integer cannot find Key then 0 is returned and Error is set to 
  348.    --  Error_Key_Not_Found. Likewise, if the value associated 
  349.    --  with Key cannot be interpreted as an integer then 0 is returned 
  350.    --  and error is set to Error_Invalid_Value. 
  351.  
  352.    type Integer_List is array (Integer range <>) of Gint; 
  353.    pragma Convention (C, Integer_List); 
  354.  
  355.    function Get_Integer_List 
  356.      (Key_File   : G_Key_File; 
  357.       Group_Name : String; 
  358.       Key        : String; 
  359.       Error      : Glib.Error.GError := null) 
  360.       return Integer_List; 
  361.    procedure Set_Integer_List 
  362.      (Key_File   : G_Key_File; 
  363.       Group_Name : String := ""; 
  364.       Key        : String; 
  365.       List       : Integer_List); 
  366.    --  Associates a list of integer values with Key under Group_Name. 
  367.    --  If Key cannot be found then it is created. 
  368.  
  369.    ------------ 
  370.    -- String -- 
  371.    ------------ 
  372.  
  373.    function Get_String 
  374.      (Key_File   : G_Key_File; 
  375.       Group_Name : String; 
  376.       Key        : String; 
  377.       Error      : Glib.Error.GError := null) 
  378.       return String; 
  379.    procedure Set_String 
  380.      (Key_File   : G_Key_File; 
  381.       Group_Name : String := ""; 
  382.       Key        : String; 
  383.       The_String : String); 
  384.    --  Associates a new string value with Key under Group_Name. 
  385.    --  If Key cannot be found then it is created. 
  386.    --  If Group_Name cannot be found then it is created. 
  387.    --  Unlike Set_Value, this function handles characters 
  388.    --  that need escaping, such as newlines. 
  389.  
  390.    function Get_String_List 
  391.      (Key_File   : G_Key_File; 
  392.       Group_Name : String; 
  393.       Key        : String; 
  394.       Error      : Glib.Error.GError := null) 
  395.       return GNAT.Strings.String_List; 
  396.    procedure Set_String_List 
  397.      (Key_File   : G_Key_File; 
  398.       Group_Name : String := ""; 
  399.       Key        : String; 
  400.       List       : GNAT.Strings.String_List); 
  401.    --  Associates a list of string values for Key under Group_Name. 
  402.    --  If Key cannot be found then it is created. 
  403.    --  If Group_Name cannot be found then it is created. 
  404.  
  405.    ----------- 
  406.    -- Value -- 
  407.    ----------- 
  408.  
  409.    function Get_Value 
  410.      (Key_File   : G_Key_File; 
  411.       Group_Name : String; 
  412.       Key        : String; 
  413.       Error      : Glib.Error.GError := null) 
  414.       return String; 
  415.    procedure Set_Value 
  416.      (Key_File   : G_Key_File; 
  417.       Group_Name : String := ""; 
  418.       Key        : String; 
  419.       Value      : String); 
  420.    --  Associates a new value with Key under Group_Name. 
  421.    -- 
  422.    --  If Key cannot be found then it is created. If Group_Name cannot 
  423.    --  be found then it is created. To set an UTF-8 string which may contain 
  424.    --  characters that need escaping (such as newlines or spaces), use 
  425.    --  Set_String. 
  426.  
  427.    ------------- 
  428.    -- Loading -- 
  429.    ------------- 
  430.  
  431.    function Load_From_Data 
  432.      (Key_File : G_Key_File; 
  433.       Data     : String; 
  434.       Flags    : G_Key_File_Flags; 
  435.       Error    : Glib.Error.GError := null) 
  436.       return Boolean; 
  437.    --  Loads Data (which holds the contents of a key file) into an empty 
  438.    --  G_Key_File structure.  If the object cannot be created then Error 
  439.    --  is set to a G_Key_File_Error. 
  440.    -- 
  441.    --  Returns True if a key file could be loaded, False otherwise 
  442.  
  443.    function Load_From_Data_Dirs 
  444.      (Key_File : G_Key_File; 
  445.       File     : String; 
  446.       Flags    : G_Key_File_Flags; 
  447.       Error    : Glib.Error.GError := null) 
  448.       return Boolean; 
  449.    --  This function looks for a key file named File in the paths 
  450.    --  returned from g_get_user_data_dir() and g_get_system_data_dirs() 
  451.    --  and loads the file into Key_File.  If the file could not be loaded 
  452.    --  then Error is set to either a G_File_Error or G_Key_File_Error. 
  453.    -- 
  454.    --  Returns True if a key file could be loaded, False otherwise 
  455.  
  456.    function Load_From_Dirs 
  457.      (Key_File    : G_Key_File; 
  458.       File        : String; 
  459.       Search_Dirs : GNAT.Strings.String_List; 
  460.       Flags       : G_Key_File_Flags; 
  461.       Error       : Glib.Error.GError := null) 
  462.       return Boolean; 
  463.    --  This function looks for a key file named File in the paths specified 
  464.    --  in Search_Dirs and loads the file into Key_File.  If the file could not 
  465.    --  be loaded then an Error is set to either a G_File_Error or 
  466.    --  G_Key_File_Error. 
  467.    -- 
  468.    --  Returns True if a key file could be loaded, False otherwise 
  469.  
  470.    function Load_From_File 
  471.      (Key_File : G_Key_File; 
  472.       File     : String; 
  473.       Flags    : G_Key_File_Flags; 
  474.       Error    : Glib.Error.GError := null) 
  475.       return Boolean; 
  476.    --  Loads a key file into an empty G_Key_File structure. 
  477.    --  If the file could not be loaded then Error is set to 
  478.    --  either a G_File_Error or G_Key_File_Error. 
  479.    -- 
  480.    --  Returns True if a key file could be loaded, False otherwise 
  481.  
  482.    ------------- 
  483.    -- Locales -- 
  484.    ------------- 
  485.  
  486.    function Get_Locale_String 
  487.      (Key_File   : G_Key_File; 
  488.       Group_Name : String; 
  489.       Key        : String; 
  490.       Locale     : String) 
  491.       return String; 
  492.    procedure Set_Locale_String 
  493.      (Key_File   : G_Key_File; 
  494.       Group_Name : String := ""; 
  495.       Key        : String; 
  496.       Locale     : String; 
  497.       The_String : String); 
  498.    --  Associates a string value for Key and Locale under Group_Name. 
  499.    --  If the translation for Key cannot be found then it is created. 
  500.  
  501.    function Get_Locale_String_List 
  502.      (Key_File   : G_Key_File; 
  503.       Group_Name : String; 
  504.       Key        : String; 
  505.       Locale     : String; 
  506.       Error      : Glib.Error.GError := null) 
  507.       return GNAT.Strings.String_List; 
  508.    procedure Set_Locale_String_List 
  509.      (Key_File   : G_Key_File; 
  510.       Group_Name : String := ""; 
  511.       Key        : String; 
  512.       Locale     : String; 
  513.       List       : GNAT.Strings.String_List); 
  514.    --  Associates a list of string values for Key and Locale under 
  515.    --  Group_Name.  If the translation for Key cannot be found then 
  516.    --  it is created. 
  517.  
  518. private 
  519.  
  520.    pragma Import (C, Error_Quark, "g_key_file_error_quark"); 
  521.    pragma Import (C, Free, "g_key_file_free"); 
  522.    pragma Import (C, Set_List_Separator, "g_key_file_set_list_separator"); 
  523.  
  524. end Glib.Key_File;