## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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-2007, 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.     -----------------------------------------------------------------------

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>

38.     with Unchecked_Deallocation;

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.

45.     package Glib.XMLTo API docTo specTo body is

47.        --  <doc_ignore>

48.        procedure Free is new Unchecked_Deallocation (String, String_PtrTo API docTo spec);

49.        --  </doc_ignore>

51.        type NodeTo API docTo body;

52.        type Node_Ptr is access all NodeTo API docTo specTo body;

53.        --  Pointer to a node of the XML tree.

55.        type NodeTo API docTo spec is record

56.           Tag   : String_PtrTo API docTo spec;

57.           --  The name of this node. This is utf8-encoded

59.           Attributes   : String_PtrTo API docTo spec;

60.           --  The attributes of this node. This is utf8-encoded

62.           Value : String_PtrTo API docTo spec;

63.           --  The value, or null is not relevant. This is utf8-encoded

65.           Parent : Node_PtrTo API docTo spec;

66.           --  The parent of this Node.

68.           Child : Node_PtrTo API docTo spec;

69.           --  The first Child of this Node. The next child is Child.Next

71.           Next  : Node_PtrTo API docTo spec;

72.           --  Next sibling node.

74.           Specific_Data : XML_Specific_DataTo API docTo spec;

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).

83.        function ParseTo API docTo body (File : String) return Node_PtrTo API docTo spec;

84.        --  Parse File and return the first node representing the XML file.

86.        function Parse_BufferTo API docTo body (Buffer : UTF8_StringTo API docTo spec) return Node_PtrTo API docTo spec;

87.        --  Parse a given Buffer in memory and return the first node representing

88.        --  the XML contents.

90.        procedure PrintTo API docTo body (N : Node_PtrTo API docTo spec; 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

96.        procedure PrintTo API docTo body

97.          (N         : Node_PtrTo API docTo spec;

98.           File_Name : String;

99.           Success   : out Boolean);

100.        --  Same as above, with Success reporting the success of the operation.

102.        function ProtectTo API docTo body (S : String) return String;

103.        --  Return a copy of S modified so that it is a valid XML value

105.        function Find_TagTo API docTo body (N : Node_PtrTo API docTo spec; Tag : UTF8_StringTo API docTo spec) return Node_PtrTo API docTo spec;

106.        --  Find a tag Tag in N and its brothers.

108.        function Get_FieldTo API docTo body (N : Node_PtrTo API docTo spec; Field : UTF8_StringTo API docTo spec) return String_PtrTo API docTo spec;

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.

113.        function Is_EqualTo API docTo body (Node1, Node2 : Node_PtrTo API docTo spec) 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.

118.        procedure Add_ChildTo API docTo body

119.          (N : Node_PtrTo API docTo spec; Child : Node_PtrTo API docTo spec; 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.

124.        function Children_CountTo API docTo body (N : Node_PtrTo API docTo spec) return Natural;

125.        --  Return the number of child nodes

127.        function Deep_CopyTo API docTo body (N : Node_PtrTo API docTo spec) return Node_PtrTo API docTo spec;

128.        --  Return a deep copy of the tree starting with N. N can then be freed

129.        --  without affecting the copy.

131.        type Free_Specific_Data is access

132.          procedure (Data : in out XML_Specific_DataTo API docTo spec);

134.        procedure FreeTo API docTo body

135.          (N : in out Node_PtrTo API docTo spec; Free_Data : Free_Specific_DataTo API docTo spec := 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.

141.        function Get_AttributeTo API docTo body

142.          (N : in Node_PtrTo API docTo spec;

143.           Attribute_Name : in UTF8_StringTo API docTo spec;

144.           Default        : in UTF8_StringTo API docTo spec := "") return UTF8_StringTo API docTo spec;

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.

150.        procedure Set_AttributeTo API docTo body

151.          (N : Node_PtrTo API docTo spec; Attribute_Name, Attribute_Value : UTF8_StringTo API docTo spec);

152.        --  Create a new attribute, or replace an existing one. The attribute value

153.        --  is automatically protected for special XML characters

155.        function Find_Tag_With_AttributeTo API docTo body

156.          (N     : Node_PtrTo API docTo spec;

157.           Tag   : UTF8_StringTo API docTo spec;

158.           Key   : UTF8_StringTo API docTo spec;

159.           Value : UTF8_StringTo API docTo spec := "")

160.          return Node_PtrTo API docTo spec;

161.        --  Find a tag Tag in N that has a given key (and value if given).

163.     end Glib.XMLTo API docTo specTo body;