XML::Sablotron::DOM - The DOM interface to Sablotron's internal structures
use XML::Sablotron::DOM;
my $situa = new XML::Sablotron::Situation(); my $doc = new XML::Sablotron::DOM::Document(SITUATION => $sit);
my $e = $doc->createElement($situa, "foo"); my $t = $doc->createTextNode($situa, "this is my text");
print $doc->toString();
Sablotron uses internally the DOM-like data structures to represent
parsed XML trees. In the sdom.h header file is defined a subset of
functions allowing the DOM access to these structures.
You may find this module useful if you need to
There is one significant extension to the DOM specification. Since Sablotron is designed to support multithreading processing (and well reentrant code too), you need create and use special context for error processing. This context is called the situation.
An instance of this object MUST be passed as the first parameter to
almost all calls in the XML::Sablotron::DOM code.
Some easy-to-use default behavior may be introduced in later releases.
See perldoc XML::Sablotron for more details.
Perl objects representing nodes of the DOM tree live independently on internal structures of Sablotron. If you create and populate the document, its structure is not related to the lifecycle of your Perl variables. It is good for you, but there are two exceptions to this:
As results from above, you have to force XML::Sablotron::DOM to free document, if you want. Use
$doc->freeDocument($sit);
to to it. Another way is to use the autodispode feature (see the documentation for the method autodispose and document constructor).
If you will try to access the node, which was previously disposed by
Sablotron (perhaps with the all tree), your Perl code will die with
exception -1. Use eval {}; to avoid program termination.
The XML::Sablotron::DOM defines several packages. Just will be
created manually in your code; they are mostly returned as a return
values from many functions.
The XML::Sablotron::DOM package is almost empty, and serves as a
parent module for the other packages.
By default this module exports no symbols into the callers package. If want to use some predefined constants or functions, you may use
use XML::Sablotron::DOM qw( :constants :functions );
Constants are defined for:
ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE,
ENTITY_REFERENCE_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE,
COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE,
DOCUMENT_FRAGMENT_NODE, NOTATION_NODE, OTHER_NODE
SDOM_OK, INDEX_SIZE_ERR, DOMSTRING_SIZE_ERR, HIERARCHY_ERR,
WRONG_DOCUMENT_ERR, INVALID_CHARACTER_ERR, NO_DATA_ALLOWED_ERR,
NO_MODIFICATION_ALLOWED_ERR, NOT_FOUND_ERR, NOT_SUPPORTED_ERR,
INUSE_ATTRIBUTE_ERR, INVALID_STATE_ERR, SYNTAX_ERR,
INVALID_MODIFICATION_ERR, NAMESPACE_ERR, INVALID_ACCESS_ERR,
INVALID_NODE_TYPE_ERR, QUERY_PARSE_ERR QUERY_EXECUTION_ERR,
NOT_OK
This function parses the document specified by the URI. There is currently no support for scheme handler for this operation (see the XML::Sablotron manpage) but it will be added soon.
Function returns the XML::Sablotron::DOM::Document object instance.
XML::Sablotron::DOM::parse($sit, $uri);
This function parses the literal data specified.
XML::Sablotron::DOM::parseBuffer($sit, $data);
This function parses the stylesheet specified by the URI. There is currently no support for scheme handler for this operation (see the XML::Sablotron manpage) but it will be added soon.
Function returns the XML::Sablotron::DOM::Document object instance.
XML::Sablotron::DOM::parseStylesheet($sit, $uri);
This function parses the stylesheet given by the literal data.
XML::Sablotron::DOM::parseStylesheetBuffer($sit, $data);
This package is used to represent the Sablotron internal representation of the node. It is the common ancestor of all other types.
Check if the to perl representations of the node represent the same node in the DOM document. Not in DOM spec.
Synopsis:
$node1->equals($node2);
For ELEMENT_NODE and ATTRIBUTE_NODE returns the name of the node. For other node types return as follows:
TEXT_NODE => ``#text'', CDATA_SECTION_NODE => ``#cdata-section'', COMMENT_NODE => ``#comment'', DOCUMENT_NODE => ``#document'', PROCESSING_INSTRUCTION_NODE => target of this node
Not in DOM spec.
Synopsis:
$node->getNodeName([$situa]);
Sets the name of the node. Not in DOM spec.
Exceptions:
=item NAMESPACE_ERR
for ELEMENT_NODE:if unknown prefix is used to set name for ATTRIBUTE_NODE:if attempt to change non-namespace attribute to namespace attribute a vice versa
Synopsis:
$node->setNodeName($name [, $situa]);
Gets or sets the name of the node.
Exceptions:
Synopsis:
$node->nodeName([$situa]); $node->nodeName($name [, $situa]);
Returns the value of ATTRIBUTE_NODE, the content of TEXT_NODE, CDATA_SECTION_NODE and COMMENT_NODE, the body of PROCESSING_INSTRUCTION_NODE and otherwise returns undef. Not in DOM spec.
Synopsis:
$node->getNodeValue([$situa]);
Sets the content of the node for TEXT_NODE, CDATA_SECTION_NODE and COMMENT_NODE, the value of ATTRIBUTE_NODE, the body of PROCESSING_INSTRUCTION_NODE. Not in DOM spec.
Exceptions:
Synopsis:
$node->setNodeValue($value [, $situa]);
Gets or sets the content of the node for ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, PROCESSING_INSTRUCTION_NODE and COMMENT_NODE.
Exceptions:
Synopsis: $node->nodeValue([$situa]); $node->nodeValue($value [, $situa]);
Returns the node type. See XML::Sablotron::DOM for more details. Not in DOM spec.
Synopsis:
$node->getNodeType([$situa]);
Returns the node type. See XML::Sablotron::DOM for more details.
Synopsis:
$node->nodeType([$situa]);
Returns the parent node, if there is any. Otherwise returns undef. Undefined value is always returned for the DOCUMENT_NODE. Not in DOM spec.
Synopsis:
$node->getParentNode([$situa]);
Returns the parent node, if there is any. Otherwise returns undef. Undefined value is always returned for the DOCUMENT_NODE.
Synopsis:
$node->parentNode([$situa]);
Returns the reference to the array of all child nodes of given node. This array is NOT alive, i.e. the content of once created array does not reflect the changes of DOM tree. Not in DOM spec.
Synopsis:
$node->getChildNodes([$situa]);
Returns the reference to the array of all child nodes of given node. This array is NOT alive, i.e. the content of once created array does not reflect the changes of DOM tree. Not in DOM spec.
Synopsis:
$node->childNodesArr([$situa]);
Returns the reference to the instance of XML::Sablotron::DOM::NodeList. This array is alive, i.e. the content of once created array does reflect the changes of DOM tree.
Synopsis:
see XML::Sablotron::DOM::NodeList
Get the first child of the node or undef. Not in DOM spec.
Synopsis:
$node->getFirstChild([$situa]);
Get the first child of the node or undef.
Synopsis:
$node->firstChild([$situa]);
Get the last child of the node or undef. Not in DOM spec.
Synopsis:
$node->getLastChild([$situa]);
Get the last child of the node or undef.
Synopsis:
$node->lastChild([$situa]);
Returns the node immediately preceding the node. Returns undef, if there is no such node. Not in DOM spec.
Synopsis:
$node->getPreviousSibling([$situa]);
Returns the node immediately preceding the node. Returns undef, if there is no such node.
Synopsis:
$node->previousSibling([$situa]);
Returns the node immediately following the node. Returns undef, if there is no such node. Not in DOM spec.
Synopsis:
$node->getNextSibling([$situa]);
Returns the node immediately following the node. Returns undef, if there is no such node.
Synopsis:
$node->nextSibling([$situa]);
Returns undef. Implemented in XML::Sablotron::DOM::Element.
Returns the document owning the node. It is always the document, which created this node. For document itself the return value is undef. Not in DOM spec.
Synopsis:
$node->getOwnerDocument([$situa]);
Returns the document owning the node. It is always the document, which created this node. For document itself the return value is undef.
Synopsis:
$node->ownerDocument([$situa]);
Makes a new node the child of thexpression to be replacede node. It is put right before the reference node. If the reference node is not defined, the new node is appended to the child list.
Exceptions:
Synopsis:
$node->insertBefore($new_node, $ref_node [, $situa]);
Replace the child node with the new one. Returns replaced (old) child.
Exceptions:
Synopsis:
$node->replaceChild($child, $old_child [, $situa]);
Remove the child node from the list of children of the node.
Exceptions:
Synopsis:
$node->removeChild($child, [, $situa]);
Appends the new node to the list of children of the node.
Exceptions:
Synopsis:
$node->appendChild($child, [$situa]);
Returns the count of child nodes.
Synopsis:
$node->hasChildNodes([$situa]);
Returns the copy of node.
Exceptions:
Synopsis:
$node->cloneNode($deep [, $situa]);
Does and returns nothing.
Returns false (exactly 0).
Returns uri of the namespace, in which node is.
Synopsis:
$node->namespaceURI([$situa]);
Gets or sets prefix of the node.
Synopsis:
$node->prefix([$situa]); $node->prefix($prefix [, $situa]);
Returns local name of the node.
Synopsis:
$node->localName([$situa]);
Returns false (exactly 0).
Executes the XPath expression and returns the ARRAYREF of resulting nodes. Not in DOM spec.
Synopsis:
$node->xql($expr [, $situa]);
Represents the whole DOM document (the ``/'' root element).
Create the new empty document. Not in DOM spec.
Synopsis:
$doc = XML::Sablotron::DOM::Document->new([AUTODISPOSE => $ad]);
Reads or set the autodispose flag, This flag causes, that the document is destroyed after the last Perl reference is undefined. Not in DOM spec.
Synopsis:
$doc->autodispose([$ad]);
Disposes all memory allocated by Sablotron for the DOM document. This is the only way how to do it. See MEMORY ISSUES for more details. Not in DOM spec.
Synopsis:
$doc->freeDocument([$situa]);
Serializes the document tree into the string representation. Not in DOM spec.
Synopsis:
$doc->toString([$situa])
Returns the root element of the document.
Synopsis:
$doc->documentElement([$situa])
Creates the new ELEMENT_NODE. The parent of the node is not set; the owner document is set to the document.
Synopsis:
$doc->createElement($name [, $situa]);
Creates the new TEXT_NODE. The parent of the node is not set; the owner document is set to the document.
Synopsis:
$doc->createTextNode($data [, $situa]);
Creates the new COMMENT_NODE. The parent of the node is not set; the owner document is set to the document.
Synopsis:
$doc->createComment($data [, $situa]);
Creates the new CDATA_SECTION_NODE. The parent of the node is not set; the owner document is set to the document.
Synopsis:
$doc->createCDATASection($data [, $situa]);
Creates the new PROCESSING_INSTRUCTION_NODE. The parent of the node is not set; the owner document is set to the document.
Synopsis:
$doc->createProcessingInstruction($target, $data [, $situa]);
Creates the new attribute. The owner document is set to the document.
Synopsis:
$doc->createAttribute($name [, $situa]);
Clone the node. The children of the node may be cloned too. The cloned node may be from another document; cloned nodes are always owned by the calling document. Parent of the cloned node is not set. Not in DOM spec.
Synopsis:
$doc->cloneNode($node, $deep [, $situa]);
Clone the node. The children of the node may be cloned too. The cloned node may be from another document; cloned nodes are always owned by the calling document. Parent of the cloned node is not set.
Synopsis:
$doc->importNode($node, $deep [, $situa]);
Creates the new element. The parent of the node is not set; the owner document is set to the document.
Exceptions:
Synopsis:
$doc->createElementNS($namespaceUri, $qname [, $situa]);
Creates the new attribute. The owner document is set to the document.
Exceptions:
Synopsis:
$doc->createAttributeNS($namespaceUri, $qname [, $situa]);
Represents the element of the tree.
Returns the element name.
Synopsis:
$e->tagName([$situa]);
Retrieves an attribute value by name.
Synopsis:
$value = $e->getAttribute($name [, $situa]);
If attribute with specified name already exists, sets its value, otherwise inserts new attribute and sets its value.
Synopsis:
$e->setAttribute($name, $value [, $situa]);
Returns the reference to the hash of all attributes of the element. This hash is NOT alive, i.e. the content of once created hash does not reflect the changes of DOM tree. Not in DOM spec.
Synopsis:
$hashref = $e->getAttributes([$situa]);
Calls $e->setAttribute for each name/value pair of referenced hash. Not in DOM spec.
Synopsis:
$e->setAttributes($hashref [, $situa]);
Named node map of element attributes. This object IS alive. See XML::Sablotron::DOM::NamedNodeMap.
Synopsis:
$e->attributes->method_of_NamedNodeMap;
Removes an attribute by name.
Synopsis:
$e->removeAttribute($name [, $situa]);
Retrieves an attribute node by name.
Synopsis:
$node = $e->getAttributeNode($name [, $situa]);
Adds a new attribute node. If an attribute with that name is already present in the element, it is replaced by the new one.
Exceptions:
Raised if the $att is from different document as $e.
Synopsis:
$replaced = $e->setAttributeNode($att [, $situa]);
Removes specified attribute and returns it.
Exceptions:
Synopsis:
$removed = $e->removeAttributeNode($attNode [, $situa]);
Retrieves an attribute value by local name and namespace URI.
Synopsis:
$value = $e->getAttributeNS($nsURI, $localName [, $situa]);
If attribute with specified namespace URI and local name already exists, sets its value and prefix; otherwise inserts new attribute and sets its value.
Synopsis:
$removed = $e->setAttributeNS($nsURI, $qName, $value [, $situa]);
Removes an attribute by local name and namespace URI.
Exceptions:
Synopsis:
$e->removeAttributeNS($namespaceURI, $localName [, $situa]);
Retrieves an attribute by local name and namespace URI.
Synopsis:
$node = $e->getAttributeNodeNS($nsURI, $localName [, $situa]);
If attribute with the same namespace URI and local name already exists, replaces it; otherwise inserts specified attribute.
Synopsis:
$replaced = $e->setAttributeNS($att [, $situa]);
Returns true if attribute with the specified name already exists, (exactly returns 1); otherwise returns false (exactly 0).
Synopsis:
$e->hasAttribute($name [, $situa]);
Returns true if attribute with the specified namespace URI and local name already exists, (exactly returns 1); otherwise returns false (exactly 0).
Synopsis:
$e->hasAttribute($nsURI, $localName [, $situa]);
Serializes the element and its subtree into the string representation.
Synopsis:
$e->toString([$situa])
Represents the attribute.
Returns the attribute name.
Synopsis:
$a->name([$situa])
Returns true (exactly 1).
Synopsis:
$a->specified([$situa])
Gets or sets value of the attribute. See XML::Sablotron::DOM::Node::nodeValue.
Synopsis:
$a->value([$situa]) $a->value($value [, $situa])
Returns element owning the attribute, if any.
Synopsis:
$e = $a->ownerElement([$situa])
Represents class, which serves as parent for another DOM objects.
Gets or sets character data of the node. See XML::Sablotron::DOM::nodeValue
Synopsis:
$node->data([$situa]) $node->data($data [, $situa])
Returns length of character data of the node.
Synopsis:
$node->length([$situa])
Returns substring of character data of the node.
Exceptions:
Synopsis:
$node->substringData($offset, $count [, $situa])
Appends specified substring to character data of the node.
Synopsis:
$node->appendData($data [, $situa])
Inserts specified substring to character data of the node.
Exceptions:
Synopsis:
$node->insertData($offset, $data [, $situa])
Cuts specified substring from character data of the node.
Exceptions:
Synopsis:
$node->deleteData($offset, $count [, $situa])
Replaces specified substring from character data of the node.
Exceptions:
Synopsis:
$node->replaceData($offset, $count, $data [, $situa])
Represents a text node of DOM tree.
If length of data is greather than specified offset, inserts new text node behind original node and splits original node data to two chunks, the first chunk with offset length set to original node, the second chunk set to newly created node.
Exceptions:
Synopsis:
$node->splitText($offset [, $situa])
Represents a processing instruction of DOM tree.
Gets the first token of node value.
Synopsis:
$pi->target([$situa])
Gets or sets the content of the processing instruction (text starting with the first non-whitespace character after target).
Synopsis:
$pi->data([$situa]) $pi->data($content [, $situa])
Represents a list of some items.
Returns the item on specified position in the list.
Synopsis:
$list->item($index)
Returns count of the list items.
Synopsis:
$list->length()
Represents a collection of nodes that can be accessed by name.
Returns the node specified by name.
Synopsis:
$node = $nnm->getNamedItem($name)
Inserts or replaces node to map by its name.
Synopsis:
$replaced = $nnm->setNamedItem($node)
Removes node from map by its name.
Exceptions:
Synopsis:
$removed = $nnm->removeNamedItem($name)
Returns the node specified by local name and namespace URI.
Synopsis:
$node = $nnm->getNamedItemNS($nsURI, $localName)
Inserts or replaces node to map by its local name and namespace URI.
Synopsis:
$replaced = $nnm->setNamedItemNS($node)
Removes node from map by its local name and namespace URI.
Exceptions:
Synopsis:
$removed = $nnm->removeNamedItemNS($nsURI, $localName)
Pavel Hlavnicka, pavel@gingerall.cz; Ginger Alliance LLC; Jan Poslusny, pajout@gingerall.cz; Ginger Alliance LLC;
perl(1).