1------------------------------------------------------------------------------
2--                     XML/Ada - An XML suite for Ada95                     --
3--                                                                          --
4--                     Copyright (C) 2001-2017, 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
24package DOM.Core.Documents is
25
26   function Doc_Type (Doc : Document) return Document_Type;
27   --  Return the DTD associated with Doc.
28   --  This might return null if there is no such DTD.
29
30   function Implementation (Doc : Document) return DOM_Implementation;
31   --  Return the DOM_Implementation to which Doc belongs.
32
33   function Get_Element (Doc : Document) return Element;
34   --  Return the top-element of DOC
35
36   function Create_Element (Doc : Document; Tag_Name : DOM_String)
37      return Element;
38   --  Create a new element, and its default attributes.
39   --  See also Create_Element_NS
40   --  Invalid_Character_Err is raised if Tag_Name contains invalid
41   --  characters.
42
43   function Create_Element_NS
44     (Doc            : Document;
45      Namespace_URI  : DOM_String;
46      Qualified_Name : DOM_String) return Element;
47   function Create_Element_NS
48     (Doc            : Document;
49      Symbols        : Sax.Utils.Symbol_Table;
50      Namespace_URI  : Sax.Symbols.Symbol;
51      Prefix         : Sax.Symbols.Symbol;
52      Local_Name     : Sax.Symbols.Symbol) return Element;
53   --  Create a new element, and its default attributes.
54   --  Invalid_Character_Err is raised if Tag_Name contains invalid
55   --  characters.
56   --  Namespace_Err raised if Qualified_Name is incorrect.
57   --  The version with Symbols is more efficient.
58   --  Symbol_Table is the table in which the symbols were allocated, to ensure
59   --  they are valid while the document is in use.
60
61   function Create_Document_Fragment (Doc : Document) return Document_Fragment;
62   --  Create an empty document fragment
63
64   function Create_Text_Node (Doc : Document; Data : DOM_String)
65      return Text;
66   --  Create a text node given a specific string
67   function Create_Text_Node (Doc : Document; Data : DOM_String_Access)
68      return Text;
69   --  As above but with a pre-allocated Data which must not be freed
70
71   function Create_Comment (Doc : Document; Data : DOM_String)
72      return Comment;
73   --  Create a comment node given a specific string
74
75   function Create_Cdata_Section (Doc : Document; Data : DOM_String)
76      return Cdata_Section;
77   --  Create a Cdata section for a specific string
78   --  Not_Supported_Err is raised for HTML documents
79
80   function Create_Processing_Instruction
81     (Doc : Document; Target : DOM_String; Data : DOM_String)
82      return Processing_Instruction;
83   --  Create a processing instruction.
84   --  Invalid_Character_Err raised if Target is invalid.
85   --  Not_Supported_Err raised for HTML documents
86
87   function Create_Attribute (Doc : Document; Name : DOM_String)
88      return Attr;
89   --  Create a new attribute.
90   --  Use Set_Attribute to associate it with an element.
91   --  See Create_Attribute_NS to create an attribute with a namespace.
92   --  Invalid_Character_Err raised if Name is invalid
93
94   function Create_Attribute_NS
95     (Doc : Document;
96      Namespace_URI : DOM_String;
97      Qualified_Name : DOM_String) return Attr;
98   function Create_Attribute_NS
99     (Doc           : Document;
100      Symbols       : Sax.Utils.Symbol_Table;
101      Namespace_URI : Sax.Symbols.Symbol;
102      Prefix        : Sax.Symbols.Symbol;
103      Local_Name    : Sax.Symbols.Symbol) return Attr;
104   --  Create a new attribute.
105   --  Use Set_Attribute to associate it with an element.
106   --  Invalid_Character_Err raised if Name is invalid
107   --  Namespace_Err raised if Qualified_Name is incorrect.
108
109   function Create_Entity_Reference (Doc : Document; Name : DOM_String)
110      return Entity_Reference;
111   --  Create a new entity reference.
112   --  If the referenced entity is known, the child list of the entity
113   --  reference is made the same as that of the Entity.
114   --  Invalid_Character_Err raised if Target is invalid.
115   --  Not_Supported_Err raised for HTML documents
116
117   function Get_Elements_By_Tag_Name
118     (Doc : Document; Tag_Name : DOM_String := "*") return Node_List;
119   --  Returns a NodeList of all the Elements with a given tag name in the
120   --  order in which they would be encountered in a preorder traversal
121   --  of the Document tree.
122   --  The special case "*" matches all tags.
123   --  The returned list must be freed with DOM.Core.Free
124
125   function Get_Elements_By_Tag_Name_NS
126     (Doc : Document;
127      Namespace_URI : DOM_String := "*";
128      Local_Name : DOM_String := "*") return Node_List;
129   --  Returns a NodeList of all the matching Elements.
130   --  "*" matches all namespaces or all local names
131   --  The returned list must be freed with DOM.Core.Free
132
133   function Get_Element_By_Id
134     (Doc : Document; Element_Id : DOM_String) return Node;
135   --  Return the element whose id is Element_Id. The first matching element
136   --  is returned.
137   --  The DOM implementation must know which attributes are of type Id, or
138   --  null is returned.
139   --  For documents resulting from parsing an XML input source, this will only
140   --  work if the parser was configured with validation features on.
141   --  Otherwise, it will not know what attributes should be considered as ID,
142   --  and thus will not be able to retrieve them.
143
144   function Adopt_Node (Doc : Document; Source : Node) return Node;
145   --  Attempts to adopt a node from another document to this document. If
146   --  supported, it changes the Owner_Document of the source node, its
147   --  children, as well as the attached attribute nodes if there are any. If
148   --  the source node has a parent it is first removed from the child list of
149   --  its parent. This effectively allows moving a subtree from one document
150   --  to another (unlike Import_Node which create a copy of the source node
151   --  instead of moving it). When it fails, applications should use
152   --  Import_Node instead.
153   --
154   --  Note that if the adopted node is already part of this document (i.e. the
155   --  source and target document are the same), this method still has the
156   --  effect of removing the source node from the child list of its parent, if
157   --  any. The following list describes the specifics for each type of node.
158
159   function Import_Node
160      (Doc : Document; Imported_Node : Node; Deep : Boolean := True)
161      return Node;
162   --  Imports a copy of Import_Node into Doc.
163   --  It returns the imported node.
164   --  This behaves mostly as if there had been a merge of the two XML
165   --  files that contained the document and the imported node, but also takes
166   --  into account the possibly different DTDs.
167
168end DOM.Core.Documents;
169