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