1XML::LibXML::Node(3) User Contributed Perl Documentation XML::LibXML::Node(3)
2
6 XML::LibXML::Node - Abstract Base Class of XML::LibXML Nodes
7
9 use XML::LibXML;
10 $name = $node->nodeName;
12 $node->setNodeName( $newName );
13 $bool = $node->isSameNode( $other_node );
14 $bool = $node->isEqual( $other_node );
15 $content = $node->nodeValue;
16 $content = $node->textContent;
17 $type = $node->nodeType;
18 $node->unbindNode();
19 $childnode = $node->removeChild( $childnode );
20 $oldnode = $node->replaceChild( $newNode, $oldNode );
21 $node->replaceNode($newNode);
22 $childnode = $node->appendChild( $childnode );
23 $childnode = $node->addChild( $chilnode );
24 $node = $parent->addNewChild( $nsURI, $name );
25 $node->addSibling($newNode);
26 $newnode =$node->cloneNode( $deep );
27 $parentnode = $node->parentNode;
28 $nextnode = $node->nextSibling();
29 $nextnode = $node->nextNonBlankSibling();
30 $prevnode = $node->previousSibling();
31 $prevnode = $node->previousNonBlankSibling();
32 $boolean = $node->hasChildNodes();
33 $childnode = $node->firstChild;
34 $childnode = $node->lastChild;
35 $documentnode = $node->ownerDocument;
36 $node = $node->getOwner;
37 $node->setOwnerDocument( $doc );
38 $node->insertBefore( $newNode, $refNode );
39 $node->insertAfter( $newNode, $refNode );
40 @nodes = $node->findnodes( $xpath_expression );
41 $result = $node->find( $xpath );
42 print $node->findvalue( $xpath );
43 $bool = $node->exists( $xpath_expression );
44 @childnodes = $node->childNodes();
45 @childnodes = $node->nonBlankChildNodes();
46 $xmlstring = $node->toString($format,$docencoding);
47 $c14nstring = $node->toStringC14N();
48 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
49 $ec14nstring = $node->toStringEC14N();
50 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
51 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
52 $str = $doc->serialize($format);
53 $localname = $node->localname;
54 $nameprefix = $node->prefix;
55 $uri = $node->namespaceURI();
56 $boolean = $node->hasAttributes();
57 @attributelist = $node->attributes();
58 $URI = $node->lookupNamespaceURI( $prefix );
59 $prefix = $node->lookupNamespacePrefix( $URI );
60 $node->normalize;
61 @nslist = $node->getNamespaces;
62 $node->removeChildNodes();
63 $strURI = $node->baseURI();
64 $node->setBaseURI($strURI);
65 $node->nodePath();
66 $lineno = $node->line_number();
67
69 XML::LibXML::Node defines functions that are common to all Node Types.
70 A LibXML::Node should never be created standalone, but as an instance
71 of a high level class such as LibXML::Element or LibXML::Text. The
72 class itself should provide only common functionality. In XML::LibXML
73 each node is part either of a document or a document-fragment. Because
74 of this there is no node without a parent. This may causes confusion
75 with "unbound" nodes.
76
78 Many functions listed here are extensively documented in the DOM Level
79 3 specification (http://www.w3.org/TR/DOM-Level-3-Core/
80 <http://www.w3.org/TR/DOM-Level-3-Core/>). Please refer to the
81 specification for extensive documentation.
82 nodeName
84 $name = $node->nodeName;
85 Returns the node's name. This function is aware of namespaces and
87 returns the full name of the current node ("prefix:localname").
88 Since 1.62 this function also returns the correct DOM names for
90 node types with constant names, namely: #text, #cdata-section,
91 #comment, #document, #document-fragment.
92 setNodeName
94 $node->setNodeName( $newName );
95 In very limited situations, it is useful to change a nodes name. In
97 the DOM specification this should throw an error. This Function is
98 aware of namespaces.
99 isSameNode
101 $bool = $node->isSameNode( $other_node );
102 returns TRUE (1) if the given nodes refer to the same node
104 structure, otherwise FALSE (0) is returned.
105 isEqual
107 $bool = $node->isEqual( $other_node );
108 deprecated version of isSameNode().
110 NOTE isEqual will change behaviour to follow the DOM specification
112 nodeValue
114 $content = $node->nodeValue;
115 If the node has any content (such as stored in a "text node") it
117 can get requested through this function.
118 NOTE: Element Nodes have no content per definition. To get the text
120 value of an Element use textContent() instead!
121 textContent
123 $content = $node->textContent;
124 this function returns the content of all text nodes in the
126 descendants of the given node as specified in DOM.
127 nodeType
129 $type = $node->nodeType;
130 Return a numeric value representing the node type of this node. The
132 module XML::LibXML by default exports constants for the node types
133 (see the EXPORT section in the XML::LibXML manual page).
134 unbindNode
136 $node->unbindNode();
137 Unbinds the Node from its siblings and Parent, but not from the
139 Document it belongs to. If the node is not inserted into the DOM
140 afterwards it will be lost after the program terminated. From a low
141 level view, the unbound node is stripped from the context it is and
142 inserted into a (hidden) document-fragment.
143 removeChild
145 $childnode = $node->removeChild( $childnode );
146 This will unbind the Child Node from its parent $node. The function
148 returns the unbound node. If "oldNode" is not a child of the given
149 Node the function will fail.
150 replaceChild
152 $oldnode = $node->replaceChild( $newNode, $oldNode );
153 Replaces the $oldNode with the $newNode. The $oldNode will be
155 unbound from the Node. This function differs from the DOM L2
156 specification, in the case, if the new node is not part of the
157 document, the node will be imported first.
158 replaceNode
160 $node->replaceNode($newNode);
161 This function is very similar to replaceChild(), but it replaces
163 the node itself rather than a childnode. This is useful if a node
164 found by any XPath function, should be replaced.
165 appendChild
167 $childnode = $node->appendChild( $childnode );
168 The function will add the $childnode to the end of $node's
170 children. The function should fail, if the new childnode is already
171 a child of $node. This function differs from the DOM L2
172 specification, in the case, if the new node is not part of the
173 document, the node will be imported first.
174 addChild
176 $childnode = $node->addChild( $chilnode );
177 As an alternative to appendChild() one can use the addChild()
179 function. This function is a bit faster, because it avoids all DOM
180 conformity checks. Therefore this function is quite useful if one
181 builds XML documents in memory where the order and ownership
182 ("ownerDocument") is assured.
183 addChild() uses libxml2's own xmlAddChild() function. Thus it has
185 to be used with extra care: If a text node is added to a node and
186 the node itself or its last childnode is as well a text node, the
187 node to add will be merged with the one already available. The
188 current node will be removed from memory after this action. Because
189 perl is not aware of this action, the perl instance is still
190 available. XML::LibXML will catch the loss of a node and refuse to
191 run any function called on that node.
192 my $t1 = $doc->createTextNode( "foo" );
194 my $t2 = $doc->createTextNode( "bar" );
195 $t1->addChild( $t2 ); # is OK
196 my $val = $t2->nodeValue(); # will fail, script dies
197 Also addChild() will not check if the added node belongs to the
199 same document as the node it will be added to. This could lead to
200 inconsistent documents and in more worse cases even to memory
201 violations, if one does not keep track of this issue.
202 Although this sounds like a lot of trouble, addChild() is useful if
204 a document is built from a stream, such as happens sometimes in SAX
205 handlers or filters.
206 If you are not sure about the source of your nodes, you better stay
208 with appendChild(), because this function is more user friendly in
209 the sense of being more error tolerant.
210 addNewChild
212 $node = $parent->addNewChild( $nsURI, $name );
213 Similar to "addChild()", this function uses low level libxml2
215 functionality to provide faster interface for DOM building.
216 addNewChild() uses "xmlNewChild()" to create a new node on a given
217 parent element.
218 addNewChild() has two parameters $nsURI and $name, where $nsURI is
220 an (optional) namespace URI. $name is the fully qualified element
221 name; addNewChild() will determine the correct prefix if necessary.
222 The function returns the newly created node.
224 This function is very useful for DOM building, where a created node
226 can be directly associated with its parent. NOTE this function is
227 not part of the DOM specification and its use will limit your code
228 to XML::LibXML.
229 addSibling
231 $node->addSibling($newNode);
232 addSibling() allows adding an additional node to the end of a
234 nodelist, defined by the given node.
235 cloneNode
237 $newnode =$node->cloneNode( $deep );
238 cloneNode creates a copy of $node. When $deep is set to 1 (true)
240 the function will copy all childnodes as well. If $deep is 0 only
241 the current node will be copied. Note that in case of element,
242 attributes are copied even if $deep is 0.
243 Note that the behavior of this function for $deep=0 has changed in
245 1.62 in order to be consistent with the DOM spec (in older versions
246 attributes and namespace information was not copied for elements).
247 parentNode
249 $parentnode = $node->parentNode;
250 Returns simply the Parent Node of the current node.
252 nextSibling
254 $nextnode = $node->nextSibling();
255 Returns the next sibling if any .
257 nextNonBlankSibling
259 $nextnode = $node->nextNonBlankSibling();
260 Returns the next non-blank sibling if any (a node is blank if it is
262 a Text or CDATA node consisting of whitespace only). This method is
263 not defined by DOM.
264 previousSibling
266 $prevnode = $node->previousSibling();
267 Analogous to getNextSibling the function returns the previous
269 sibling if any.
270 previousNonBlankSibling
272 $prevnode = $node->previousNonBlankSibling();
273 Returns the previous non-blank sibling if any (a node is blank if
275 it is a Text or CDATA node consisting of whitespace only). This
276 method is not defined by DOM.
277 hasChildNodes
279 $boolean = $node->hasChildNodes();
280 If the current node has Childnodes this function returns TRUE (1),
282 otherwise it returns FALSE (0, not undef).
283 firstChild
285 $childnode = $node->firstChild;
286 If a node has childnodes this function will return the first node
288 in the childlist.
289 lastChild
291 $childnode = $node->lastChild;
292 If the $node has childnodes this function returns the last child
294 node.
295 ownerDocument
297 $documentnode = $node->ownerDocument;
298 Through this function it is always possible to access the document
300 the current node is bound to.
301 getOwner
303 $node = $node->getOwner;
304 This function returns the node the current node is associated with.
306 In most cases this will be a document node or a document fragment
307 node.
308 setOwnerDocument
310 $node->setOwnerDocument( $doc );
311 This function binds a node to another DOM. This method unbinds the
313 node first, if it is already bound to another document.
314 This function is the opposite calling of XML::LibXML::Document's
316 adoptNode() function. Because of this it has the same limitations
317 with Entity References as adoptNode().
318 insertBefore
320 $node->insertBefore( $newNode, $refNode );
321 The method inserts $newNode before $refNode. If $refNode is
323 undefined, the newNode will be set as the new last child of the
324 parent node. This function differs from the DOM L2 specification,
325 in the case, if the new node is not part of the document, the node
326 will be imported first, automatically.
327 $refNode has to be passed to the function even if it is undefined:
329 $node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode );
331 $node->insertBefore( $newNode ); # wrong
332 Note, that the reference node has to be a direct child of the node
334 the function is called on. Also, $newChild is not allowed to be an
335 ancestor of the new parent node.
336 insertAfter
338 $node->insertAfter( $newNode, $refNode );
339 The method inserts $newNode after $refNode. If $refNode is
341 undefined, the newNode will be set as the new last child of the
342 parent node.
343 Note, that $refNode has to be passed explicitly even if it is
345 undef.
346 findnodes
348 @nodes = $node->findnodes( $xpath_expression );
349 findnodes evaluates the xpath expression (XPath 1.0) on the current
351 node and returns the resulting node set as an array. In scalar
352 context returns a XML::LibXML::NodeList object.
353 The xpath expression can be passed either as a string or or as a
355 XML::LibXML::XPathExpression object.
356 NOTE ON NAMESPACES AND XPATH:
358 A common mistake about XPath is to assume that node tests
360 consisting of an element name with no prefix match elements in the
361 default namespace. This assumption is wrong - by XPath
362 specification, such node tests can only match elements that are in
363 no (i.e. null) namespace.
364 So, for example, one cannot match the root element of an XHTML
366 document with "$node->find('/html')" since '/html' would only match
367 if the root element "<html>" had no namespace, but all XHTML
368 elements belong to the namespace http://www.w3.org/1999/xhtml.
369 (Note that "xmlns="..."" namespace declarations can also be
370 specified in a DTD, which makes the situation even worse, since the
371 XML document looks as if there was no default namespace).
372 There are several possible ways to deal with namespaces in XPath:
374 · The recommended way is to use the XML::LibXML::XPathContext
376 module to define an explicit context for XPath evaluation, in
377 which a document independent prefix-to-namespace mapping can be
378 defined. For example:
379 my $xpc = XML::LibXML::XPathContext->new;
381 $xpc->registerNs('x', 'http://www.w3.org/1999/xhtml');
382 $xpc->find('/x:html',$node);
383 · Another possibility is to use prefixes declared in the queried
385 document (if known). If the document declares a prefix for the
386 namespace in question (and the context node is in the scope of
387 the declaration), "XML::LibXML" allows you to use the prefix in
388 the XPath expression, e.g.:
389 $node->find('/x:html');
391 See also XML::LibXML::XPathContext->findnodes.
393 find
395 $result = $node->find( $xpath );
396 find evaluates the XPath 1.0 expression using the current node as
398 the context of the expression, and returns the result depending on
399 what type of result the XPath expression had. For example, the
400 XPath "1 * 3 + 52" results in a XML::LibXML::Number object being
401 returned. Other expressions might return a XML::LibXML::Boolean
402 object, or a XML::LibXML::Literal object (a string). Each of those
403 objects uses Perl's overload feature to "do the right thing" in
404 different contexts.
405 The xpath expression can be passed either as a string or or as a
407 XML::LibXML::XPathExpression object.
408 See also XML::LibXML::XPathContext->find.
410 findvalue
412 print $node->findvalue( $xpath );
413 findvalue is exactly equivalent to:
415 $node->find( $xpath )->to_literal;
417 That is, it returns the literal value of the results. This enables
419 you to ensure that you get a string back from your search, allowing
420 certain shortcuts. This could be used as the equivalent of XSLT's
421 <xsl:value-of select="some_xpath"/>.
422 See also XML::LibXML::XPathContext->findvalue.
424 The xpath expression can be passed either as a string or or as a
426 XML::LibXML::XPathExpression object.
427 exists
429 $bool = $node->exists( $xpath_expression );
430 This method behaves like findnodes, except that it only returns a
432 boolean value (1 if the expression matches a node, 0 otherwise) and
433 may be faster than findnodes, because the XPath evaluation may stop
434 early on the first match (this is true for libxml2 >= 2.6.27).
435 For XPath expressions that do not return node-set, the method
437 returns true if the returned value is a non-zero number or a non-
438 empty string.
439 childNodes
441 @childnodes = $node->childNodes();
442 childNodes implements a more intuitive interface to the childnodes
444 of the current node. It enables you to pass all children directly
445 to a "map" or "grep". If this function is called in scalar context,
446 a XML::LibXML::NodeList object will be returned.
447 nonBlankChildNodes
449 @childnodes = $node->nonBlankChildNodes();
450 This is like childNodes, but returns only non-blank nodes (where a
452 node is blank if it is a Text or CDATA node consisting of
453 whitespace only). This method is not defined by DOM.
454 toString
456 $xmlstring = $node->toString($format,$docencoding);
457 This method is similar to the method "toString" of a
459 XML::LibXML::Document but for a single node. It returns a string
460 consisting of XML serialization of the given node and all its
461 descendants. Unlike "XML::LibXML::Document::toString", in this case
462 the resulting string is by default a character string (UTF-8
463 encoded with UTF8 flag on). An optional flag $format controls
464 indentation, as in "XML::LibXML::Document::toString". If the second
465 optional $docencoding flag is true, the result will be a byte
466 string in the document encoding (see
467 "XML::LibXML::Document::actualEncoding").
468 toStringC14N
470 $c14nstring = $node->toStringC14N();
471 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
472 The function is similar to toString(). Instead of simply
474 serializing the document tree, it transforms it as it is specified
475 in the XML-C14N Specification (see http://www.w3.org/TR/xml-c14n
476 <http://www.w3.org/TR/xml-c14n>). Such transformation is known as
477 canonization.
478 If $with_comments is 0 or not defined, the result-document will not
480 contain any comments that exist in the original document. To
481 include comments into the canonized document, $with_comments has to
482 be set to 1.
483 The parameter $xpath_expression defines the nodeset of nodes that
485 should be visible in the resulting document. This can be used to
486 filter out some nodes. One has to note, that only the nodes that
487 are part of the nodeset, will be included into the result-document.
488 Their child-nodes will not exist in the resulting document, unless
489 they are part of the nodeset defined by the xpath expression.
490 If $xpath_expression is omitted or empty, toStringC14N() will
492 include all nodes in the given sub-tree, using the following XPath
493 expressions: with comments
494 (. | .//node() | .//@* | .//namespace::*)
496 and without comments
498 (. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
500 An optional parameter $xpath_context can be used to pass an
502 XML::LibXML::XPathContext object defining the context for
503 evaluation of $xpath_expression. This is useful for mapping
504 namespace prefixes used in the XPath expression to namespace URIs.
505 Note, however, that $node will be used as the context node for the
506 evaluation, not the context node of $xpath_context!
507 toStringEC14N
509 $ec14nstring = $node->toStringEC14N();
510 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
511 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
512 The function is similar to toStringC14N() but follows the
514 XML-EXC-C14N Specification (see http://www.w3.org/TR/xml-exc-c14n
515 <http://www.w3.org/TR/xml-exc-c14n>) for exclusive canonization of
516 XML.
517 The arguments $with_comments, $xpath_expression, $xpath_context are
519 as in toStringC14N(). An ARRAY reference can be passed as the last
520 argument $inclusive_prefix_list, listing namespace prefixes that
521 are to be handled in the manner described by the Canonical XML
522 Recommendation (i.e. preserved in the output even if the namespace
523 is not used). C.f. the spec for details.
524 serialize
526 $str = $doc->serialize($format);
527 An alias for toString(). This function was name added to be more
529 consistent with libxml2.
530 serialize_c14n
532 An alias for toStringC14N().
533 serialize_exc_c14n
535 An alias for toStringEC14N().
536 localname
538 $localname = $node->localname;
539 Returns the local name of a tag. This is the part behind the colon.
541 prefix
543 $nameprefix = $node->prefix;
544 Returns the prefix of a tag. This is the part before the colon.
546 namespaceURI
548 $uri = $node->namespaceURI();
549 returns the URI of the current namespace.
551 hasAttributes
553 $boolean = $node->hasAttributes();
554 returns 1 (TRUE) if the current node has any attributes set,
556 otherwise 0 (FALSE) is returned.
557 attributes
559 @attributelist = $node->attributes();
560 This function returns all attributes and namespace declarations
562 assigned to the given node.
563 Because XML::LibXML does not implement namespace declarations and
565 attributes the same way, it is required to test what kind of node
566 is handled while accessing the functions result.
567 If this function is called in array context the attribute nodes are
569 returned as an array. In scalar context the function will return a
570 XML::LibXML::NamedNodeMap object.
571 lookupNamespaceURI
573 $URI = $node->lookupNamespaceURI( $prefix );
574 Find a namespace URI by its prefix starting at the current node.
576 lookupNamespacePrefix
578 $prefix = $node->lookupNamespacePrefix( $URI );
579 Find a namespace prefix by its URI starting at the current node.
581 NOTE Only the namespace URIs are meant to be unique. The prefix is
583 only document related. Also the document might have more than a
584 single prefix defined for a namespace.
585 normalize
587 $node->normalize;
588 This function normalizes adjacent text nodes. This function is not
590 as strict as libxml2's xmlTextMerge() function, since it will not
591 free a node that is still referenced by the perl layer.
592 getNamespaces
594 @nslist = $node->getNamespaces;
595 If a node has any namespaces defined, this function will return
597 these namespaces. Note, that this will not return all namespaces
598 that are in scope, but only the ones declared explicitly for that
599 node.
600 Although getNamespaces is available for all nodes, it only makes
602 sense if used with element nodes.
603 removeChildNodes
605 $node->removeChildNodes();
606 This function is not specified for any DOM level: It removes all
608 childnodes from a node in a single step. Other than the libxml2
609 function itself (xmlFreeNodeList), this function will not
610 immediately remove the nodes from the memory. This saves one from
611 getting memory violations, if there are nodes still referred to
612 from the Perl level.
613 baseURI ()
615 $strURI = $node->baseURI();
616 Searches for the base URL of the node. The method should work on
618 both XML and HTML documents even if base mechanisms for these are
619 completely different. It returns the base as defined in RFC 2396
620 sections "5.1.1. Base URI within Document Content" and "5.1.2. Base
621 URI from the Encapsulating Entity". However it does not return the
622 document base (5.1.3), use method "URI" of "XML::LibXML::Document"
623 for this.
624 setBaseURI ($strURI)
626 $node->setBaseURI($strURI);
627 This method only does something useful for an element node in a XML
629 document. It sets the xml:base attribute on the node to $strURI,
630 which effectively sets the base URI of the node to the same value.
631 Note: For HTML documents this behaves as if the document was XML
633 which may not be desired, since it does not effectively set the
634 base URI of the node. See RFC 2396 appendix D for an example of how
635 base URI can be specified in HTML.
636 nodePath
638 $node->nodePath();
639 This function is not specified for any DOM level: It returns a
641 canonical structure based XPath for a given node.
642 line_number
644 $lineno = $node->line_number();
645 This function returns the line number where the tag was found
647 during parsing. If a node is added to the document the line number
648 is 0. Problems may occur, if a node from one document is passed to
649 another one.
650 IMPORTANT: Due to limitations in the libxml2 library line numbers
652 greater than 65535 will be returned as 65535. Please see
653 <http://bugzilla.gnome.org/show_bug.cgi?id=325533> for more
654 details.
655 Note: line_number() is special to XML::LibXML and not part of the
657 DOM specification.
658 If the line_numbers flag of the parser was not activated before
660 parsing, line_number() will always return 0.
661
663 Matt Sergeant, Christian Glahn, Petr Pajas
664
666 1.70
667
669 2001-2007, AxKit.com Ltd.
670 2002-2006, Christian Glahn.
672 2006-2009, Petr Pajas.
674perl v5.12.0 2009-10-07 XML::LibXML::Node(3)