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 $num = $node->unique_key;
16 $content = $node->nodeValue;
17 $content = $node->textContent;
18 $type = $node->nodeType;
19 $node->unbindNode();
20 $childnode = $node->removeChild( $childnode );
21 $oldnode = $node->replaceChild( $newNode, $oldNode );
22 $node->replaceNode($newNode);
23 $childnode = $node->appendChild( $childnode );
24 $childnode = $node->addChild( $childnode );
25 $node = $parent->addNewChild( $nsURI, $name );
26 $node->addSibling($newNode);
27 $newnode =$node->cloneNode( $deep );
28 $parentnode = $node->parentNode;
29 $nextnode = $node->nextSibling();
30 $nextnode = $node->nextNonBlankSibling();
31 $prevnode = $node->previousSibling();
32 $prevnode = $node->previousNonBlankSibling();
33 $boolean = $node->hasChildNodes();
34 $childnode = $node->firstChild;
35 $childnode = $node->lastChild;
36 $documentnode = $node->ownerDocument;
37 $node = $node->getOwner;
38 $node->setOwnerDocument( $doc );
39 $node->insertBefore( $newNode, $refNode );
40 $node->insertAfter( $newNode, $refNode );
41 @nodes = $node->findnodes( $xpath_expression );
42 $result = $node->find( $xpath );
43 print $node->findvalue( $xpath );
44 $bool = $node->exists( $xpath_expression );
45 @childnodes = $node->childNodes();
46 @childnodes = $node->nonBlankChildNodes();
47 $xmlstring = $node->toString($format,$docencoding);
48 $c14nstring = $node->toStringC14N();
49 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
50 $c14nstring = $node->toStringC14N_v1_1();
51 $c14nstring = $node->toStringC14N_v1_1($with_comments, $xpath_expression , $xpath_context);
52 $ec14nstring = $node->toStringEC14N();
53 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
54 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
55 $str = $doc->serialize($format);
56 $localname = $node->localname;
57 $nameprefix = $node->prefix;
58 $uri = $node->namespaceURI();
59 $boolean = $node->hasAttributes();
60 @attributelist = $node->attributes();
61 $URI = $node->lookupNamespaceURI( $prefix );
62 $prefix = $node->lookupNamespacePrefix( $URI );
63 $node->normalize;
64 @nslist = $node->getNamespaces;
65 $node->removeChildNodes();
66 $strURI = $node->baseURI();
67 $node->setBaseURI($strURI);
68 $node->nodePath();
69 $lineno = $node->line_number();
70
72 XML::LibXML::Node defines functions that are common to all Node Types.
73 An XML::LibXML::Node should never be created standalone, but as an
74 instance of a high level class such as XML::LibXML::Element or
75 XML::LibXML::Text. The class itself should provide only common
76 functionality. In XML::LibXML each node is part either of a document or
77 a document-fragment. Because of this there is no node without a parent.
78 This may causes confusion with "unbound" nodes.
79
81 Many functions listed here are extensively documented in the DOM Level
82 3 specification (<http://www.w3.org/TR/DOM-Level-3-Core/>). Please
83 refer to the specification for extensive documentation.
84 nodeName
86 $name = $node->nodeName;
87 Returns the node's name. This function is aware of namespaces and
89 returns the full name of the current node ("prefix:localname").
90 Since 1.62 this function also returns the correct DOM names for
92 node types with constant names, namely: #text, #cdata-section,
93 #comment, #document, #document-fragment.
94 setNodeName
96 $node->setNodeName( $newName );
97 In very limited situations, it is useful to change a nodes name. In
99 the DOM specification this should throw an error. This Function is
100 aware of namespaces.
101 isSameNode
103 $bool = $node->isSameNode( $other_node );
104 returns TRUE (1) if the given nodes refer to the same node
106 structure, otherwise FALSE (0) is returned.
107 isEqual
109 $bool = $node->isEqual( $other_node );
110 deprecated version of isSameNode().
112 NOTE isEqual will change behaviour to follow the DOM specification
114 unique_key
116 $num = $node->unique_key;
117 This function is not specified for any DOM level. It returns a key
119 guaranteed to be unique for this node, and to always be the same
120 value for this node. In other words, two node objects return the
121 same key if and only if isSameNode indicates that they are the same
122 node.
123 The returned key value is useful as a key in hashes.
125 nodeValue
127 $content = $node->nodeValue;
128 If the node has any content (such as stored in a "text node") it
130 can get requested through this function.
131 NOTE: Element Nodes have no content per definition. To get the text
133 value of an Element use textContent() instead!
134 textContent
136 $content = $node->textContent;
137 this function returns the content of all text nodes in the
139 descendants of the given node as specified in DOM.
140 nodeType
142 $type = $node->nodeType;
143 Return a numeric value representing the node type of this node. The
145 module XML::LibXML by default exports constants for the node types
146 (see the EXPORT section in the XML::LibXML manual page).
147 unbindNode
149 $node->unbindNode();
150 Unbinds the Node from its siblings and Parent, but not from the
152 Document it belongs to. If the node is not inserted into the DOM
153 afterwards, it will be lost after the program terminates. From a
154 low level view, the unbound node is stripped from the context it is
155 and inserted into a (hidden) document-fragment.
156 removeChild
158 $childnode = $node->removeChild( $childnode );
159 This will unbind the Child Node from its parent $node. The function
161 returns the unbound node. If $childnode is not a child of the given
162 Node the function will fail.
163 replaceChild
165 $oldnode = $node->replaceChild( $newNode, $oldNode );
166 Replaces the $oldNode with the $newNode. The $oldNode will be
168 unbound from the Node. This function differs from the DOM L2
169 specification, in the case, if the new node is not part of the
170 document, the node will be imported first.
171 replaceNode
173 $node->replaceNode($newNode);
174 This function is very similar to replaceChild(), but it replaces
176 the node itself rather than a childnode. This is useful if a node
177 found by any XPath function, should be replaced.
178 appendChild
180 $childnode = $node->appendChild( $childnode );
181 The function will add the $childnode to the end of $node's
183 children. The function should fail, if the new childnode is already
184 a child of $node. This function differs from the DOM L2
185 specification, in the case, if the new node is not part of the
186 document, the node will be imported first.
187 addChild
189 $childnode = $node->addChild( $childnode );
190 As an alternative to appendChild() one can use the addChild()
192 function. This function is a bit faster, because it avoids all DOM
193 conformity checks. Therefore this function is quite useful if one
194 builds XML documents in memory where the order and ownership
195 ("ownerDocument") is assured.
196 addChild() uses libxml2's own xmlAddChild() function. Thus it has
198 to be used with extra care: If a text node is added to a node and
199 the node itself or its last childnode is as well a text node, the
200 node to add will be merged with the one already available. The
201 current node will be removed from memory after this action. Because
202 perl is not aware of this action, the perl instance is still
203 available. XML::LibXML will catch the loss of a node and refuse to
204 run any function called on that node.
205 my $t1 = $doc->createTextNode( "foo" );
207 my $t2 = $doc->createTextNode( "bar" );
208 $t1->addChild( $t2 ); # is OK
209 my $val = $t2->nodeValue(); # will fail, script dies
210 Also addChild() will not check if the added node belongs to the
212 same document as the node it will be added to. This could lead to
213 inconsistent documents and in more worse cases even to memory
214 violations, if one does not keep track of this issue.
215 Although this sounds like a lot of trouble, addChild() is useful if
217 a document is built from a stream, such as happens sometimes in SAX
218 handlers or filters.
219 If you are not sure about the source of your nodes, you better stay
221 with appendChild(), because this function is more user friendly in
222 the sense of being more error tolerant.
223 addNewChild
225 $node = $parent->addNewChild( $nsURI, $name );
226 Similar to "addChild()", this function uses low level libxml2
228 functionality to provide faster interface for DOM building.
229 addNewChild() uses "xmlNewChild()" to create a new node on a given
230 parent element.
231 addNewChild() has two parameters $nsURI and $name, where $nsURI is
233 an (optional) namespace URI. $name is the fully qualified element
234 name; addNewChild() will determine the correct prefix if necessary.
235 The function returns the newly created node.
237 This function is very useful for DOM building, where a created node
239 can be directly associated with its parent. NOTE this function is
240 not part of the DOM specification and its use will limit your code
241 to XML::LibXML.
242 addSibling
244 $node->addSibling($newNode);
245 addSibling() allows adding an additional node to the end of a
247 nodelist, defined by the given node.
248 cloneNode
250 $newnode =$node->cloneNode( $deep );
251 cloneNode creates a copy of $node. When $deep is set to 1 (true)
253 the function will copy all child nodes as well. If $deep is 0 only
254 the current node will be copied. Note that in case of element,
255 attributes are copied even if $deep is 0.
256 Note that the behavior of this function for $deep=0 has changed in
258 1.62 in order to be consistent with the DOM spec (in older versions
259 attributes and namespace information was not copied for elements).
260 parentNode
262 $parentnode = $node->parentNode;
263 Returns simply the Parent Node of the current node.
265 nextSibling
267 $nextnode = $node->nextSibling();
268 Returns the next sibling if any .
270 nextNonBlankSibling
272 $nextnode = $node->nextNonBlankSibling();
273 Returns the next non-blank sibling if any (a node is blank if it is
275 a Text or CDATA node consisting of whitespace only). This method is
276 not defined by DOM.
277 previousSibling
279 $prevnode = $node->previousSibling();
280 Analogous to getNextSibling the function returns the previous
282 sibling if any.
283 previousNonBlankSibling
285 $prevnode = $node->previousNonBlankSibling();
286 Returns the previous non-blank sibling if any (a node is blank if
288 it is a Text or CDATA node consisting of whitespace only). This
289 method is not defined by DOM.
290 hasChildNodes
292 $boolean = $node->hasChildNodes();
293 If the current node has child nodes this function returns TRUE (1),
295 otherwise it returns FALSE (0, not undef).
296 firstChild
298 $childnode = $node->firstChild;
299 If a node has child nodes this function will return the first node
301 in the child list.
302 lastChild
304 $childnode = $node->lastChild;
305 If the $node has child nodes this function returns the last child
307 node.
308 ownerDocument
310 $documentnode = $node->ownerDocument;
311 Through this function it is always possible to access the document
313 the current node is bound to.
314 getOwner
316 $node = $node->getOwner;
317 This function returns the node the current node is associated with.
319 In most cases this will be a document node or a document fragment
320 node.
321 setOwnerDocument
323 $node->setOwnerDocument( $doc );
324 This function binds a node to another DOM. This method unbinds the
326 node first, if it is already bound to another document.
327 This function is the opposite calling of XML::LibXML::Document's
329 adoptNode() function. Because of this it has the same limitations
330 with Entity References as adoptNode().
331 insertBefore
333 $node->insertBefore( $newNode, $refNode );
334 The method inserts $newNode before $refNode. If $refNode is
336 undefined, the newNode will be set as the new last child of the
337 parent node. This function differs from the DOM L2 specification,
338 in the case, if the new node is not part of the document, the node
339 will be imported first, automatically.
340 $refNode has to be passed to the function even if it is undefined:
342 $node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode );
344 $node->insertBefore( $newNode ); # wrong
345 Note, that the reference node has to be a direct child of the node
347 the function is called on. Also, $newChild is not allowed to be an
348 ancestor of the new parent node.
349 insertAfter
351 $node->insertAfter( $newNode, $refNode );
352 The method inserts $newNode after $refNode. If $refNode is
354 undefined, the newNode will be set as the new last child of the
355 parent node.
356 Note, that $refNode has to be passed explicitly even if it is
358 undef.
359 findnodes
361 @nodes = $node->findnodes( $xpath_expression );
362 findnodes evaluates the xpath expression (XPath 1.0) on the current
364 node and returns the resulting node set as an array. In scalar
365 context, returns an XML::LibXML::NodeList object.
366 The xpath expression can be passed either as a string, or as a
368 XML::LibXML::XPathExpression object.
369 NOTE ON NAMESPACES AND XPATH:
371 A common mistake about XPath is to assume that node tests
373 consisting of an element name with no prefix match elements in the
374 default namespace. This assumption is wrong - by XPath
375 specification, such node tests can only match elements that are in
376 no (i.e. null) namespace.
377 So, for example, one cannot match the root element of an XHTML
379 document with "$node->find('/html')" since '/html' would only match
380 if the root element "<html>" had no namespace, but all XHTML
381 elements belong to the namespace http://www.w3.org/1999/xhtml.
382 (Note that "xmlns="..."" namespace declarations can also be
383 specified in a DTD, which makes the situation even worse, since the
384 XML document looks as if there was no default namespace).
385 There are several possible ways to deal with namespaces in XPath:
387 • The recommended way is to use the XML::LibXML::XPathContext
389 module to define an explicit context for XPath evaluation, in
390 which a document independent prefix-to-namespace mapping can be
391 defined. For example:
392 my $xpc = XML::LibXML::XPathContext->new;
394 $xpc->registerNs('x', 'http://www.w3.org/1999/xhtml');
395 $xpc->find('/x:html',$node);
396 • Another possibility is to use prefixes declared in the queried
398 document (if known). If the document declares a prefix for the
399 namespace in question (and the context node is in the scope of
400 the declaration), "XML::LibXML" allows you to use the prefix in
401 the XPath expression, e.g.:
402 $node->find('/x:html');
404 See also XML::LibXML::XPathContext->findnodes.
406 find
408 $result = $node->find( $xpath );
409 find evaluates the XPath 1.0 expression using the current node as
411 the context of the expression, and returns the result depending on
412 what type of result the XPath expression had. For example, the
413 XPath "1 * 3 + 52" results in a XML::LibXML::Number object being
414 returned. Other expressions might return an XML::LibXML::Boolean
415 object, or an XML::LibXML::Literal object (a string). Each of those
416 objects uses Perl's overload feature to "do the right thing" in
417 different contexts.
418 The xpath expression can be passed either as a string, or as a
420 XML::LibXML::XPathExpression object.
421 See also XML::LibXML::XPathContext->find.
423 findvalue
425 print $node->findvalue( $xpath );
426 findvalue is exactly equivalent to:
428 $node->find( $xpath )->to_literal;
430 That is, it returns the literal value of the results. This enables
432 you to ensure that you get a string back from your search, allowing
433 certain shortcuts. This could be used as the equivalent of XSLT's
434 <xsl:value-of select="some_xpath"/>.
435 See also XML::LibXML::XPathContext->findvalue.
437 The xpath expression can be passed either as a string, or as a
439 XML::LibXML::XPathExpression object.
440 exists
442 $bool = $node->exists( $xpath_expression );
443 This method behaves like findnodes, except that it only returns a
445 boolean value (1 if the expression matches a node, 0 otherwise) and
446 may be faster than findnodes, because the XPath evaluation may stop
447 early on the first match (this is true for libxml2 >= 2.6.27).
448 For XPath expressions that do not return node-set, the method
450 returns true if the returned value is a non-zero number or a non-
451 empty string.
452 childNodes
454 @childnodes = $node->childNodes();
455 childNodes implements a more intuitive interface to the childnodes
457 of the current node. It enables you to pass all children directly
458 to a "map" or "grep". If this function is called in scalar context,
459 a XML::LibXML::NodeList object will be returned.
460 nonBlankChildNodes
462 @childnodes = $node->nonBlankChildNodes();
463 This is like childNodes, but returns only non-blank nodes (where a
465 node is blank if it is a Text or CDATA node consisting of
466 whitespace only). This method is not defined by DOM.
467 toString
469 $xmlstring = $node->toString($format,$docencoding);
470 This method is similar to the method "toString" of a
472 XML::LibXML::Document but for a single node. It returns a string
473 consisting of XML serialization of the given node and all its
474 descendants. Unlike "XML::LibXML::Document::toString", in this case
475 the resulting string is by default a character string (UTF-8
476 encoded with UTF8 flag on). An optional flag $format controls
477 indentation, as in "XML::LibXML::Document::toString". If the second
478 optional $docencoding flag is true, the result will be a byte
479 string in the document encoding (see
480 "XML::LibXML::Document::actualEncoding").
481 toStringC14N
483 $c14nstring = $node->toStringC14N();
484 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
485 The function is similar to toString(). Instead of simply
487 serializing the document tree, it transforms it as it is specified
488 in the XML-C14N Specification (see
489 <http://www.w3.org/TR/xml-c14n>). Such transformation is known as
490 canonization.
491 If $with_comments is 0 or not defined, the result-document will not
493 contain any comments that exist in the original document. To
494 include comments into the canonized document, $with_comments has to
495 be set to 1.
496 The parameter $xpath_expression defines the nodeset of nodes that
498 should be visible in the resulting document. This can be used to
499 filter out some nodes. One has to note, that only the nodes that
500 are part of the nodeset, will be included into the result-document.
501 Their child-nodes will not exist in the resulting document, unless
502 they are part of the nodeset defined by the xpath expression.
503 If $xpath_expression is omitted or empty, toStringC14N() will
505 include all nodes in the given sub-tree, using the following XPath
506 expressions: with comments
507 (. | .//node() | .//@* | .//namespace::*)
509 and without comments
511 (. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
513 An optional parameter $xpath_context can be used to pass an
515 XML::LibXML::XPathContext object defining the context for
516 evaluation of $xpath_expression. This is useful for mapping
517 namespace prefixes used in the XPath expression to namespace URIs.
518 Note, however, that $node will be used as the context node for the
519 evaluation, not the context node of $xpath_context!
520 toStringC14N_v1_1
522 $c14nstring = $node->toStringC14N_v1_1();
523 $c14nstring = $node->toStringC14N_v1_1($with_comments, $xpath_expression , $xpath_context);
524 This function behaves like toStringC14N() except that it uses the
526 "XML_C14N_1_1" constant for canonicalising using the "C14N 1.1
527 spec".
528 toStringEC14N
530 $ec14nstring = $node->toStringEC14N();
531 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
532 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
533 The function is similar to toStringC14N() but follows the
535 XML-EXC-C14N Specification (see
536 <http://www.w3.org/TR/xml-exc-c14n>) for exclusive canonization of
537 XML.
538 The arguments $with_comments, $xpath_expression, $xpath_context are
540 as in toStringC14N(). An ARRAY reference can be passed as the last
541 argument $inclusive_prefix_list, listing namespace prefixes that
542 are to be handled in the manner described by the Canonical XML
543 Recommendation (i.e. preserved in the output even if the namespace
544 is not used). C.f. the spec for details.
545 serialize
547 $str = $doc->serialize($format);
548 An alias for toString(). This function was name added to be more
550 consistent with libxml2.
551 serialize_c14n
553 An alias for toStringC14N().
554 serialize_exc_c14n
556 An alias for toStringEC14N().
557 localname
559 $localname = $node->localname;
560 Returns the local name of a tag. This is the part behind the colon.
562 prefix
564 $nameprefix = $node->prefix;
565 Returns the prefix of a tag. This is the part before the colon.
567 namespaceURI
569 $uri = $node->namespaceURI();
570 returns the URI of the current namespace.
572 hasAttributes
574 $boolean = $node->hasAttributes();
575 returns 1 (TRUE) if the current node has any attributes set,
577 otherwise 0 (FALSE) is returned.
578 attributes
580 @attributelist = $node->attributes();
581 This function returns all attributes and namespace declarations
583 assigned to the given node.
584 Because XML::LibXML does not implement namespace declarations and
586 attributes the same way, it is required to test what kind of node
587 is handled while accessing the functions result.
588 If this function is called in array context the attribute nodes are
590 returned as an array. In scalar context, the function will return a
591 XML::LibXML::NamedNodeMap object.
592 lookupNamespaceURI
594 $URI = $node->lookupNamespaceURI( $prefix );
595 Find a namespace URI by its prefix starting at the current node.
597 lookupNamespacePrefix
599 $prefix = $node->lookupNamespacePrefix( $URI );
600 Find a namespace prefix by its URI starting at the current node.
602 NOTE Only the namespace URIs are meant to be unique. The prefix is
604 only document related. Also the document might have more than a
605 single prefix defined for a namespace.
606 normalize
608 $node->normalize;
609 This function normalizes adjacent text nodes. This function is not
611 as strict as libxml2's xmlTextMerge() function, since it will not
612 free a node that is still referenced by the perl layer.
613 getNamespaces
615 @nslist = $node->getNamespaces;
616 If a node has any namespaces defined, this function will return
618 these namespaces. Note, that this will not return all namespaces
619 that are in scope, but only the ones declared explicitly for that
620 node.
621 Although getNamespaces is available for all nodes, it only makes
623 sense if used with element nodes.
624 removeChildNodes
626 $node->removeChildNodes();
627 This function is not specified for any DOM level: It removes all
629 childnodes from a node in a single step. Other than the libxml2
630 function itself (xmlFreeNodeList), this function will not
631 immediately remove the nodes from the memory. This saves one from
632 getting memory violations, if there are nodes still referred to
633 from the Perl level.
634 baseURI ()
636 $strURI = $node->baseURI();
637 Searches for the base URL of the node. The method should work on
639 both XML and HTML documents even if base mechanisms for these are
640 completely different. It returns the base as defined in RFC 2396
641 sections "5.1.1. Base URI within Document Content" and "5.1.2. Base
642 URI from the Encapsulating Entity". However it does not return the
643 document base (5.1.3), use method "URI" of "XML::LibXML::Document"
644 for this.
645 setBaseURI ($strURI)
647 $node->setBaseURI($strURI);
648 This method only does something useful for an element node in an
650 XML document. It sets the xml:base attribute on the node to
651 $strURI, which effectively sets the base URI of the node to the
652 same value.
653 Note: For HTML documents this behaves as if the document was XML
655 which may not be desired, since it does not effectively set the
656 base URI of the node. See RFC 2396 appendix D for an example of how
657 base URI can be specified in HTML.
658 nodePath
660 $node->nodePath();
661 This function is not specified for any DOM level: It returns a
663 canonical structure based XPath for a given node.
664 line_number
666 $lineno = $node->line_number();
667 This function returns the line number where the tag was found
669 during parsing. If a node is added to the document the line number
670 is 0. Problems may occur, if a node from one document is passed to
671 another one.
672 IMPORTANT: Due to limitations in the libxml2 library line numbers
674 greater than 65535 will be returned as 65535. Please see
675 <http://bugzilla.gnome.org/show_bug.cgi?id=325533> for more
676 details.
677 Note: line_number() is special to XML::LibXML and not part of the
679 DOM specification.
680 If the line_numbers flag of the parser was not activated before
682 parsing, line_number() will always return 0.
683
685 Matt Sergeant, Christian Glahn, Petr Pajas
686
688 2.0207
689
691 2001-2007, AxKit.com Ltd.
692 2002-2006, Christian Glahn.
694 2006-2009, Petr Pajas.
696
698 This program is free software; you can redistribute it and/or modify it
699 under the same terms as Perl itself.
700perl v5.34.0 2022-01-21 XML::LibXML::Node(3)