/ 
XML-LibXML-1.54_2
River stage four • 504 direct dependents • 1164 total dependents
/ XML::LibXML::Node
Security Advisories (2)
CVE-2015-3451 (2015-04-23)

The _clone function does not properly set the expand_entities option, which allows remote attackers to conduct XML external entity (XXE) attacks via crafted XML data to the (1) new or (2) load_xml function.

CVE-2017-10672 (2015-04-23)

Use-after-free in the XML-LibXML module through 2.0129 for Perl allows remote attackers to execute arbitrary code by controlling the arguments to a replaceChild call.

NAME

XML::LibXML::Node - abstract Base Class DOM-Nodes

synopsis

use XML::LibXML

$name = $node->nodeName;
$node->setNodeName( $newName );
$bool = $node->isSameNode( $other_node );
$bool = $node->isEqual( $other_node );
$content = $node->nodeValue;
$content = $node->textContent;
$type = $node->nodeType;
$node->unbindNode()
$childnode = $node->removeChild( $childnode )
$oldnode = $node->replaceChild( $newNode, $oldNode )
$node->replaceNode($newNode);
$childnode = $node->appendChild( $childnode );
$childnode = $node->addChild( $chilnode );
$node = $parent->addNewChild( $nsURI, $name );
$node->addSibling($newNode);
$newnode =$node->cloneNode( $deep )
$parentnode = $node->parentNode;
$nextnode = $node->nextSibling()
$prevnode = $node->previousSibling()
$boolean = $node->hasChildNodes();
$childnode = $node->firstChild;
$childnode = $node->lastChild;
$documentnode = $node->ownerDocument;
$node = $node->getOwner;
$node->setOwnerDocument( $doc );
$node->insertBefore( $newNode, $refNode )
$node->insertAfter( $newNode, $refNode )
@nodes = $node->findnodes( $xpath_statement );
$result = $node->find( $xpath );
print $node->findvalue( $xpath );
@childnodes = $node->childNodes;
$xmlstring = $node->toString($format,$docencoding);
$localname = $node->localname;
$nameprefix = $node->prefix;
$uri = $node->namespaceURI()
$boolean = $node->hasAttributes();
@attributelist = $node->attributes();
$URI = $node->lookupNamespaceURI( $prefix );
$prefix = $node->lookupNamespacePrefix( $URI );
$iter = $node->iterator;
$node->normalize;
@nslist = $node->getNamespaces;
$node->removeChildNodes();

DESCRIPTION

LibXML::Node defines functions that are common to all Node Types. A LibXML::Node should never be created standalone, but as an instance of a high level class such as LibXML::Element or LibXML::Text. The class itself should provide only common functionality. In XML::LibXML each node is part either of a document or a document-fragment. Because of this there is no node without a parent. This may causes confusion with "unbound" nodes.

Methods

nodeName

Returns the node's name. This Function is aware about namesaces and returns the full name of the current node (prefix:localname)

setNodeName

In very limited situation it is usefull to change a nodes name. In the DOM specification this should throw an error. This Function is aware about namespaces.

isSameNode

returns TRUE (1) if the given nodes refer to the same node structure, otherwise FALSE (0) is returned.

isEqual

depraced version of isSameNode().

NOTE isEqual will change behaviour to follow the DOM specification

nodeValue

If the node has any content (such as stored in a text node) it can get requested through this function.

NOTE: Element Nodes have no content per definition. To get the text value of an Element use textContent() instead!

textContent

this function returns the content of all text nodes in the descendants of the given node as spacified in DOM.

nodeType

Retrun the node's type. The possible types are described in the libxml2 tree.h documentation. The return value of this function is a numeric value. Therefore it differst with the result of perl ref function.

unbindNode

Unbinds the Node from its siblings and Parent, but not from the Document it belongs to. If the node is not inserted into the DOM afterwards it will be lost after the programm terminated. From a low level view, the unbound node is stripped from the context it is and inserted into a (hidden) document-fragment.

removeChild

This will unbind the Child Node from its parent $node. The function returns the unbound node. If oldNode is not a child of the given Node the function will fail.

replaceChild

Replaces the $oldNode with the $newNode. The $oldNode will be unbound from the Node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.

replaceNode

This function is very similar to replaceChild(), but it replaces the node itself rather than a childnode. This is useful if a node found by any XPath function, should be replaced.

appendChild

The function will add the $childnode to the end of $node's children. The function should fail, if the new childnode is allready a child of $node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.

addChild

As an alternative to appendChild() one can use the addChild() function. This function is a bit faster, because it avoids all DOM confomity checks. Therefore this function is quite usefull if one builds XML documents in memory where the order and ownership (ownerDocument) is ashured.

addChild() uses libxml2's own xmlAddChild() function. Thus it has to be used with extra care: If a text node is added to a node and the node itself or its last childnode is aswell a text node, the node to add will be merged with the one already available. The current node will be removed from memory after this action. Because perl is not aware about this action, the perl instance is still available. XML::LibXML will catch the loss of a node an avoid to run any function called on that node.

my $t1 = $doc->createTextNode( "foo" );
my $t2 = $doc->createTextNode( "bar" );
$t1->addChild( $t2 );       # is ok
my $val = $t2->nodeValue(); # will fail, script dies

Also addChild() will not check it the added node belongs to the same document as the node it will be added to. This could lead to inconsistent documents and in more worse cases even to memory violations, if one does not keep track of this issue.

Although this sounds like a lot of trouble, addChild() is usefull if a document is build from a stream, such as happens sometimes in SAX handlers or filters.

