1. ------------------------------------------------------------------------------ 
  2. --               GtkAda - Ada95 binding for the Gimp Toolkit                -- 
  3. --                                                                          -- 
  4. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  5. --                     Copyright (C) 1998-2014, AdaCore                     -- 
  6. --                                                                          -- 
  7. -- This library is free software;  you can redistribute it and/or modify it -- 
  8. -- under terms of the  GNU General Public License  as published by the Free -- 
  9. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  10. -- version. This library is distributed in the hope that it will be useful, -- 
  11. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  12. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  13. --                                                                          -- 
  14. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  15. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  16. -- version 3.1, as published by the Free Software Foundation.               -- 
  17. --                                                                          -- 
  18. -- You should have received a copy of the GNU General Public License and    -- 
  19. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  20. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  21. -- <http://www.gnu.org/licenses/>.                                          -- 
  22. --                                                                          -- 
  23. ------------------------------------------------------------------------------ 
  24.  
  25. --  <description> 
  26. -- 
  27. --  This package provides a simple minded XML parser to be used with 
  28. --  Gate. 
  29. -- 
  30. --  </description> 
  31. --  <group>Glib, the general-purpose library</group> 
  32.  
  33. with Unchecked_Deallocation; 
  34.  
  35. generic 
  36.    type XML_Specific_Data is private; 
  37.    --  The type of the extra data that can be attached to each node of the 
  38.    --  XML tree. See for instance the package Glib.Glade. 
  39.  
  40. package Glib.XML is 
  41.  
  42.    --  <doc_ignore> 
  43.    procedure Free is new Unchecked_Deallocation (String, String_Ptr); 
  44.    --  </doc_ignore> 
  45.  
  46.    type Node; 
  47.    type Node_Ptr is access all Node; 
  48.    --  Pointer to a node of the XML tree. 
  49.  
  50.    type Node is record 
  51.       Tag   : String_Ptr; 
  52.       --  The name of this node. This is utf8-encoded 
  53.  
  54.       Attributes   : String_Ptr; 
  55.       --  The attributes of this node. This is utf8-encoded 
  56.  
  57.       Value : String_Ptr; 
  58.       --  The value, or null is not relevant. This is utf8-encoded 
  59.  
  60.       Parent : Node_Ptr; 
  61.       --  The parent of this Node. 
  62.  
  63.       Child : Node_Ptr; 
  64.       --  The first Child of this Node. The next child is Child.Next 
  65.  
  66.       Next  : Node_Ptr; 
  67.       --  Next sibling node. 
  68.  
  69.       Specific_Data : XML_Specific_Data; 
  70.       --  Use to store data specific to each implementation (e.g a boolean 
  71.       --  indicating whether this node has been accessed) 
  72.    end record; 
  73.    --  A node of the XML tree. 
  74.    --  Each time a tag is found in the XML file, a new node is created, that 
  75.    --  points to its parent, its children and its siblings (nodes at the same 
  76.    --  level in the tree and with the same parent). 
  77.  
  78.    function Parse (File : String) return Node_Ptr; 
  79.    --  Parse File and return the first node representing the XML file. 
  80.  
  81.    function Parse_Buffer (Buffer : UTF8_String) return Node_Ptr; 
  82.    --  Parse a given Buffer in memory and return the first node representing 
  83.    --  the XML contents. 
  84.  
  85.    procedure Print (N : Node_Ptr; File_Name : String := ""); 
  86.    --  Write the tree starting with N into a file File_Name. The generated 
  87.    --  file is valid XML, and can be parsed with the Parse function. 
  88.    --  If File_Name is the empty string, then the tree is printed on the 
  89.    --  standard output 
  90.  
  91.    procedure Print 
  92.      (N         : Node_Ptr; 
  93.       File_Name : String; 
  94.       Success   : out Boolean); 
  95.    --  Same as above, with Success reporting the success of the operation. 
  96.  
  97.    function Protect (S : String) return String; 
  98.    --  Return a copy of S modified so that it is a valid XML value 
  99.  
  100.    function Find_Tag (N : Node_Ptr; Tag : UTF8_String) return Node_Ptr; 
  101.    --  Find a tag Tag in N and its brothers. 
  102.  
  103.    function Get_Field (N : Node_Ptr; Field : UTF8_String) return String_Ptr; 
  104.    --  Return the value of the field 'Field' if present in the children of N. 
  105.    --  Return null otherwise. 
  106.    --  Do not free the returned value. 
  107.  
  108.    function Is_Equal (Node1, Node2 : Node_Ptr) return Boolean; 
  109.    --  Compare two XML nodes recursively, and returns True if they are equal. 
  110.    --  Casing in attributes is relevant. Order of attributes is also 
  111.    --  relevant. 
  112.  
  113.    procedure Add_Child 
  114.      (N : Node_Ptr; Child : Node_Ptr; Append : Boolean := False); 
  115.    --  Add a new child to a node. 
  116.    --  If Append is true, the child is added at the end of the current list of 
  117.    --  children. 
  118.  
  119.    function Children_Count (N : Node_Ptr) return Natural; 
  120.    --  Return the number of child nodes 
  121.  
  122.    function Deep_Copy (N : Node_Ptr) return Node_Ptr; 
  123.    --  Return a deep copy of the tree starting with N. N can then be freed 
  124.    --  without affecting the copy. 
  125.  
  126.    type Free_Specific_Data is access 
  127.      procedure (Data : in out XML_Specific_Data); 
  128.  
  129.    procedure Free 
  130.      (N : in out Node_Ptr; Free_Data : Free_Specific_Data := null); 
  131.    --  Free the memory allocated for a node and its children. 
  132.    --  It also disconnects N from its parent. 
  133.    --  If Free_Data is not null, it is used to free the memory occupied by 
  134.    --  the Specific_Data for each node. 
  135.  
  136.    function Get_Attribute 
  137.      (N : in Node_Ptr; 
  138.       Attribute_Name : in UTF8_String; 
  139.       Default        : in UTF8_String := "") return UTF8_String; 
  140.    --  Return the value of the attribute 'Attribute_Name' if present. 
  141.    --  Special XML characters have already been interpreted in the result 
  142.    --  string. 
  143.    --  Return Default otherwise. 
  144.  
  145.    procedure Set_Attribute 
  146.      (N : Node_Ptr; Attribute_Name, Attribute_Value : UTF8_String); 
  147.    --  Create a new attribute, or replace an existing one. The attribute value 
  148.    --  is automatically protected for special XML characters 
  149.  
  150.    function Find_Tag_With_Attribute 
  151.      (N     : Node_Ptr; 
  152.       Tag   : UTF8_String; 
  153.       Key   : UTF8_String; 
  154.       Value : UTF8_String := "") 
  155.      return Node_Ptr; 
  156.    --  Find a tag Tag in N that has a given key (and value if given). 
  157.  
  158. end Glib.XML;