NAME

XML::Sablotron::DOM - The DOM interface to Sablotron's internal structures

SYNOPSIS

use XML::Sablotron::DOM;

my $situa = new XML::Sablotron::Situation();
my $doc = new Sablotron::XML::Document(SITUATION => $sit);

my $e = $doc->createElement($situa, "foo");
my $t = $doc->createTextNode($situa, "this is my text");

print $doc->toString();

DESCRIPTION

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.

What is it good for

You may find this module useful if you need to

access parsed trees
build trees on the fly
pass parsed/built trees into XSLT processor

Situation

There is one significant extension to the DOM specification. Since Sablotron os 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.

A 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.

MEMORY ISSUES

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:

freeing the document
accessing the node after the document is destroyed

As results from above, you have to force XML::Sablotron::DOM to free document, if you want. Use

$doc->freeDocument($sit);

to to it.

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.

PACKAGES

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.

XML::Sablotron::DOM

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

Constants are defined for:

node types

$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
exception codes

$SDOM_OK, $INDEX_SIZE_ERR, $HIERARCHY_ERR, $WRONG_DOCUMENT_ERR, $NO_MODIFICATION_ALLOWED_ERR, $NOT_FOUND_ERR, $INVALID_NODE_TYPE_ERR, $QUERY_PARSE_ERR, $QUERY_EXECUTION_ERR, $NOT_OK

parse

This function parses the document specified by the URI. There is currently no support for scheme handler for this operation (see XML::Sablotron) but it will be added soon.

Function returns the XML::Sablotron::DOM::Document object instance.

XML::Sablotron::DOM::parse($sit, $uri);

$sit: The situation to be used.
$uri: The URI of the document to be parsed.

parseBuffer

This function parses the literal data specified.

XML::Sablotron::DOM::parseBuffer($sit, $data);

$sit: The situation to be used.
$data: The string containing the XML data to be parsed.

parseStylesheet

This function parses the stylesheet specified by the URI. There is currently no support for scheme handler for this operation (see XML::Sablotron) but it will be added soon.

Function returns the XML::Sablotron::DOM::Document object instance.

XML::Sablotron::DOM::parseStylesheet($sit, $uri);

$sit: The situation to be used.
$uri: The URI of the stylesheet to be parsed.

parseStylesheetBuffer

This function parses the stylesheet given by the literal data.

XML::Sablotron::DOM::parseStylesheetBuffer($sit, $data);

$sit: The situation to be used.
$data: The string containing the stylesheet to be parsed.

XML::Sablotron::DOM::Node

This packages is used to represent the Sablotron internal representation of the node. It is the common ancestor of all other types.

equals

Check if the to perl representations of the node represent the same node in the DOM document.

Synopsis:

$node1->equals($node2);

$node2: The node to be compared to.

getNodeType

Returns the node type. See "XML::Sablotron::DOM" for more details.

$node->getNodeType([$situa]);

$situa: The situation to be used (optional).

getNodeName

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", DOCUMNET_NODE => "#document"

Synopsis:

$node->getNodeName([$situa]);

$situa: The situation to be used (optional).

setNodeName

Sets the name of the node.

Exceptions:

NO_MODIFICATION_ALLOWED_ERR: for TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE and DOCUMENT_NODE

Synopsis:

$node->setNodeName($name [, $situa]);

$name: The new node name.
$situa: The situation to be used (optional).

getNodeValue

returns the content of TEXT_NODE, CDATA_SECTION_NODE and COMMENT_NODE, otherwise returns undef.

Synopsis:

$node->getNodeValue([$situa]);

$situa: The situation to be used (optional).

setNodeValue

Sets the content of the node for TEXT_NODE, CDATA_SECTION_NODE and COMMENT_NODE.

Exceptions:

NO_MODIFICATION_ALLOWED_ERR: for ELEMENT_NODE, DOCUMENT_NODE

Synopsis:

$node->setNodeValue($value [, $situa]);

$value: The new node value.
$situa: The situation to be used (optional).

getParentNode

Returns the parent node, if there is any. Otherwise returns undef. Undefined value is always returned for the DOCUMENT_NODE.

Synopsis:

$node->getNodeValue([$situa]);

$situa: The situation to be used (optional).

getFirstChild

Get the first child of the node or undef.

Synopsis:

$node->getFirstChild([$situa]);

$situa: The situation to be used (optional).

getLastChild

Get the last child of the node or undef.

Synopsis:

$node->getLastChild([$situa]);

$situa: The situation to be used (optional).

getPreviousSibling

Returns the node immediately preceding the node. Returns undef, if there is no such node.

Synopsis:

$node->getPreviousSibling([$situa]);

$situa: The situation to be used (optional).

getNextSibling

Returns the node immediately following the node. Returns undef, if there is no such node.

Synopsis:

