------------------------------------------------------------------------------
-- XML/Ada - An XML suite for Ada95 --
-- --
-- Copyright (C) 2001-2012, AdaCore --
-- --
-- This library is free software; you can redistribute it and/or modify it --
-- under terms of the GNU General Public License as published by the Free --
-- Software Foundation; either version 3, 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 MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
-- --
-- --
-- --
-- --
-- You should have received a copy of the GNU General Public License and --
-- a copy of the GCC Runtime Library Exception along with this program; --
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
-- . --
-- --
------------------------------------------------------------------------------
with Ada.Streams;
with Sax.Encodings;
with Unicode.Encodings;
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.
-- For an node, this returns the qualified name, in the form of
-- "prefix:local_name". See below for subprograms to get each of the
-- components separately instead.
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.
function Node_Type (N : node) return node_types;
-- Return the type of the node
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.
-- Note: In the Ada implementation, this only works when N belongs to
-- a tree already, it doesn't work for isolated nodes.
function Local_Name (N : node) return dom_string;
function Local_Name (N : node) return Sax.Symbols.symbol;
-- 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.
-- The caller must free the returned node.
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
-- The caller must free the returned node.
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;
function Get_Named_Item
(Map : named_node_map;
Name : Sax.Symbols.symbol) 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;
function Get_Named_Item_NS
(Map : named_node_map;
Namespace_URI : Sax.Symbols.symbol;
Local_Name : Sax.Symbols.symbol) 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.
------------------
-- Input/Output --
------------------
procedure Write
(Stream : access Ada.Streams.Root_Stream_Type'class;
N : node;
Print_Comments : Boolean := True;
Print_XML_Declaration : Boolean := True;
With_URI : Boolean := False;
Pretty_Print : Boolean := False;
EOL_Sequence : String := "" & ASCII.LF;
Encoding : Unicode.Encodings.unicode_encoding :=
Unicode.Encodings.Get_By_Name ("utf-8");
Collapse_Empty_Nodes : Boolean := True);
-- Print the contents of Node and its children in XML format.
-- If Print_Comments is True, then nodes associated with comments are
-- also displayed.
-- EOL_Sequence is output at every end of line. It should be encoded in
-- Sax.Encodings.Encoding, and will be automatically converted to the
-- appropriate output encoding.
-- Encoding specifies the encoding to use in the output stream.
--
-- The declaration is displayed only if Print_XML_Declaration and
-- N is a Document_Node. In this case, a Byte-Order mark is also output
-- so that proper decoding of the document can be performed later on.
-- Note that you mustn't added yourself to the DOM tree. The XML
-- standard doesn't define this as a processing instruction, which is why
-- it has a different name ("XML declaration") and cannot be modified by
-- users.
--
-- 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
--
-- If Collapse_Empty_Nodes is true, then nodes with no child node will be
-- output as , instead of
--
-- If Pretty_Print is true, then the XML nodes will be indented so that
-- children nodes are to the right of their parents. It is set to False
-- by default because its use changes the document (addition or removal
-- of whitespaces among other things), which in general has no effect for
-- automatic tools reading the document. All whitespaces are modified
-- outside of elements containing nothing but text nodes. For text nodes,
-- leading and trailing whitespaces are also deleted
-----------------------
-- 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.
-- The output of any of these subprograms is likely to change from one
-- version of XML/Ada to the next, do not rely on it.
procedure Print
(N : node;
Print_Comments : Boolean := False;
Print_XML_PI : Boolean := False;
With_URI : Boolean := False;
EOL_Sequence : String := Sax.Encodings.Lf_Sequence;
Encoding : Unicode.Encodings.unicode_encoding :=
Unicode.Encodings.Get_By_Name ("utf-8");
Collapse_Empty_Nodes : Boolean := False);
-- For debugging purposes only!
--
-- Same as Write, but the output is done on Stdout.
-- Warning: the default values for the parameters are not the same as for
-- write. For the latter, they are chosen so that by default the output is
-- valid XML, whereas Print is mostly intended to be used for testsuite
-- purposes, and the default match that goal.
procedure Dump (N : node; With_URI : Boolean := False);
-- Dump the contents of the node to standard output.
-- This output shows the structure of the tree instead of a valid XML file.
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;