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