local-lib5/man/man3/XML::LibXML::Node.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XML::LibXML::Node 3"
 127 .TH XML::LibXML::Node 3 "2009-10-07" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::LibXML::Node \- Abstract Base Class of XML::LibXML Nodes
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use XML::LibXML;
 138 \&
 139 \&  $name = $node\->nodeName;
 140 \&  $node\->setNodeName( $newName );
 141 \&  $bool = $node\->isSameNode( $other_node );
 142 \&  $bool = $node\->isEqual( $other_node );
 143 \&  $content = $node\->nodeValue;
 144 \&  $content = $node\->textContent;
 145 \&  $type = $node\->nodeType;
 146 \&  $node\->unbindNode();
 147 \&  $childnode = $node\->removeChild( $childnode );
 148 \&  $oldnode = $node\->replaceChild( $newNode, $oldNode );
 149 \&  $node\->replaceNode($newNode);
 150 \&  $childnode = $node\->appendChild( $childnode );
 151 \&  $childnode = $node\->addChild( $chilnode );
 152 \&  $node = $parent\->addNewChild( $nsURI, $name );
 153 \&  $node\->addSibling($newNode);
 154 \&  $newnode =$node\->cloneNode( $deep );
 155 \&  $parentnode = $node\->parentNode;
 156 \&  $nextnode = $node\->nextSibling();
 157 \&  $nextnode = $node\->nextNonBlankSibling();
 158 \&  $prevnode = $node\->previousSibling();
 159 \&  $prevnode = $node\->previousNonBlankSibling();
 160 \&  $boolean = $node\->hasChildNodes();
 161 \&  $childnode = $node\->firstChild;
 162 \&  $childnode = $node\->lastChild;
 163 \&  $documentnode = $node\->ownerDocument;
 164 \&  $node = $node\->getOwner;
 165 \&  $node\->setOwnerDocument( $doc );
 166 \&  $node\->insertBefore( $newNode, $refNode );
 167 \&  $node\->insertAfter( $newNode, $refNode );
 168 \&  @nodes = $node\->findnodes( $xpath_expression );
 169 \&  $result = $node\->find( $xpath );
 170 \&  print $node\->findvalue( $xpath );
 171 \&  $bool = $node\->exists( $xpath_expression );
 172 \&  @childnodes = $node\->childNodes();
 173 \&  @childnodes = $node\->nonBlankChildNodes();
 174 \&  $xmlstring = $node\->toString($format,$docencoding);
 175 \&  $c14nstring = $node\->toStringC14N();
 176 \&  $c14nstring = $node\->toStringC14N($with_comments, $xpath_expression , $xpath_context);
 177 \&  $ec14nstring = $node\->toStringEC14N();
 178 \&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
 179 \&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
 180 \&  $str = $doc\->serialize($format);
 181 \&  $localname = $node\->localname;
 182 \&  $nameprefix = $node\->prefix;
 183 \&  $uri = $node\->namespaceURI();
 184 \&  $boolean = $node\->hasAttributes();
 185 \&  @attributelist = $node\->attributes();
 186 \&  $URI = $node\->lookupNamespaceURI( $prefix );
 187 \&  $prefix = $node\->lookupNamespacePrefix( $URI );
 188 \&  $node\->normalize;
 189 \&  @nslist = $node\->getNamespaces;
 190 \&  $node\->removeChildNodes();
 191 \&  $strURI = $node\->baseURI();
 192 \&  $node\->setBaseURI($strURI);
 193 \&  $node\->nodePath();
 194 \&  $lineno = $node\->line_number();
 195 .Ve
 196 .SH "DESCRIPTION"
 197 .IX Header "DESCRIPTION"
 198 XML::LibXML::Node defines functions that are common to all Node Types. A
 199 LibXML::Node should never be created standalone, but as an instance of a high
 200 level class such as LibXML::Element or LibXML::Text. The class itself should
 201 provide only common functionality. In XML::LibXML each node is part either of a
 202 document or a document-fragment. Because of this there is no node without a
 203 parent. This may causes confusion with \*(L"unbound\*(R" nodes.
 204 .SH "METHODS"
 205 .IX Header "METHODS"
 206 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.
 207 .IP "nodeName" 4
 208 .IX Item "nodeName"
 209 .Vb 1
 210 \&  $name = $node\->nodeName;
 211 .Ve
 212 .Sp
 213 Returns the node's name. This function is aware of namespaces and returns the
 214 full name of the current node (\f(CW\*(C`prefix:localname\*(C'\fR).
 215 .Sp
 216 Since 1.62 this function also returns the correct \s-1DOM\s0 names for node types with
 217 constant names, namely: #text, #cdata\-section, #comment, #document,
 218 #document\-fragment.
 219 .IP "setNodeName" 4
 220 .IX Item "setNodeName"
 221 .Vb 1
 222 \&  $node\->setNodeName( $newName );
 223 .Ve
 224 .Sp
 225 In very limited situations, it is useful to change a nodes name. In the \s-1DOM\s0
 226 specification this should throw an error. This Function is aware of namespaces.
 227 .IP "isSameNode" 4
 228 .IX Item "isSameNode"
 229 .Vb 1
 230 \&  $bool = $node\->isSameNode( $other_node );
 231 .Ve
 232 .Sp
 233 returns \s-1TRUE\s0 (1) if the given nodes refer to the same node structure, otherwise
 234 \&\s-1FALSE\s0 (0) is returned.
 235 .IP "isEqual" 4
 236 .IX Item "isEqual"
 237 .Vb 1
 238 \&  $bool = $node\->isEqual( $other_node );
 239 .Ve
 240 .Sp
 241 deprecated version of \fIisSameNode()\fR.
 242 .Sp
 243 \&\fI\s-1NOTE\s0\fR isEqual will change behaviour to follow the \s-1DOM\s0 specification
 244 .IP "nodeValue" 4
 245 .IX Item "nodeValue"
 246 .Vb 1
 247 \&  $content = $node\->nodeValue;
 248 .Ve
 249 .Sp
 250 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.
 251 .Sp
 252 \&\fI\s-1NOTE:\s0\fR Element Nodes have no content per definition. To get the text value of an
 253 Element use \fItextContent()\fR instead!
 254 .IP "textContent" 4
 255 .IX Item "textContent"
 256 .Vb 1
 257 \&  $content = $node\->textContent;
 258 .Ve
 259 .Sp
 260 this function returns the content of all text nodes in the descendants of the
 261 given node as specified in \s-1DOM\s0.
 262 .IP "nodeType" 4
 263 .IX Item "nodeType"
 264 .Vb 1
 265 \&  $type = $node\->nodeType;
 266 .Ve
 267 .Sp
 268 Return a numeric value representing the node type of this node. The module
 269 XML::LibXML by default exports constants for the node types (see the \s-1EXPORT\s0
 270 section in the XML::LibXML manual page).
 271 .IP "unbindNode" 4
 272 .IX Item "unbindNode"
 273 .Vb 1
 274 \&  $node\->unbindNode();
 275 .Ve
 276 .Sp
 277 Unbinds the Node from its siblings and Parent, but not from the Document it
 278 belongs to. If the node is not inserted into the \s-1DOM\s0 afterwards it will be lost
 279 after the program terminated. From a low level view, the unbound node is
 280 stripped from the context it is and inserted into a (hidden) document-fragment.
 281 .IP "removeChild" 4
 282 .IX Item "removeChild"
 283 .Vb 1
 284 \&  $childnode = $node\->removeChild( $childnode );
 285 .Ve
 286 .Sp
 287 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.
 288 .IP "replaceChild" 4
 289 .IX Item "replaceChild"
 290 .Vb 1
 291 \&  $oldnode = $node\->replaceChild( $newNode, $oldNode );
 292 .Ve
 293 .Sp
 294 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\s0 L2
 295 specification, in the case, if the new node is not part of the document, the
 296 node will be imported first.
 297 .IP "replaceNode" 4
 298 .IX Item "replaceNode"
 299 .Vb 1
 300 \&  $node\->replaceNode($newNode);
 301 .Ve
 302 .Sp
 303 This function is very similar to \fIreplaceChild()\fR, but it replaces the node
 304 itself rather than a childnode. This is useful if a node found by any XPath
 305 function, should be replaced.
 306 .IP "appendChild" 4
 307 .IX Item "appendChild"
 308 .Vb 1
 309 \&  $childnode = $node\->appendChild( $childnode );
 310 .Ve
 311 .Sp
 312 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
 313 of \f(CW$node\fR. This function differs from the \s-1DOM\s0 L2 specification, in the case, if the new
 314 node is not part of the document, the node will be imported first.
 315 .IP "addChild" 4
 316 .IX Item "addChild"
 317 .Vb 1
 318 \&  $childnode = $node\->addChild( $chilnode );
 319 .Ve
 320 .Sp
 321 As an alternative to \fIappendChild()\fR one can use the \fIaddChild()\fR function. This
 322 function is a bit faster, because it avoids all \s-1DOM\s0 conformity checks.
 323 Therefore this function is quite useful if one builds \s-1XML\s0 documents in memory
 324 where the order and ownership (\f(CW\*(C`ownerDocument\*(C'\fR) is assured.
 325 .Sp
 326 \&\fIaddChild()\fR uses libxml2's own \fIxmlAddChild()\fR function. Thus it has to be used
 327 with extra care: If a text node is added to a node and the node itself or its
 328 last childnode is as well a text node, the node to add will be merged with the
 329 one already available. The current node will be removed from memory after this
 330 action. Because perl is not aware of this action, the perl instance is still
 331 available. XML::LibXML will catch the loss of a node and refuse to run any
 332 function called on that node.
 333 .Sp
 334 .Vb 4
 335 \&  my $t1 = $doc\->createTextNode( "foo" );
 336 \&   my $t2 = $doc\->createTextNode( "bar" );
 337 \&   $t1\->addChild( $t2 );       # is OK
 338 \&   my $val = $t2\->nodeValue(); # will fail, script dies
 339 .Ve
 340 .Sp
 341 Also \fIaddChild()\fR will not check if the added node belongs to the same document
 342 as the node it will be added to. This could lead to inconsistent documents and
 343 in more worse cases even to memory violations, if one does not keep track of
 344 this issue.
 345 .Sp
 346 Although this sounds like a lot of trouble, \fIaddChild()\fR is useful if a document
 347 is built from a stream, such as happens sometimes in \s-1SAX\s0 handlers or filters.
 348 .Sp
 349 If you are not sure about the source of your nodes, you better stay with
 350 \&\fIappendChild()\fR, because this function is more user friendly in the sense of
 351 being more error tolerant.
 352 .IP "addNewChild" 4
 353 .IX Item "addNewChild"
 354 .Vb 1
 355 \&  $node = $parent\->addNewChild( $nsURI, $name );
 356 .Ve
 357 .Sp
 358 Similar to \f(CW\*(C`addChild()\*(C'\fR, this function uses low level libxml2 functionality to provide faster
 359 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.
 360 .Sp
 361 \&\fIaddNewChild()\fR has two parameters \f(CW$nsURI\fR and \f(CW$name\fR, where \f(CW$nsURI\fR is an
 362 (optional) namespace \s-1URI\s0. \f(CW$name\fR is the fully qualified element name;
 363 \&\fIaddNewChild()\fR will determine the correct prefix if necessary.
 364 .Sp
 365 The function returns the newly created node.
 366 .Sp
 367 This function is very useful for \s-1DOM\s0 building, where a created node can be
 368 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
 369 code to XML::LibXML.
 370 .IP "addSibling" 4
 371 .IX Item "addSibling"
 372 .Vb 1
 373 \&  $node\->addSibling($newNode);
 374 .Ve
 375 .Sp
 376 \&\fIaddSibling()\fR allows adding an additional node to the end of a nodelist, defined
 377 by the given node.
 378 .IP "cloneNode" 4
 379 .IX Item "cloneNode"
 380 .Vb 1
 381 \&  $newnode =$node\->cloneNode( $deep );
 382 .Ve
 383 .Sp
 384 \&\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 childnodes as well.
 385 If \f(CW$deep\fR is 0 only the current node will be copied. Note that in case of
 386 element, attributes are copied even if \f(CW$deep\fR is 0.
 387 .Sp
 388 Note that the behavior of this function for \f(CW$deep\fR=0 has changed in 1.62 in
 389 order to be consistent with the \s-1DOM\s0 spec (in older versions attributes and
 390 namespace information was not copied for elements).
 391 .IP "parentNode" 4
 392 .IX Item "parentNode"
 393 .Vb 1
 394 \&  $parentnode = $node\->parentNode;
 395 .Ve
 396 .Sp
 397 Returns simply the Parent Node of the current node.
 398 .IP "nextSibling" 4
 399 .IX Item "nextSibling"
 400 .Vb 1
 401 \&  $nextnode = $node\->nextSibling();
 402 .Ve
 403 .Sp
 404 Returns the next sibling if any .
 405 .IP "nextNonBlankSibling" 4
 406 .IX Item "nextNonBlankSibling"
 407 .Vb 1
 408 \&  $nextnode = $node\->nextNonBlankSibling();
 409 .Ve
 410 .Sp
 411 Returns the next non-blank sibling if any (a node is blank if it is a Text or
 412 \&\s-1CDATA\s0 node consisting of whitespace only). This method is not defined by \s-1DOM\s0.
 413 .IP "previousSibling" 4
 414 .IX Item "previousSibling"
 415 .Vb 1
 416 \&  $prevnode = $node\->previousSibling();
 417 .Ve
 418 .Sp
 419 Analogous to \fIgetNextSibling\fR the function returns the previous sibling if any.
 420 .IP "previousNonBlankSibling" 4
 421 .IX Item "previousNonBlankSibling"
 422 .Vb 1
 423 \&  $prevnode = $node\->previousNonBlankSibling();
 424 .Ve
 425 .Sp
 426 Returns the previous non-blank sibling if any (a node is blank if it is a Text
 427 or \s-1CDATA\s0 node consisting of whitespace only). This method is not defined by
 428 \&\s-1DOM\s0.
 429 .IP "hasChildNodes" 4
 430 .IX Item "hasChildNodes"
 431 .Vb 1
 432 \&  $boolean = $node\->hasChildNodes();
 433 .Ve
 434 .Sp
 435 If the current node has Childnodes this function returns \s-1TRUE\s0 (1), otherwise it
 436 returns \s-1FALSE\s0 (0, not undef).
 437 .IP "firstChild" 4
 438 .IX Item "firstChild"
 439 .Vb 1
 440 \&  $childnode = $node\->firstChild;
 441 .Ve
 442 .Sp
 443 If a node has childnodes this function will return the first node in the
 444 childlist.
 445 .IP "lastChild" 4
 446 .IX Item "lastChild"
 447 .Vb 1
 448 \&  $childnode = $node\->lastChild;
 449 .Ve
 450 .Sp
 451 If the \f(CW$node\fR has childnodes this function returns the last child node.
 452 .IP "ownerDocument" 4
 453 .IX Item "ownerDocument"
 454 .Vb 1
 455 \&  $documentnode = $node\->ownerDocument;
 456 .Ve
 457 .Sp
 458 Through this function it is always possible to access the document the current
 459 node is bound to.
 460 .IP "getOwner" 4
 461 .IX Item "getOwner"
 462 .Vb 1
 463 \&  $node = $node\->getOwner;
 464 .Ve
 465 .Sp
 466 This function returns the node the current node is associated with. In most
 467 cases this will be a document node or a document fragment node.
 468 .IP "setOwnerDocument" 4
 469 .IX Item "setOwnerDocument"
 470 .Vb 1
 471 \&  $node\->setOwnerDocument( $doc );
 472 .Ve
 473 .Sp
 474 This function binds a node to another \s-1DOM\s0. This method unbinds the node first,
 475 if it is already bound to another document.
 476 .Sp
 477 This function is the opposite calling of XML::LibXML::Document's \fIadoptNode()\fR function. Because of this it has the same limitations with
 478 Entity References as \fIadoptNode()\fR.
 479 .IP "insertBefore" 4
 480 .IX Item "insertBefore"
 481 .Vb 1
 482 \&  $node\->insertBefore( $newNode, $refNode );
 483 .Ve
 484 .Sp
 485 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.
 486 This function differs from the \s-1DOM\s0 L2 specification, in the case, if the new
 487 node is not part of the document, the node will be imported first,
 488 automatically.
 489 .Sp
 490 \&\f(CW$refNode\fR has to be passed to the function even if it is undefined:
 491 .Sp
 492 .Vb 2
 493 \&  $node\->insertBefore( $newNode, undef ); # the same as $node\->appendChild( $newNode );
 494 \&   $node\->insertBefore( $newNode ); # wrong
 495 .Ve
 496 .Sp
 497 Note, that the reference node has to be a direct child of the node the function
 498 is called on. Also, \f(CW$newChild\fR is not allowed to be an ancestor of the new
 499 parent node.
 500 .IP "insertAfter" 4
 501 .IX Item "insertAfter"
 502 .Vb 1
 503 \&  $node\->insertAfter( $newNode, $refNode );
 504 .Ve
 505 .Sp
 506 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.
 507 .Sp
 508 Note, that \f(CW$refNode\fR has to be passed explicitly even if it is undef.
 509 .IP "findnodes" 4
 510 .IX Item "findnodes"
 511 .Vb 1
 512 \&  @nodes = $node\->findnodes( $xpath_expression );
 513 .Ve
 514 .Sp
 515 \&\fIfindnodes\fR evaluates the xpath expression (XPath 1.0) on the current node and returns the
 516 resulting node set as an array. In scalar context returns a XML::LibXML::NodeList object.
 517 .Sp
 518 The xpath expression can be passed either as a string or or as a XML::LibXML::XPathExpression object.
 519 .Sp
 520 \&\fI\s-1NOTE\s0 \s-1ON\s0 \s-1NAMESPACES\s0 \s-1AND\s0 \s-1XPATH\s0\fR:
 521 .Sp
 522 A common mistake about XPath is to assume that node tests consisting of an
 523 element name with no prefix match elements in the default namespace. This
 524 assumption is wrong \- by XPath specification, such node tests can only match
 525 elements that are in no (i.e. null) namespace.
 526 .Sp
 527 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
 528 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
 529 situation even worse, since the \s-1XML\s0 document looks as if there was no default
 530 namespace).
 531 .Sp
 532 There are several possible ways to deal with namespaces in XPath:
 533 .RS 4
 534 .IP "\(bu" 4
 535 The recommended way is to use the XML::LibXML::XPathContext module to define an explicit context for XPath evaluation, in which a document
 536 independent prefix-to-namespace mapping can be defined. For example:
 537 .Sp
 538 .Vb 3
 539 \&  my $xpc = XML::LibXML::XPathContext\->new;
 540 \&  $xpc\->registerNs(\*(Aqx\*(Aq, \*(Aqhttp://www.w3.org/1999/xhtml\*(Aq);
 541 \&  $xpc\->find(\*(Aq/x:html\*(Aq,$node);
 542 .Ve
 543 .IP "\(bu" 4
 544 Another possibility is to use prefixes declared in the queried document (if
 545 known). If the document declares a prefix for the namespace in question (and
 546 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.:
 547 .Sp
 548 .Vb 1
 549 \&  $node\->find(\*(Aq/x:html\*(Aq);
 550 .Ve
 551 .RE
 552 .RS 4
 553 .Sp
 554 See also XML::LibXML::XPathContext\->findnodes.
 555 .RE
 556 .IP "find" 4
 557 .IX Item "find"
 558 .Vb 1
 559 \&  $result = $node\->find( $xpath );
 560 .Ve
 561 .Sp
 562 \&\fIfind\fR evaluates the XPath 1.0 expression using the current node as the context of the
 563 expression, and returns the result depending on what type of result the XPath
 564 expression had. For example, the XPath \*(L"1 * 3 + 52\*(R" 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 \*(L"do
 565 the right thing\*(R" in different contexts.
 566 .Sp
 567 The xpath expression can be passed either as a string or or as a XML::LibXML::XPathExpression object.
 568 .Sp
 569 See also XML::LibXML::XPathContext\->find.
 570 .IP "findvalue" 4
 571 .IX Item "findvalue"
 572 .Vb 1
 573 \&  print $node\->findvalue( $xpath );
 574 .Ve
 575 .Sp
 576 \&\fIfindvalue\fR is exactly equivalent to:
 577 .Sp
 578 .Vb 1
 579 \&  $node\->find( $xpath )\->to_literal;
 580 .Ve
 581 .Sp
 582 That is, it returns the literal value of the results. This enables you to
 583 ensure that you get a string back from your search, allowing certain shortcuts.
 584 This could be used as the equivalent of \s-1XSLT\s0's <xsl:value\-of
 585 select=\*(L"some_xpath\*(R"/>.
 586 .Sp
 587 See also XML::LibXML::XPathContext\->findvalue.
 588 .Sp
 589 The xpath expression can be passed either as a string or or as a XML::LibXML::XPathExpression object.
 590 .IP "exists" 4
 591 .IX Item "exists"
 592 .Vb 1
 593 \&  $bool = $node\->exists( $xpath_expression );
 594 .Ve
 595 .Sp
 596 This method behaves like \fIfindnodes\fR, except that it only returns a boolean value (1 if the expression matches a
 597 node, 0 otherwise) and may be faster than \fIfindnodes\fR, because the XPath evaluation may stop early on the first match (this is true
 598 for libxml2 >= 2.6.27).
 599 .Sp
 600 For XPath expressions that do not return node-set, the method returns true if
 601 the returned value is a non-zero number or a non-empty string.
 602 .IP "childNodes" 4
 603 .IX Item "childNodes"
 604 .Vb 1
 605 \&  @childnodes = $node\->childNodes();
 606 .Ve
 607 .Sp
 608 \&\fIchildNodes\fR implements a more intuitive interface to the childnodes of the current node. It
 609 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.
 610 .IP "nonBlankChildNodes" 4
 611 .IX Item "nonBlankChildNodes"
 612 .Vb 1
 613 \&  @childnodes = $node\->nonBlankChildNodes();
 614 .Ve
 615 .Sp
 616 This is like \fIchildNodes\fR, but returns only non-blank nodes (where a node is blank if it is a Text or
 617 \&\s-1CDATA\s0 node consisting of whitespace only). This method is not defined by \s-1DOM\s0.
 618 .IP "toString" 4
 619 .IX Item "toString"
 620 .Vb 1
 621 \&  $xmlstring = $node\->toString($format,$docencoding);
 622 .Ve
 623 .Sp
 624 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
 625 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
 626 encoded with \s-1UTF8\s0 flag on). An optional flag \f(CW$format\fR controls indentation, as
 627 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
 628 string in the document encoding (see \f(CW\*(C`XML::LibXML::Document::actualEncoding\*(C'\fR).
 629 .IP "toStringC14N" 4
 630 .IX Item "toStringC14N"
 631 .Vb 2
 632 \&  $c14nstring = $node\->toStringC14N();
 633 \&  $c14nstring = $node\->toStringC14N($with_comments, $xpath_expression , $xpath_context);
 634 .Ve
 635 .Sp
 636 The function is similar to \fItoString()\fR. Instead of simply serializing the
 637 document tree, it transforms it as it is specified in the \s-1XML\-C14N\s0
 638 Specification (see <http://www.w3.org/TR/xml\-c14n>). Such transformation is known as canonization.
 639 .Sp
 640 If \f(CW$with_comments\fR is 0 or not defined, the result-document will not contain any
 641 comments that exist in the original document. To include comments into the
 642 canonized document, \f(CW$with_comments\fR has to be set to 1.
 643 .Sp
 644 The parameter \f(CW$xpath_expression\fR defines the nodeset of nodes that should be
 645 visible in the resulting document. This can be used to filter out some nodes.
 646 One has to note, that only the nodes that are part of the nodeset, will be
 647 included into the result-document. Their child-nodes will not exist in the
 648 resulting document, unless they are part of the nodeset defined by the xpath
 649 expression.
 650 .Sp
 651 If \f(CW$xpath_expression\fR is omitted or empty, \fItoStringC14N()\fR will include all nodes
 652 in the given sub-tree, using the following XPath expressions: with comments
 653 .Sp
 654 .Vb 1
 655 \&  (. | .//node() | .//@* | .//namespace::*)
 656 .Ve
 657 .Sp
 658 and without comments
 659 .Sp
 660 .Vb 1
 661 \&  (. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
 662 .Ve
 663 .Sp
 664 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
 665 for mapping namespace prefixes used in the XPath expression to namespace URIs.
 666 Note, however, that \f(CW$node\fR will be used as the context node for the evaluation,
 667 not the context node of \f(CW$xpath_context\fR!
 668 .IP "toStringEC14N" 4
 669 .IX Item "toStringEC14N"
 670 .Vb 3
 671 \&  $ec14nstring = $node\->toStringEC14N();
 672 \&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
 673 \&  $ec14nstring = $node\->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
 674 .Ve
 675 .Sp
 676 The function is similar to \fItoStringC14N()\fR but follows the \s-1XML\-EXC\-C14N\s0
 677 Specification (see <http://www.w3.org/TR/xml\-exc\-c14n>) for exclusive canonization of \s-1XML\s0.
 678 .Sp
 679 The arguments \f(CW$with_comments\fR, \f(CW$xpath_expression\fR, \f(CW$xpath_context\fR are as in
 680 \&\fItoStringC14N()\fR. An \s-1ARRAY\s0 reference can be passed as the last argument
 681 \&\f(CW$inclusive_prefix_list\fR, listing namespace prefixes that are to be handled in
 682 the manner described by the Canonical \s-1XML\s0 Recommendation (i.e. preserved in the
 683 output even if the namespace is not used). C.f. the spec for details.
 684 .IP "serialize" 4
 685 .IX Item "serialize"
 686 .Vb 1
 687 \&  $str = $doc\->serialize($format);
 688 .Ve
 689 .Sp
 690 An alias for \fItoString()\fR. This function was name added to be more consistent
 691 with libxml2.
 692 .IP "serialize_c14n" 4
 693 .IX Item "serialize_c14n"
 694 An alias for \fItoStringC14N()\fR.
 695 .IP "serialize_exc_c14n" 4
 696 .IX Item "serialize_exc_c14n"
 697 An alias for \fItoStringEC14N()\fR.
 698 .IP "localname" 4
 699 .IX Item "localname"
 700 .Vb 1
 701 \&  $localname = $node\->localname;
 702 .Ve
 703 .Sp
 704 Returns the local name of a tag. This is the part behind the colon.
 705 .IP "prefix" 4
 706 .IX Item "prefix"
 707 .Vb 1
 708 \&  $nameprefix = $node\->prefix;
 709 .Ve
 710 .Sp
 711 Returns the prefix of a tag. This is the part before the colon.
 712 .IP "namespaceURI" 4
 713 .IX Item "namespaceURI"
 714 .Vb 1
 715 \&  $uri = $node\->namespaceURI();
 716 .Ve
 717 .Sp
 718 returns the \s-1URI\s0 of the current namespace.
 719 .IP "hasAttributes" 4
 720 .IX Item "hasAttributes"
 721 .Vb 1
 722 \&  $boolean = $node\->hasAttributes();
 723 .Ve
 724 .Sp
 725 returns 1 (\s-1TRUE\s0) if the current node has any attributes set, otherwise 0
 726 (\s-1FALSE\s0) is returned.
 727 .IP "attributes" 4
 728 .IX Item "attributes"
 729 .Vb 1
 730 \&  @attributelist = $node\->attributes();
 731 .Ve
 732 .Sp
 733 This function returns all attributes and namespace declarations assigned to the
 734 given node.
 735 .Sp
 736 Because XML::LibXML does not implement namespace declarations and attributes
 737 the same way, it is required to test what kind of node is handled while
 738 accessing the functions result.
 739 .Sp
 740 If this function is called in array context the attribute nodes are returned as
 741 an array. In scalar context the function will return a XML::LibXML::NamedNodeMap object.
 742 .IP "lookupNamespaceURI" 4
 743 .IX Item "lookupNamespaceURI"
 744 .Vb 1
 745 \&  $URI = $node\->lookupNamespaceURI( $prefix );
 746 .Ve
 747 .Sp
 748 Find a namespace \s-1URI\s0 by its prefix starting at the current node.
 749 .IP "lookupNamespacePrefix" 4
 750 .IX Item "lookupNamespacePrefix"
 751 .Vb 1
 752 \&  $prefix = $node\->lookupNamespacePrefix( $URI );
 753 .Ve
 754 .Sp
 755 Find a namespace prefix by its \s-1URI\s0 starting at the current node.
 756 .Sp
 757 \&\fI\s-1NOTE\s0\fR Only the namespace URIs are meant to be unique. The prefix is only document
 758 related. Also the document might have more than a single prefix defined for a
 759 namespace.
 760 .IP "normalize" 4
 761 .IX Item "normalize"
 762 .Vb 1
 763 \&  $node\->normalize;
 764 .Ve
 765 .Sp
 766 This function normalizes adjacent text nodes. This function is not as strict as
 767 libxml2's \fIxmlTextMerge()\fR function, since it will not free a node that is still
 768 referenced by the perl layer.
 769 .IP "getNamespaces" 4
 770 .IX Item "getNamespaces"
 771 .Vb 1
 772 \&  @nslist = $node\->getNamespaces;
 773 .Ve
 774 .Sp
 775 If a node has any namespaces defined, this function will return these
 776 namespaces. Note, that this will not return all namespaces that are in scope,
 777 but only the ones declared explicitly for that node.
 778 .Sp
 779 Although getNamespaces is available for all nodes, it only makes sense if used
 780 with element nodes.
 781 .IP "removeChildNodes" 4
 782 .IX Item "removeChildNodes"
 783 .Vb 1
 784 \&  $node\->removeChildNodes();
 785 .Ve
 786 .Sp
 787 This function is not specified for any \s-1DOM\s0 level: It removes all childnodes
 788 from a node in a single step. Other than the libxml2 function itself
 789 (xmlFreeNodeList), this function will not immediately remove the nodes from the
 790 memory. This saves one from getting memory violations, if there are nodes still
 791 referred to from the Perl level.
 792 .IP "baseURI ()" 4
 793 .IX Item "baseURI ()"
 794 .Vb 1
 795 \&  $strURI = $node\->baseURI();
 796 .Ve
 797 .Sp
 798 Searches for the base \s-1URL\s0 of the node. The method should work on both \s-1XML\s0 and
 799 \&\s-1HTML\s0 documents even if base mechanisms for these are completely different. It
 800 returns the base as defined in \s-1RFC\s0 2396 sections \*(L"5.1.1. Base \s-1URI\s0 within
 801 Document Content\*(R" and \*(L"5.1.2. Base \s-1URI\s0 from the Encapsulating Entity\*(R". However
 802 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.
 803 .IP "setBaseURI ($strURI)" 4
 804 .IX Item "setBaseURI ($strURI)"
 805 .Vb 1
 806 \&  $node\->setBaseURI($strURI);
 807 .Ve
 808 .Sp
 809 This method only does something useful for an element node in a \s-1XML\s0 document.
 810 It sets the xml:base attribute on the node to \f(CW$strURI\fR, which effectively sets
 811 the base \s-1URI\s0 of the node to the same value.
 812 .Sp
 813 Note: For \s-1HTML\s0 documents this behaves as if the document was \s-1XML\s0 which may not
 814 be desired, since it does not effectively set the base \s-1URI\s0 of the node. See \s-1RFC\s0
 815 2396 appendix D for an example of how base \s-1URI\s0 can be specified in \s-1HTML\s0.
 816 .IP "nodePath" 4
 817 .IX Item "nodePath"
 818 .Vb 1
 819 \&  $node\->nodePath();
 820 .Ve
 821 .Sp
 822 This function is not specified for any \s-1DOM\s0 level: It returns a canonical
 823 structure based XPath for a given node.
 824 .IP "line_number" 4
 825 .IX Item "line_number"
 826 .Vb 1
 827 \&  $lineno = $node\->line_number();
 828 .Ve
 829 .Sp
 830 This function returns the line number where the tag was found during parsing.
 831 If a node is added to the document the line number is 0. Problems may occur, if
 832 a node from one document is passed to another one.
 833 .Sp
 834 \&\s-1IMPORTANT:\s0 Due to limitations in the libxml2 library line numbers greater than
 835 65535 will be returned as 65535. Please see <http://bugzilla.gnome.org/show_bug.cgi?id=325533> for more details.
 836 .Sp
 837 Note: \fIline_number()\fR is special to XML::LibXML and not part of the \s-1DOM\s0
 838 specification.
 839 .Sp
 840 If the line_numbers flag of the parser was not activated before parsing,
 841 \&\fIline_number()\fR will always return 0.
 842 .SH "AUTHORS"
 843 .IX Header "AUTHORS"
 844 Matt Sergeant,
 845 Christian Glahn,
 846 Petr Pajas
 847 .SH "VERSION"
 848 .IX Header "VERSION"
 849 1.70
 850 .SH "COPYRIGHT"
 851 .IX Header "COPYRIGHT"
 852 2001\-2007, AxKit.com Ltd.
 853 .PP
 854 2002\-2006, Christian Glahn.
 855 .PP
 856 2006\-2009, Petr Pajas.