If you are not shure about the source of your nodes, you better stay with appendChild(), because this function is more user friendly in the sense of more error tolerance.

addNewChild

Similar to addChild(), this function uses low level libxml2 functionality to provide faster interface for DOM building. addNewChild() uses xmlNewChild() to create a new node on a given parent element.

addNewChild() has two parameters $nsURI and $name, where $nsURI is an (optional) namespace URI. $name is the fully qualified element name; addNewChild() will determine the correct prefix if nessecary.

The function returns the newly created node.

This function is very usefull for DOM building, where a created node can be directly associated to its parent. NOTE this function is not part of the DOM specification and its use will limit your code to XML::LibXML.

addSibling

addSibling() allows to add an additional node to the end of a nodelist, defined by the given node.

cloneNode

cloneNode creates a copy of $node. Wether $deep is set to 1 (true) the function will copy all childnodes as well. If $deep is 0 only the current node will be copied.

cloneNode will not copy any namespace information if it is not run recursivly.

parentNode

Returns simply the Parent Node of the current node.

nextSibling

Returns the next sibling if any .

previousSibling

Analogous to getNextSibling the function returns the previous sibling if any.

hasChildNodes

If the current node has Childnodes this function returns TRUE (1), otherwise it returns FALSE (0, not undef).

firstChild

If a node has childnodes this function will return the first node in the childlist.

lastChild

If the $node has childnodes this function returns the last child node.

ownerDocument

Through this function it is allways possible to access the document the current node is bound to.

getOwner

This function returns the node the current node is associated with. In the very most cases this will be a document node or a document fragment node.

setOwnerDocument

This function binds a node to another DOM. This method unbinds the node first, if it is allready bound to another document.

This function is the oposite calling of XML::LibXML::Document's adoptNode() function. Because of this it has the same limitations with Entity References as adoptNode().

insertBefore

The method inserts $newNode before $refNode. If $refNode is undefined, the newNode will be set as the new first child of the parent node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.

insertAfter

The method inserts $newNode after $refNode. If $refNode is undefined, the newNode will be set as the new last child of the parent node.

findnodes

findnodes performs the xpath statement on the current node and returns the result as an array. In scalar context returns a XML::LibXML::NodeList object.

find

find performs the xpath expression using the current node as the context of the expression, and returns the result depending on what type of result the XPath expression had. For example, the XPath "1 * 3 + 52" results in a XML::LibXML::Number object being returned. Other expressions might return a XML::LibXML::Boolean object, or a XML::LibXML::Literal object (a string). Each of those objects uses Perl's overload feature to "do the right thing" in different contexts.

findvalue

findvalue is exactly equivalent to:

$node->find( $xpath )->to_literal;

That is, it returns the literal value of the results. This enables you to ensure that you get a string back from your search, allowing certain shortcuts. This could be used as the equivalent of XSLT's .

childNodes

getChildnodes implements a more intuitive interface to the childnodes of the current node. It enables you to pass all children directly to a map or grep. If this function is called in scalar context, a XML::LibXML::NodeList object will be returned.

toString

This is the equivalent to XML::LibXML::Document::toString for a single node. This means a node and all its childnodes will be dumped into the result string.

Additionally to the $format flag of XML::LibXML::Document, this version accepts the optional $docencoding flag. If this flag is set this function returns the string in its original encoding (the encoding of the document) rather than UTF8.

localname

Returns the local name of a tag. This is the part behind the colon.

prefix

Returns the prefix of a tag. This is the part before the colon.

namespaceURI

returns the URI of the current namespace.

hasAttributes

returns 1 (TRUE) if the current node has any attributes set, otherwise 0 (FALSE) is returned.

attributes

This function returns all attributes and namespace declarations assigned to the given node.

Because XML::LibXML does not implement namespace declarations and attributes the same way, it is required to test what kind of node is handled while accessing the functions result.

If this function is called in array context the attribute nodes are returned as an array. In scalar context the function will return a XML::LibXML::NamedNodeMap object.

lookupNamespaceURI

Find a namespace URI by its prefix starting at the current node.

lookupNamespacePrefix

Find a namespace prefix by its URI starting at the current node.

NOTE Only the namespace URIs are ment to be unique. The prefix is only document related. also document might has more than a single prefix defined for a namespace.

iterator

This function returns a new iterator object based with the current element as first element. This iterator can be used for linear tree walking.

$node->iterator->iterate( sub { shift;print $_[0]->nodeName(),"\n"; } );

The example will print all node names in the current subtree.

Check the XML::LibXML::Iterator man page for more details.

NOTE: The function has changed with version 1.53. Earlier versions did not return an iterator object, but ran the iterate() function directly.

normalize

This function normalizes adjacent textnodes. This function is not as strict as libxml2's xmlTextMerge() function, since it will not free a node that is still refered by the perl layer.

getNamespaces

If a node has any namespaces defined, this function will return these namespaces. Note, that this will not return all namespaces that are in scope, but only the ones declares explicitly for that node.

Although getNamespaces is available for all nodes, it makes only sense if used with element nodes.

removeChildNodes

This function is not specified for any DOM level: It removes all childnodes from a node in a single step. Other than the libxml2 function itself (xmlFreeNodeList), this function will not imediatly remove the nodes from the memory. This safes one from getting memory violations, if there are nodes still refered from the Perl level.

AUTHOR

Matt Sergeant, Christian Glahn

SEE ALSO

XML::LibXML, XML::LibXML::Element, XML::LibXML::Text, XML::LibXML::Comment, XML::LibXML::Attr, XML::LibXML::DocumentFragment

VERSION

1.53