NAME

XML::LibXML::Node - "virtual" Base Class DOM-Nodes

synopsis

use XML::LibXML

$name = $node->getName();
$name = $node->nodeName;
$node->setName( $newName );
$bool = $node->isSameNode( $other_node );
$bool = $node->isEqual( $other_node );
$content = $node->getData()
$content = $node->nodeValue;
$type = $node->getType();
$type = $node->nodeType;
$node->unbindNode()
$childnode = $node->removeChild( $childnode )
$oldnode = $node->replaceChild( $newNode, $oldNode )
$node->replaceNode($newNode);
$childnode = $node->appendChild( $childnode )
$node->addSibling($newNode);
$newnode =$node->cloneNode( $deep )
@attrs =$node->attributes;
$parentnode = $node->getParentNode();
$parentnode = $node->parentNode;
$nextnode = $node->getNextSibling()
$nextnode = $node->nextSibling()
$nextnode = $node->getPreviousSibling()
$prevnode = $node->previousSibling()
$boolean = $node->hasChildNodes();
$childnode = $node->getFirstChild()
$childnode = $node->firstChild;
$childnode = $node->getLastChild()
$childnode = $node->lastChild;
$dom = $node->getOwnerDocument()
$documentnode = $node->ownerDocument;
$node = $node->getOwner;
$node->setOwnerDocument( $dom );
$node->insertBefore( $newNode, $refNode )
$node->insertAfter( $newNode, $refNode )
@nodes = $node->findnodes( $xpath_statement );
$result = $node->find( $xpath );
print $node->findvalue( $xpath );
@children = $node->getChildnodes();
@childnodes = $node->childNodes;
$xmlstring = $node->toString();
$name = $node->getLocalName();
$localname = $node->localname;
$name = $node->getPrefix();
$nameprefix = $node->prefix;
$uri = $node->getNamespaceURI()
$boolean = $node->hasAttributes();
@attributelist = $node->attributesNS( $URI );
@nslist = $node->getNamespaces();
$node->iterator( \&nodehandler );
$node->normalize

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

getName

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

nodeName

Alias for getName().

setName

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

isSameNode

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

isEqual

depraced version of isSameNode(). NOTE isEqual will change behaviour to follow the DOM specification

getData

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

nodeValue

Alias for getData

getType

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.

nodeType

Alias for getType.

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.

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.

attributes

This function returns all attributes assigned to the given node. if this function is called in scalar context, it will return a XML::LibXML::NodeList.

getParentNode

Returns simply the Parent Node of the current node.

parentNode

Alias for getParentNode()

getNextSibling

Returns the next sibling if any .

nextSibling

Alias for getNextSibling()

getPreviousSibling

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

previousSibling

Alias for getPreviousSibling()

hasChildNodes

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

getFirstChild

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

firstChild

Alias for getFirstChild()

getLastChild

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

lastChild

Alias for getLastChild()

getOwnerDocument

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

ownerDocument

Alias for getOwnerDocument()

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.

Note that this is only safe with single nodes but not with subtrees. In case of subtrees one should use XML::LibXML::Document's importNode method.

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 <xsl:value-of select="some_xpath"/>.

getChildnodes

Alias for childNodes()

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, the number of childnodes 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.

There is no formating implemented yet, which may cause an unreadable output.

getLocalName

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

localname

Alias for getLocalName()

getPrefix

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

prefix

Alias for getPrefix()

getNamespaceURI

returns the URI of the current namespace.

hasAttributes

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

getAttributesNS

returns all attributes for the given namespace. (not implemented yet)

getNamespaces

returns all the namespace declaration nodes bound to this node. The items are instances of the class XML::LibXML::Namespace.

iterator

This is little helper function, that lets one define a function, that will be processed on the current node and all its children. The function will recieve as its only parameter the node to proceed. The function uses inorder proceeding to traverse the subtree. Therefore you can't reach the childnodes anymore, if the nodehandler removes childnodes.

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

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

The iterator function will return the return value of the nodehandler while processing the last child of the current node.

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.

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