$node->getNextSibling([$situa]);

$situa: The situation to be used (optional).

getOwnerDocument

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->getOwnerDocument([$situa]);

$situa: The situation to be used (optional).

insertBefore

Makes a new node the child of the 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:

HIERARCHY_REQUEST_ERR: Raised if the node doesn't allow children of given type.
WRONG_DOCUMENT_ERR: Raised if the new node is not owned by the same document as the node.

Synopsis:

$node->insertBefore($new_node, $ref_node [, $situa]);

$new_node: The inserted node.
$ref_node: The reference node. The new node is to be inserted right before this node. May be undef; in this case the new node is appended.
$situa: The situation to be used (optional).

appendChild

Appends the new node to the list of children of the node.

Exceptions:

HIERARCHY_REQUEST_ERR: Raised if the node doesn't allow children of given type.
WRONG_DOCUMENT_ERR: Raised if the new node is not owned by the same document as the node.

Synopsis:

$node->appendChild($child, [$situa]);

$child: The node to be appended.
$situa: The situation to be used (optional).

removeChild

Remove the child node from the list of children of the node.

Exceptions:

NOT_FOUND_ERR: Raised if the removed node is not the child of the node.

Synopsis:

$node->removeChild($child, [, $situa]);

$child: The node to be removed.
$situa: The situation to be used (optional).

replaceChild

Replace the child node with the new one.

Exceptions:

HIERARCHY_REQUEST_ERR: Raised if the node doesn't allow children of given type.
WRONG_DOCUMENT_ERR: Raised if the new node is not owned by the same document as the node.
NOT_FOUND_ERR: Raised if the replaced node is not the child of the node.

Synopsis:

$node->replaceChild($child, $old_child [, $situa]);

$child: The new child to be inserted (in the place of the $old_child)
$old_child: The node to be replaced.
$situa: The situation to be used (optional).

xql

Executes the XPath expression and returns the ARRAYREF of resulting nodes.

Synopsis:

$node->xql($expr [, $situa]);

$expr: The expression to be replaced.
$situa: The situation to be used (optional).

XML::Sablotron::DOM::Document

Represents the whole DOM document (the "/" root element).

freeDocument

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.

Synopsis:

$doc->freeDocument([$situa]);

$situa: The situation to be used (optional).

toString

Serializes the document tree into the string representation.

Synopsis:

$doc->toString([$situa])

$situa: The situation to be used (optional).

cloneNode

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->cloneNode($node, $deep [, $situa]);

$node: The node to be cloned.
$deep: If true, all children of the node are cloned too.
$situa: The situation to be used (optional).

createElement

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

$name: The new element name.
$situa: The situation to be used (optional).

createTextNode

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

$data: The initial value of the node.
$situa: The situation to be used (optional).

createCDATASection

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

$data: The initial value of the node.
$situa: The situation to be used (optional).

createComment

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

$data: The initial value of the node.
$situa: The situation to be used (optional).

createProcessingInstruction

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

$target: The target for the PI.
$data: The data for the PI.
$situa: The situation to be used (optional).

XML::Sablotron::DOM::Element

Represents the element of the tree.

getAttribute

$hashref = $e->getAttribute($name [, $situa]);

$name: The name of queried attribute.
$situa: The situation to be used (optional).

setAttribute

$hashref = $e->setAttribute($name, $value [, $situa]);

$name: The name of attribute to be set.
$value: The value of the new attribute.
$situa: The situation to be used (optional).

getAttributes

$hashref = $e->getAttributes([$situa]);

$situa: The situation to be used (optional).

setAttributes

$hashref = $e->setAttributes($hashref [, $situa]);

$hashref: The HASHREF value. Referenced hash contains name/value pair to be used.
$situa: The situation to be used (optional).

removeAttribute

$hashref = $e->removeAttribute($name [, $situa]);

$name: The name of attribute to be removed.
$situa: The situation to be used (optional).

AUTHOR

Pavel Hlavnicka, pavel@gingerall.cz; Ginger Alliance LLC;

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

What is it good for

Situation

MEMORY ISSUES

PACKAGES

XML::Sablotron::DOM

constants

parse

parseBuffer

parseStylesheet

parseStylesheetBuffer

XML::Sablotron::DOM::Node

equals

getNodeType

getNodeName

setNodeName

getNodeValue

setNodeValue

getParentNode

getFirstChild

getLastChild

getPreviousSibling

getNextSibling

getOwnerDocument

insertBefore

appendChild

removeChild

replaceChild

xql

XML::Sablotron::DOM::Document

freeDocument

toString

cloneNode

createElement

createTextNode

createCDATASection

createComment

createProcessingInstruction

XML::Sablotron::DOM::Element

getAttribute

setAttribute

getAttributes

setAttributes

removeAttribute

AUTHOR

SEE ALSO

Module Install Instructions