------------------------------------------------------------------------------ -- 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;