=head1 NAME

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

=head1 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->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();


=head1 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.




=head2 Methods

=over 4

=item B<nodeName>




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




=item B<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.




=item B<isSameNode>




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




=item B<isEqual>




depraced version of isSameNode().





B<NOTE> isEqual will change behaviour to
follow the DOM specification




=item B<nodeValue>




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





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




=item B<textContent>




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




=item B<nodeType>




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




=item B<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.




=item B<removeChild>




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




=item B<replaceChild>




Replaces the I<$oldNode> with the
I<$newNode>. The I<$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.




=item B<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.




=item B<appendChild>




The function will add the I<$childnode> to
the end of I<$node>'s children. The function
should fail, if the new childnode is allready a
child of I<$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.




=item B<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 (I<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.




=item B<addSibling>




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




=item B<cloneNode>




B<cloneNode> creates a copy of
I<$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.





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



=item B<parentNode>




Returns simply the Parent Node of the current
node.




=item B<nextSibling>




Returns the next sibling if any .




=item B<previousSibling>




Analogous to B<getNextSibling> the function
returns the previous sibling if any.




=item B<hasChildNodes>




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




=item B<firstChild>




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




=item B<lastChild>




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




=item B<ownerDocument>




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




=item B<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.




=item B<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().




=item B<insertBefore>




The method inserts I<$newNode> before
I<$refNode>. If I<$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.




=item B<insertAfter>




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




=item B<findnodes>




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




=item B<find>




B<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
I<XML::LibXML::Number> object being
returned. Other expressions might return a
I<XML::LibXML::Boolean> object, or a
I<XML::LibXML::Literal> object (a
string). Each of those objects uses Perl's
overload feature to "do the right thing" in
different contexts.




=item B<findvalue>




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




=item B<childNodes>




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




=item B<toString>




This is the equivalent to
I<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.




=item B<localname>




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




=item B<prefix>




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




=item B<namespaceURI>




returns the URI of the current namespace.




=item B<hasAttributes>




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




=item B<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
I<XML::LibXML::NamedNodeMap> object.




=item B<lookupNamespaceURI>




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




=item B<lookupNamespacePrefix>




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





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




=item B<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 I<XML::LibXML::Iterator> man page
for more details.





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




=item B<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.




=item B<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.




=item B<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. 





=back

=head1 AUTHOR

Matt Sergeant, Christian Glahn

=head1 SEE ALSO

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

=head1 VERSION

1.53

