.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::LibXML::Node 3"
.TH XML::LibXML::Node 3 "2016-07-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::LibXML::Node \- Abstract Base Class of XML::LibXML Nodes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use XML::LibXML;
\&
\&  $name = $node\->nodeName;
\&  $node\->setNodeName( $newName );
\&  $bool = $node\->isSameNode( $other_node );
\&  $bool = $node\->isEqual( $other_node );
\&  $num = $node\->unique_key;
\&  $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( $childnode );
\&  $node = $parent\->addNewChild( $nsURI, $name );
\&  $node\->addSibling($newNode);
\&  $newnode =$node\->cloneNode( $deep );
\&  $parentnode = $node\->parentNode;
\&  $nextnode = $node\->nextSibling();
\&  $nextnode = $node\->nextNonBlankSibling();
\&  $prevnode = $node\->previousSibling();
\&  $prevnode = $node\->previousNonBlankSibling();
\&  $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_expression );
\&  $result = $node\->find( $xpath );
\&  print $node\->findvalue( $xpath );
\&  $bool = $node\->exists( $xpath_expression );
\&  @childnodes = $node\->childNodes();
\&  @childnodes = $node\->nonBlankChildNodes();
\&  $xmlstring = $node\->toString($format,$docencoding);
\&  $c14nstring = $node\->toStringC14N();
\&  $c14nstring = $node\->toStringC14N($with_comments, $xpath_expression , $xpath_context);
\&  $c14nstring = $node\->toStringC14N_v1_1();
\&  $c14nstring = $node\->toStringC14N_v1_1($with_comments, $xpath_expression , $xpath_context);
\&  $ec14nstring = $node\->toStringEC14N();
\&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
\&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
\&  $str = $doc\->serialize($format);
\&  $localname = $node\->localname;
\&  $nameprefix = $node\->prefix;
\&  $uri = $node\->namespaceURI();
\&  $boolean = $node\->hasAttributes();
\&  @attributelist = $node\->attributes();
\&  $URI = $node\->lookupNamespaceURI( $prefix );
\&  $prefix = $node\->lookupNamespacePrefix( $URI );
\&  $node\->normalize;
\&  @nslist = $node\->getNamespaces;
\&  $node\->removeChildNodes();
\&  $strURI = $node\->baseURI();
\&  $node\->setBaseURI($strURI);
\&  $node\->nodePath();
\&  $lineno = $node\->line_number();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::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 \*(L"unbound\*(R" nodes.
.SH "METHODS"
.IX Header "METHODS"
Many functions listed here are extensively documented in the \s-1DOM\s0 Level 3 specification (<http://www.w3.org/TR/DOM\-Level\-3\-Core/>). Please refer to the specification for extensive documentation.
.IP "nodeName" 4
.IX Item "nodeName"
.Vb 1
\&  $name = $node\->nodeName;
.Ve
.Sp
Returns the node's name. This function is aware of namespaces and returns the
full name of the current node (\f(CW\*(C`prefix:localname\*(C'\fR).
.Sp
Since 1.62 this function also returns the correct \s-1DOM\s0 names for node types with
constant names, namely: #text, #cdata\-section, #comment, #document,
#document\-fragment.
.IP "setNodeName" 4
.IX Item "setNodeName"
.Vb 1
\&  $node\->setNodeName( $newName );
.Ve
.Sp
In very limited situations, it is useful to change a nodes name. In the \s-1DOM\s0
specification this should throw an error. This Function is aware of namespaces.
.IP "isSameNode" 4
.IX Item "isSameNode"
.Vb 1
\&  $bool = $node\->isSameNode( $other_node );
.Ve
.Sp
returns \s-1TRUE \\fIs0\fR\|(1) if the given nodes refer to the same node structure, otherwise
\&\s-1FALSE \\fIs0\fR\|(0) is returned.
.IP "isEqual" 4
.IX Item "isEqual"
.Vb 1
\&  $bool = $node\->isEqual( $other_node );
.Ve
.Sp
deprecated version of \fIisSameNode()\fR.
.Sp
\&\fI\s-1NOTE\s0\fR isEqual will change behaviour to follow the \s-1DOM\s0 specification
.IP "unique_key" 4
.IX Item "unique_key"
.Vb 1
\&  $num = $node\->unique_key;
.Ve
.Sp
This function is not specified for any \s-1DOM\s0 level. It returns a key guaranteed
to be unique for this node, and to always be the same value for this node. In
other words, two node objects return the same key if and only if isSameNode
indicates that they are the same node.
.Sp
The returned key value is useful as a key in hashes.
.IP "nodeValue" 4
.IX Item "nodeValue"
.Vb 1
\&  $content = $node\->nodeValue;
.Ve
.Sp
If the node has any content (such as stored in a \f(CW\*(C`text node\*(C'\fR) it can get requested through this function.
.Sp
\&\fI\s-1NOTE:\s0\fR Element Nodes have no content per definition. To get the text value of an
Element use \fItextContent()\fR instead!
.IP "textContent" 4
.IX Item "textContent"
.Vb 1
\&  $content = $node\->textContent;
.Ve
.Sp
this function returns the content of all text nodes in the descendants of the
given node as specified in \s-1DOM.\s0
.IP "nodeType" 4
.IX Item "nodeType"
.Vb 1
\&  $type = $node\->nodeType;
.Ve
.Sp
Return a numeric value representing the node type of this node. The module
XML::LibXML by default exports constants for the node types (see the \s-1EXPORT\s0
section in the XML::LibXML manual page).
.IP "unbindNode" 4
.IX Item "unbindNode"
.Vb 1
\&  $node\->unbindNode();
.Ve
.Sp
Unbinds the Node from its siblings and Parent, but not from the Document it
belongs to. If the node is not inserted into the \s-1DOM\s0 afterwards, it will be
lost after the program terminates. From a low level view, the unbound node is
stripped from the context it is and inserted into a (hidden) document-fragment.
.IP "removeChild" 4
.IX Item "removeChild"
.Vb 1
\&  $childnode = $node\->removeChild( $childnode );
.Ve
.Sp
This will unbind the Child Node from its parent \f(CW$node\fR. The function returns the unbound node. If \f(CW\*(C`oldNode\*(C'\fR is not a child of the given Node the function will fail.
.IP "replaceChild" 4
.IX Item "replaceChild"
.Vb 1
\&  $oldnode = $node\->replaceChild( $newNode, $oldNode );
.Ve
.Sp
Replaces the \f(CW$oldNode\fR with the \f(CW$newNode\fR. The \f(CW$oldNode\fR will be unbound from the Node. This function differs from the \s-1DOM L2\s0
specification, in the case, if the new node is not part of the document, the
node will be imported first.
.IP "replaceNode" 4
.IX Item "replaceNode"
.Vb 1
\&  $node\->replaceNode($newNode);
.Ve
.Sp
This function is very similar to \fIreplaceChild()\fR, but it replaces the node
itself rather than a childnode. This is useful if a node found by any XPath
function, should be replaced.
.IP "appendChild" 4
.IX Item "appendChild"
.Vb 1
\&  $childnode = $node\->appendChild( $childnode );
.Ve
.Sp
The function will add the \f(CW$childnode\fR to the end of \f(CW$node\fR's children. The function should fail, if the new childnode is already a child
of \f(CW$node\fR. This function differs from the \s-1DOM L2\s0 specification, in the case, if the new
node is not part of the document, the node will be imported first.
.IP "addChild" 4
.IX Item "addChild"
.Vb 1
\&  $childnode = $node\->addChild( $childnode );
.Ve
.Sp
As an alternative to \fIappendChild()\fR one can use the \fIaddChild()\fR function. This
function is a bit faster, because it avoids all \s-1DOM\s0 conformity checks.
Therefore this function is quite useful if one builds \s-1XML\s0 documents in memory
where the order and ownership (\f(CW\*(C`ownerDocument\*(C'\fR) is assured.
.Sp
\&\fIaddChild()\fR uses libxml2's own \fIxmlAddChild()\fR 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 as well 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 of this action, the perl instance is still
available. XML::LibXML will catch the loss of a node and refuse to run any
function called on that node.
.Sp
.Vb 4
\&  my $t1 = $doc\->createTextNode( "foo" );
\&   my $t2 = $doc\->createTextNode( "bar" );
\&   $t1\->addChild( $t2 );       # is OK
\&   my $val = $t2\->nodeValue(); # will fail, script dies
.Ve
.Sp
Also \fIaddChild()\fR will not check if 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.
.Sp
Although this sounds like a lot of trouble, \fIaddChild()\fR is useful if a document
is built from a stream, such as happens sometimes in \s-1SAX\s0 handlers or filters.
.Sp
If you are not sure about the source of your nodes, you better stay with
\&\fIappendChild()\fR, because this function is more user friendly in the sense of
being more error tolerant.
.IP "addNewChild" 4
.IX Item "addNewChild"
.Vb 1
\&  $node = $parent\->addNewChild( $nsURI, $name );
.Ve
.Sp
Similar to \f(CW\*(C`addChild()\*(C'\fR, this function uses low level libxml2 functionality to provide faster
interface for \s-1DOM\s0 building. \fI\fIaddNewChild()\fI\fR uses \f(CW\*(C`xmlNewChild()\*(C'\fR to create a new node on a given parent element.
.Sp
\&\fIaddNewChild()\fR has two parameters \f(CW$nsURI\fR and \f(CW$name\fR, where \f(CW$nsURI\fR is an
(optional) namespace \s-1URI.\s0 \f(CW$name\fR is the fully qualified element name;
\&\fIaddNewChild()\fR will determine the correct prefix if necessary.
.Sp
The function returns the newly created node.
.Sp
This function is very useful for \s-1DOM\s0 building, where a created node can be
directly associated with its parent. \fI\s-1NOTE\s0\fR this function is not part of the \s-1DOM\s0 specification and its use will limit your
code to XML::LibXML.
.IP "addSibling" 4
.IX Item "addSibling"
.Vb 1
\&  $node\->addSibling($newNode);
.Ve
.Sp
\&\fIaddSibling()\fR allows adding an additional node to the end of a nodelist, defined
by the given node.
.IP "cloneNode" 4
.IX Item "cloneNode"
.Vb 1
\&  $newnode =$node\->cloneNode( $deep );
.Ve
.Sp
\&\fIcloneNode\fR creates a copy of \f(CW$node\fR. When \f(CW$deep\fR is set to 1 (true) the function will copy all child nodes as well.
If \f(CW$deep\fR is 0 only the current node will be copied. Note that in case of
element, attributes are copied even if \f(CW$deep\fR is 0.
.Sp
Note that the behavior of this function for \f(CW$deep\fR=0 has changed in 1.62 in
order to be consistent with the \s-1DOM\s0 spec (in older versions attributes and
namespace information was not copied for elements).
.IP "parentNode" 4
.IX Item "parentNode"
.Vb 1
\&  $parentnode = $node\->parentNode;
.Ve
.Sp
Returns simply the Parent Node of the current node.
.IP "nextSibling" 4
.IX Item "nextSibling"
.Vb 1
\&  $nextnode = $node\->nextSibling();
.Ve
.Sp
Returns the next sibling if any .
.IP "nextNonBlankSibling" 4
.IX Item "nextNonBlankSibling"
.Vb 1
\&  $nextnode = $node\->nextNonBlankSibling();
.Ve
.Sp
Returns the next non-blank sibling if any (a node is blank if it is a Text or
\&\s-1CDATA\s0 node consisting of whitespace only). This method is not defined by \s-1DOM.\s0
.IP "previousSibling" 4
.IX Item "previousSibling"
.Vb 1
\&  $prevnode = $node\->previousSibling();
.Ve
.Sp
Analogous to \fIgetNextSibling\fR the function returns the previous sibling if any.
.IP "previousNonBlankSibling" 4
.IX Item "previousNonBlankSibling"
.Vb 1
\&  $prevnode = $node\->previousNonBlankSibling();
.Ve
.Sp
Returns the previous non-blank sibling if any (a node is blank if it is a Text
or \s-1CDATA\s0 node consisting of whitespace only). This method is not defined by
\&\s-1DOM.\s0
.IP "hasChildNodes" 4
.IX Item "hasChildNodes"
.Vb 1
\&  $boolean = $node\->hasChildNodes();
.Ve
.Sp
If the current node has child nodes this function returns \s-1TRUE \\fIs0\fR\|(1), otherwise
it returns \s-1FALSE \s0(0, not undef).
.IP "firstChild" 4
.IX Item "firstChild"
.Vb 1
\&  $childnode = $node\->firstChild;
.Ve
.Sp
If a node has child nodes this function will return the first node in the child
list.
.IP "lastChild" 4
.IX Item "lastChild"
.Vb 1
\&  $childnode = $node\->lastChild;
.Ve
.Sp
If the \f(CW$node\fR has child nodes this function returns the last child node.
.IP "ownerDocument" 4
.IX Item "ownerDocument"
.Vb 1
\&  $documentnode = $node\->ownerDocument;
.Ve
.Sp
Through this function it is always possible to access the document the current
node is bound to.
.IP "getOwner" 4
.IX Item "getOwner"
.Vb 1
\&  $node = $node\->getOwner;
.Ve
.Sp
This function returns the node the current node is associated with. In most
cases this will be a document node or a document fragment node.
.IP "setOwnerDocument" 4
.IX Item "setOwnerDocument"
.Vb 1
\&  $node\->setOwnerDocument( $doc );
.Ve
.Sp
This function binds a node to another \s-1DOM.\s0 This method unbinds the node first,
if it is already bound to another document.
.Sp
This function is the opposite calling of XML::LibXML::Document's \fIadoptNode()\fR function. Because of this it has the same limitations with
Entity References as \fIadoptNode()\fR.
.IP "insertBefore" 4
.IX Item "insertBefore"
.Vb 1
\&  $node\->insertBefore( $newNode, $refNode );
.Ve
.Sp
The method inserts \f(CW$newNode\fR before \f(CW$refNode\fR. If \f(CW$refNode\fR is undefined, the newNode will be set as the new last child of the parent node.
This function differs from the \s-1DOM L2\s0 specification, in the case, if the new
node is not part of the document, the node will be imported first,
automatically.
.Sp
\&\f(CW$refNode\fR has to be passed to the function even if it is undefined:
.Sp
.Vb 2
\&  $node\->insertBefore( $newNode, undef ); # the same as $node\->appendChild( $newNode );
\&   $node\->insertBefore( $newNode ); # wrong
.Ve
.Sp
Note, that the reference node has to be a direct child of the node the function
is called on. Also, \f(CW$newChild\fR is not allowed to be an ancestor of the new
parent node.
.IP "insertAfter" 4
.IX Item "insertAfter"
.Vb 1
\&  $node\->insertAfter( $newNode, $refNode );
.Ve
.Sp
The method inserts \f(CW$newNode\fR after \f(CW$refNode\fR. If \f(CW$refNode\fR is undefined, the newNode will be set as the new last child of the parent node.
.Sp
Note, that \f(CW$refNode\fR has to be passed explicitly even if it is undef.
.IP "findnodes" 4
.IX Item "findnodes"
.Vb 1
\&  @nodes = $node\->findnodes( $xpath_expression );
.Ve
.Sp
\&\fIfindnodes\fR evaluates the xpath expression (XPath 1.0) on the current node and returns the
resulting node set as an array. In scalar context, returns an XML::LibXML::NodeList object.
.Sp
The xpath expression can be passed either as a string, or as a XML::LibXML::XPathExpression object.
.Sp
\&\fI\s-1NOTE ON NAMESPACES AND XPATH\s0\fR:
.Sp
A common mistake about XPath is to assume that node tests consisting of an
element name with no prefix match elements in the default namespace. This
assumption is wrong \- by XPath specification, such node tests can only match
elements that are in no (i.e. null) namespace.
.Sp
So, for example, one cannot match the root element of an \s-1XHTML\s0 document with \f(CW\*(C`$node\->find(\*(Aq/html\*(Aq)\*(C'\fR since \f(CW\*(Aq/html\*(Aq\fR would only match if the root element \f(CW\*(C`<html>\*(C'\fR had no namespace, but all \s-1XHTML\s0 elements belong to the namespace
http://www.w3.org/1999/xhtml. (Note that \f(CW\*(C`xmlns="..."\*(C'\fR namespace declarations can also be specified in a \s-1DTD,\s0 which makes the
situation even worse, since the \s-1XML\s0 document looks as if there was no default
namespace).
.Sp
There are several possible ways to deal with namespaces in XPath:
.RS 4
.IP "\(bu" 4
The recommended way is to use the XML::LibXML::XPathContext module to define an explicit context for XPath evaluation, in which a document
independent prefix-to-namespace mapping can be defined. For example:
.Sp
.Vb 3
\&  my $xpc = XML::LibXML::XPathContext\->new;
\&  $xpc\->registerNs(\*(Aqx\*(Aq, \*(Aqhttp://www.w3.org/1999/xhtml\*(Aq);
\&  $xpc\->find(\*(Aq/x:html\*(Aq,$node);
.Ve
.IP "\(bu" 4
Another possibility is to use prefixes declared in the queried document (if
known). If the document declares a prefix for the namespace in question (and
the context node is in the scope of the declaration), \f(CW\*(C`XML::LibXML\*(C'\fR allows you to use the prefix in the XPath expression, e.g.:
.Sp
.Vb 1
\&  $node\->find(\*(Aq/x:html\*(Aq);
.Ve
.RE
.RS 4
.Sp
See also XML::LibXML::XPathContext\->findnodes.
.RE
.IP "find" 4
.IX Item "find"
.Vb 1
\&  $result = $node\->find( $xpath );
.Ve
.Sp
\&\fIfind\fR evaluates the XPath 1.0 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 \*(L"1 * 3 + 52\*(R" results in a XML::LibXML::Number object being returned. Other expressions might return an XML::LibXML::Boolean object, or an XML::LibXML::Literal object (a string). Each of those objects uses Perl's overload feature to \*(L"do
the right thing\*(R" in different contexts.
.Sp
The xpath expression can be passed either as a string, or as a XML::LibXML::XPathExpression object.
.Sp
See also XML::LibXML::XPathContext\->find.
.IP "findvalue" 4
.IX Item "findvalue"
.Vb 1
\&  print $node\->findvalue( $xpath );
.Ve
.Sp
\&\fIfindvalue\fR is exactly equivalent to:
.Sp
.Vb 1
\&  $node\->find( $xpath )\->to_literal;
.Ve
.Sp
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 \s-1XSLT\s0's <xsl:value\-of
select=\*(L"some_xpath\*(R"/>.
.Sp
See also XML::LibXML::XPathContext\->findvalue.
.Sp
The xpath expression can be passed either as a string, or as a XML::LibXML::XPathExpression object.
.IP "exists" 4
.IX Item "exists"
.Vb 1
\&  $bool = $node\->exists( $xpath_expression );
.Ve
.Sp
This method behaves like \fIfindnodes\fR, except that it only returns a boolean value (1 if the expression matches a
node, 0 otherwise) and may be faster than \fIfindnodes\fR, because the XPath evaluation may stop early on the first match (this is true
for libxml2 >= 2.6.27).
.Sp
For XPath expressions that do not return node-set, the method returns true if
the returned value is a non-zero number or a non-empty string.
.IP "childNodes" 4
.IX Item "childNodes"
.Vb 1
\&  @childnodes = $node\->childNodes();
.Ve
.Sp
\&\fIchildNodes\fR implements a more intuitive interface to the childnodes of the current node. It
enables you to pass all children directly to a \f(CW\*(C`map\*(C'\fR or \f(CW\*(C`grep\*(C'\fR. If this function is called in scalar context, a XML::LibXML::NodeList object will be returned.
.IP "nonBlankChildNodes" 4
.IX Item "nonBlankChildNodes"
.Vb 1
\&  @childnodes = $node\->nonBlankChildNodes();
.Ve
.Sp
This is like \fIchildNodes\fR, but returns only non-blank nodes (where a node is blank if it is a Text or
\&\s-1CDATA\s0 node consisting of whitespace only). This method is not defined by \s-1DOM.\s0
.IP "toString" 4
.IX Item "toString"
.Vb 1
\&  $xmlstring = $node\->toString($format,$docencoding);
.Ve
.Sp
This method is similar to the method \f(CW\*(C`toString\*(C'\fR of a XML::LibXML::Document but for a single node. It returns a string consisting of \s-1XML\s0 serialization of
the given node and all its descendants. Unlike \f(CW\*(C`XML::LibXML::Document::toString\*(C'\fR, in this case the resulting string is by default a character string (\s-1UTF\-8\s0
encoded with \s-1UTF8\s0 flag on). An optional flag \f(CW$format\fR controls indentation, as
in \f(CW\*(C`XML::LibXML::Document::toString\*(C'\fR. If the second optional \f(CW$docencoding\fR flag is true, the result will be a byte
string in the document encoding (see \f(CW\*(C`XML::LibXML::Document::actualEncoding\*(C'\fR).
.IP "toStringC14N" 4
.IX Item "toStringC14N"
.Vb 2
\&  $c14nstring = $node\->toStringC14N();
\&  $c14nstring = $node\->toStringC14N($with_comments, $xpath_expression , $xpath_context);
.Ve
.Sp
The function is similar to \fItoString()\fR. Instead of simply serializing the
document tree, it transforms it as it is specified in the \s-1XML\-C14N\s0
Specification (see <http://www.w3.org/TR/xml\-c14n>). Such transformation is known as canonization.
.Sp
If \f(CW$with_comments\fR is 0 or not defined, the result-document will not contain any
comments that exist in the original document. To include comments into the
canonized document, \f(CW$with_comments\fR has to be set to 1.
.Sp
The parameter \f(CW$xpath_expression\fR defines the nodeset of nodes that should be
visible in the resulting document. This can be used to filter out some nodes.
One has to note, that only the nodes that are part of the nodeset, will be
included into the result-document. Their child-nodes will not exist in the
resulting document, unless they are part of the nodeset defined by the xpath
expression.
.Sp
If \f(CW$xpath_expression\fR is omitted or empty, \fItoStringC14N()\fR will include all nodes
in the given sub-tree, using the following XPath expressions: with comments
.Sp
.Vb 1
\&  (. | .//node() | .//@* | .//namespace::*)
.Ve
.Sp
and without comments
.Sp
.Vb 1
\&  (. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
.Ve
.Sp
An optional parameter \f(CW$xpath_context\fR can be used to pass an XML::LibXML::XPathContext object defining the context for evaluation of \f(CW$xpath_expression\fR. This is useful
for mapping namespace prefixes used in the XPath expression to namespace URIs.
Note, however, that \f(CW$node\fR will be used as the context node for the evaluation,
not the context node of \f(CW$xpath_context\fR!
.IP "toStringC14N_v1_1" 4
.IX Item "toStringC14N_v1_1"
.Vb 2
\&  $c14nstring = $node\->toStringC14N_v1_1();
\&  $c14nstring = $node\->toStringC14N_v1_1($with_comments, $xpath_expression , $xpath_context);
.Ve
.Sp
This function behaves like \fItoStringC14N()\fR except that it uses the
\&\*(L"\s-1XML_C14N_1_1\*(R"\s0 constant for canonicalising using the \*(L"C14N 1.1 spec\*(R".
.IP "toStringEC14N" 4
.IX Item "toStringEC14N"
.Vb 3
\&  $ec14nstring = $node\->toStringEC14N();
\&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
\&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
.Ve
.Sp
The function is similar to \fItoStringC14N()\fR but follows the \s-1XML\-EXC\-C14N\s0
Specification (see <http://www.w3.org/TR/xml\-exc\-c14n>) for exclusive canonization of \s-1XML.\s0
.Sp
The arguments \f(CW$with_comments\fR, \f(CW$xpath_expression\fR, \f(CW$xpath_context\fR are as in
\&\fItoStringC14N()\fR. An \s-1ARRAY\s0 reference can be passed as the last argument
\&\f(CW$inclusive_prefix_list\fR, listing namespace prefixes that are to be handled in
the manner described by the Canonical \s-1XML\s0 Recommendation (i.e. preserved in the
output even if the namespace is not used). C.f. the spec for details.
.IP "serialize" 4
.IX Item "serialize"
.Vb 1
\&  $str = $doc\->serialize($format);
.Ve
.Sp
An alias for \fItoString()\fR. This function was name added to be more consistent
with libxml2.
.IP "serialize_c14n" 4
.IX Item "serialize_c14n"
An alias for \fItoStringC14N()\fR.
.IP "serialize_exc_c14n" 4
.IX Item "serialize_exc_c14n"
An alias for \fItoStringEC14N()\fR.
.IP "localname" 4
.IX Item "localname"
.Vb 1
\&  $localname = $node\->localname;
.Ve
.Sp
Returns the local name of a tag. This is the part behind the colon.
.IP "prefix" 4
.IX Item "prefix"
.Vb 1
\&  $nameprefix = $node\->prefix;
.Ve
.Sp
Returns the prefix of a tag. This is the part before the colon.
.IP "namespaceURI" 4
.IX Item "namespaceURI"
.Vb 1
\&  $uri = $node\->namespaceURI();
.Ve
.Sp
returns the \s-1URI\s0 of the current namespace.
.IP "hasAttributes" 4
.IX Item "hasAttributes"
.Vb 1
\&  $boolean = $node\->hasAttributes();
.Ve
.Sp
returns 1 (\s-1TRUE\s0) if the current node has any attributes set, otherwise 0
(\s-1FALSE\s0) is returned.
.IP "attributes" 4
.IX Item "attributes"
.Vb 1
\&  @attributelist = $node\->attributes();
.Ve
.Sp
This function returns all attributes and namespace declarations assigned to the
given node.
.Sp
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.
.Sp
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.
.IP "lookupNamespaceURI" 4
.IX Item "lookupNamespaceURI"
.Vb 1
\&  $URI = $node\->lookupNamespaceURI( $prefix );
.Ve
.Sp
Find a namespace \s-1URI\s0 by its prefix starting at the current node.
.IP "lookupNamespacePrefix" 4
.IX Item "lookupNamespacePrefix"
.Vb 1
\&  $prefix = $node\->lookupNamespacePrefix( $URI );
.Ve
.Sp
Find a namespace prefix by its \s-1URI\s0 starting at the current node.
.Sp
\&\fI\s-1NOTE\s0\fR Only the namespace URIs are meant to be unique. The prefix is only document
related. Also the document might have more than a single prefix defined for a
namespace.
.IP "normalize" 4
.IX Item "normalize"
.Vb 1
\&  $node\->normalize;
.Ve
.Sp
This function normalizes adjacent text nodes. This function is not as strict as
libxml2's \fIxmlTextMerge()\fR function, since it will not free a node that is still
referenced by the perl layer.
.IP "getNamespaces" 4
.IX Item "getNamespaces"
.Vb 1
\&  @nslist = $node\->getNamespaces;
.Ve
.Sp
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 declared explicitly for that node.
.Sp
Although getNamespaces is available for all nodes, it only makes sense if used
with element nodes.
.IP "removeChildNodes" 4
.IX Item "removeChildNodes"
.Vb 1
\&  $node\->removeChildNodes();
.Ve
.Sp
This function is not specified for any \s-1DOM\s0 level: It removes all childnodes
from a node in a single step. Other than the libxml2 function itself
(xmlFreeNodeList), this function will not immediately remove the nodes from the
memory. This saves one from getting memory violations, if there are nodes still
referred to from the Perl level.
.IP "baseURI ()" 4
.IX Item "baseURI ()"
.Vb 1
\&  $strURI = $node\->baseURI();
.Ve
.Sp
Searches for the base \s-1URL\s0 of the node. The method should work on both \s-1XML\s0 and
\&\s-1HTML\s0 documents even if base mechanisms for these are completely different. It
returns the base as defined in \s-1RFC 2396\s0 sections \*(L"5.1.1. Base \s-1URI\s0 within
Document Content\*(R" and \*(L"5.1.2. Base \s-1URI\s0 from the Encapsulating Entity\*(R". However
it does not return the document base (5.1.3), use method \f(CW\*(C`URI\*(C'\fR of \f(CW\*(C`XML::LibXML::Document\*(C'\fR for this.
.IP "setBaseURI ($strURI)" 4
.IX Item "setBaseURI ($strURI)"
.Vb 1
\&  $node\->setBaseURI($strURI);
.Ve
.Sp
This method only does something useful for an element node in an \s-1XML\s0 document.
It sets the xml:base attribute on the node to \f(CW$strURI\fR, which effectively sets
the base \s-1URI\s0 of the node to the same value.
.Sp
Note: For \s-1HTML\s0 documents this behaves as if the document was \s-1XML\s0 which may not
be desired, since it does not effectively set the base \s-1URI\s0 of the node. See \s-1RFC
2396\s0 appendix D for an example of how base \s-1URI\s0 can be specified in \s-1HTML.\s0
.IP "nodePath" 4
.IX Item "nodePath"
.Vb 1
\&  $node\->nodePath();
.Ve
.Sp
This function is not specified for any \s-1DOM\s0 level: It returns a canonical
structure based XPath for a given node.
.IP "line_number" 4
.IX Item "line_number"
.Vb 1
\&  $lineno = $node\->line_number();
.Ve
.Sp
This function returns the line number where the tag was found during parsing.
If a node is added to the document the line number is 0. Problems may occur, if
a node from one document is passed to another one.
.Sp
\&\s-1IMPORTANT:\s0 Due to limitations in the libxml2 library line numbers greater than
65535 will be returned as 65535. Please see <http://bugzilla.gnome.org/show_bug.cgi?id=325533> for more details.
.Sp
Note: \fIline_number()\fR is special to XML::LibXML and not part of the \s-1DOM\s0
specification.
.Sp
If the line_numbers flag of the parser was not activated before parsing,
\&\fIline_number()\fR will always return 0.
.SH "AUTHORS"
.IX Header "AUTHORS"
Matt Sergeant,
Christian Glahn,
Petr Pajas
.SH "VERSION"
.IX Header "VERSION"
2.0128
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
2001\-2007, AxKit.com Ltd.
.PP
2002\-2006, Christian Glahn.
.PP
2006\-2009, Petr Pajas.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.