File : dom-core-nodes.ads


-----------------------------------------------------------------------

--                XML/Ada - An XML suite for Ada95                   --

--                                                                   --

--                       Copyright (C) 2001                          --

--                            ACT-Europe                             --

--                       Author: Emmanuel Briot                      --

--                                                                   --

-- This library is free software; you can redistribute it and/or     --

-- modify it under the terms of the GNU General Public               --

-- License as published by the Free Software Foundation; either      --

-- version 2 of the License, or (at your option) any later version.  --

--                                                                   --

-- This library is distributed in the hope that it will be useful,   --

-- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

-- General Public License for more details.                          --

--                                                                   --

-- You should have received a copy of the GNU General Public         --

-- License along with this library; if not, write to the             --

-- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

-- Boston, MA 02111-1307, USA.                                       --

--                                                                   --

-- As a special exception, if other files instantiate generics from  --

-- this unit, or you link this unit with other files to produce an   --

-- executable, this  unit  does not  by itself cause  the resulting  --

-- executable to be covered by the GNU General Public License. This  --

-- exception does not however invalidate any other reasons why the   --

-- executable file  might be covered by the  GNU Public License.     --

-----------------------------------------------------------------------


package DOM.Core.Nodes is

   ----------

   -- Node --

   ----------


   function Node_Name (N : Node) return DOM_String;
   --  Return the name of the tag.

   --  Its meaning depends on the type of the node, see the DOM specifications.


   function Node_Value (N : Node) return DOM_String;
   --  Return the value of the node.

   --  Its meaning depends on the type of the node, see the DOM specifications.


   procedure Set_Node_Value (N : Node; Value : DOM_String);
   --  Change the value of the node.

   --  No_Modification_Allowed_Err is raised when Node is read-only.


   function Child_Nodes (N : Node) return Node_List;
   --  Return the list of children for this node. This could be empty depending

   --  on the type of the node.


   function First_Child (N : Node) return Node;
   --  Return the first child of N.


   function Last_Child (N : Node) return Node;
   --  Return the last child of N.


   function Parent_Node (N : Node) return Node;
   --  Return the parent for this node. Note that for attribute nodes, this

   --  is always null


   function Previous_Sibling (N : Node) return Node;
   --  Return the node preceding N in their common parent.

   --  null is returned if there is no such node.

   --  Note that it is much more efficient to get the list of all children

   --  from the parent and use Item on the list to get each one of them.


   function Next_Sibling (N : Node) return Node;
   --  Return the node following N in their common parent.

   --  null is returned if there is no such node.


   function Attributes (N : Node) return Named_Node_Map;
   --  Return the list of attributes for N.

   --  null is returned, except for Element nodes.


   function Owner_Document (N : Node) return Node;
   --  Return the document to which N belongs.


   function Namespace_URI (N : Node) return DOM_String;
   --  Return the URI associated with N.

   --  This is the URI used when the node was created, and is independent from

   --  the prefix (see below).


   function Prefix (N : Node) return DOM_String;
   --  Return the prefix associated with N (first part of the qualified name)


   procedure Set_Prefix (N : Node; Prefix : DOM_String);
   --  Changing this prefix will affect the qualified name.


   function Local_Name (N : Node) return DOM_String;
   --  Return the local name of N (second part of the qualified name). This is

   --  null if the node was created with a DOM level 1 method (no namespace at

   --  creation time).


   function Insert_Before
     (N         : Node;
      New_Child : Node;
      Ref_Child : Node := null) return Node;
   --  Insert New_Child just before Ref_Child in the list of children for N.

   --  If Ref_Child is null, New_Child is inserted at the end.

   --  If New_Child is a document_fragment, all of its children are inserted.

   --  If New_Child is already in the tree, it is first removed.

   --  raises:

   --    * Hierarchy_Request_Err: N doesn't allow a child of this type, or

   --      New_Child is already an ancestor of N.

   --    * Wrong_Document_Err: if New_Child was created from another document

   --    * No_Modification_Allowed_Err: N or New_Child is read-only.

   --    * Not_Found_Err: Ref_Child is not a child of N.


   function Replace_Child
     (N         : Node;
      New_Child : Node;
      Old_Child : Node) return Node;
   --  Replace Old_Child with New_Child in the list of children of N.

   --  If New_Child is a document fragment, all its children are inserted in

   --  place of Old_Child. Returns the replaced node.

   --  raises:

   --    * Hierarchy_Request_Err: N doesn't allow a child of this type, or

   --      New_Child is already an ancestor of N.

   --    * Wrong_Document_Err: if New_Child was created from another document

   --    * No_Modification_Allowed_Err: N or New_Child is read-only.

   --    * Not_Found_Err: Old_Child is not a child of N.


   function Remove_Child
     (N         : Node;
      Old_Child : Node) return Node;
   --  Remove Old_Child from the list of children of N, and return it.

   --  raises:

   --    * No_Modification_Allowed_Err: N is read-only

   --    * Not_Found_Err: Old_Child is not a child of N


   function Append_Child
     (N         : Node;
      New_Child : Node) return Node;
   --  Append New_Child at the end of the list of children of N, and return

   --  the added node.

   --  raises:

   --    * Hierarchy_Request_Err: N doesn't allow a child of this type, or

   --      New_Child is already an ancestor of N.

   --    * Wrong_Document_Err: if New_Child was created from another document

   --    * No_Modification_Allowed_Err: N or New_Child is read-only.


   function Has_Child_Nodes (N : Node) return Boolean;
   --  True if N has any children, False otherwise


   function Clone_Node (N : Node; Deep : Boolean) return Node;
   --  Returns a duplicate of N.

   --  The duplicate node has no parent.


   procedure Normalize (N : Node);
   --  Make sure there are no adjacent text nodes in the children of N.

   --  This processes the full-depth of the sub-tree underneath N.


   function Supports
     (N : Node;
      Feature : DOM_String;
      Version : DOM_String) return Boolean;
   --  Test whether the DOM implementation implements a specific feature, and

   --  that feature is supported by N.


   ---------------

   -- Node_List --

   ---------------


   function Item (List : Node_List; Index : Natural) return Node;
   --  Return index-nth element in the list (starting from 0)

   --  If Index is greated than or equal to the number of items in the list,

   --  null is returned.


   function Length (List : Node_List) return Natural;
   --  Return the number of elements in the list.


   --------------------

   -- Named_Node_Map --

   --------------------


   function Get_Named_Item
     (Map : Named_Node_Map; Name : DOM_String) return Node;
   --  Retrieve a node specified by name.

   --  null is returned if no such node exists

   --  Consider using Get_Named_Item_NS instead for DOM level 2


   procedure Set_Named_Item
     (Map : in out Named_Node_Map; Arg : Node; Replaces : out Node);
   procedure Set_Named_Item (Map : in out Named_Node_Map; Arg : Node);
   --  Add a node using its Node_Name attribute. Note that you can not have

   --  multiple instances of nodes with special names (#Document, ...).

   --  It returns the node that Arg replaces in Map, or null if it didn't

   --  replace anything.

   --  Consider using Set_Named_Item_NS instead for DOM level 2


   procedure Remove_Named_Item
     (Map : in out Named_Node_Map; Name : DOM_String; Removed : out Node);
   procedure Remove_Named_Item
     (Map : in out Named_Node_Map; Name : DOM_String);
   --  Remove a node from Map, and returns it.

   --  Consider using Remove_Named_Item_NS instead for DOM level 2


   procedure Remove_Named_Item (Map : in out Named_Node_Map; N : Node);
   --  Remove a specific node from the map


   function Item
     (Map : Named_Node_Map; Index : Natural) return Node;
   --  Return the Index-nth node in the list (starting from 0)


   function Length (Map : Named_Node_Map) return Natural;
   --  Return the number of elements in the map.


   function Get_Named_Item_NS
     (Map           : Named_Node_Map;
      Namespace_URI : DOM_String;
      Local_Name    : DOM_String) return Node;
   --  Retrieve a node specified by its (namespace, local_name)


   procedure Set_Named_Item_NS
     (Map : in out Named_Node_Map; Arg : Node; Replaces : out Node);
   procedure Set_Named_Item_NS
     (Map : in out Named_Node_Map; Arg : Node);
   --  Add a node using its namespace and local_name.

   --  It returns the node that Arg replaces (or null if none)


   procedure Remove_Named_Item_NS
     (Map           : in out Named_Node_Map;
      Namespace_URI : DOM_String;
      Local_Name    : DOM_String;
      Removed       : out Node);
   procedure Remove_Named_Item_NS
     (Map           : in out Named_Node_Map;
      Namespace_URI : DOM_String;
      Local_Name    : DOM_String);
   --  Remove a node specified by its namespace and local_name.


   -----------------------

   -- Extra subprograms --

   -----------------------

   --  The following subprograms are not part of the standard DOM interface.

   --  However, they are needed for a full usage of this DOM implementation


   procedure Print
     (N              : Node;
      Print_Comments : Boolean := False;
      Print_XML_PI   : Boolean := False;
      With_URI       : Boolean := False);
   --  Print the contents of Node and its children in XML format.

   --  If Print_Comments is True, then nodes associated with comments are

   --  also displayed.

   --  The <?xml?> processing instruction is displayed only if Print_XML_PI

   --  By default, names are of the form  ns_prefix:local_name. However, if

   --  with_URI is True, names will be  ns_URI:local_name instead


   procedure Print
     (List           : Node_List;
      Print_Comments : Boolean := False;
      Print_XML_PI   : Boolean := False;
      With_URI       : Boolean := False);
   --  Same as Print, byt for all the nodes in the list.


   procedure Free (N : in out Node; Deep : Boolean := True);
   --  This procedure is not part of the DOM standard, but is required to

   --  free the memory used by a node.

   --  Beware that a node is not removed from its parent.

   --  If Deep is True, then the children are also removed


end DOM.Core.Nodes;