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;