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 NOTEcloneNode creates a copy of the selected node that includes the
262 parent's defined namespaces that are in use by the node (or its
263 children) being cloned. That makes it useful for extracting a
264 fragment of xml that can be used as a valid xml document.
265 parentNode
267 $parentnode = $node->parentNode;
268 Returns simply the Parent Node of the current node.
270 nextSibling
272 $nextnode = $node->nextSibling();
273 Returns the next sibling if any .
275 nextNonBlankSibling
277 $nextnode = $node->nextNonBlankSibling();
278 Returns the next non-blank sibling if any (a node is blank if it is
280 a Text or CDATA node consisting of whitespace only). This method is
281 not defined by DOM.
282 previousSibling
284 $prevnode = $node->previousSibling();
285 Analogous to getNextSibling the function returns the previous
287 sibling if any.
288 previousNonBlankSibling
290 $prevnode = $node->previousNonBlankSibling();
291 Returns the previous non-blank sibling if any (a node is blank if
293 it is a Text or CDATA node consisting of whitespace only). This
294 method is not defined by DOM.
295 hasChildNodes
297 $boolean = $node->hasChildNodes();
298 If the current node has child nodes this function returns TRUE (1),
300 otherwise it returns FALSE (0, not undef).
301 firstChild
303 $childnode = $node->firstChild;
304 If a node has child nodes this function will return the first node
306 in the child list.
307 lastChild
309 $childnode = $node->lastChild;
310 If the $node has child nodes this function returns the last child
312 node.
313 ownerDocument
315 $documentnode = $node->ownerDocument;
316 Through this function it is always possible to access the document
318 the current node is bound to.
319 getOwner
321 $node = $node->getOwner;
322 This function returns the node the current node is associated with.
324 In most cases this will be a document node or a document fragment
325 node.
326 setOwnerDocument
328 $node->setOwnerDocument( $doc );
329 This function binds a node to another DOM. This method unbinds the
331 node first, if it is already bound to another document.
332 This function is the opposite calling of XML::LibXML::Document's
334 adoptNode() function. Because of this it has the same limitations
335 with Entity References as adoptNode().
336 insertBefore
338 $node->insertBefore( $newNode, $refNode );
339 The method inserts $newNode before $refNode. If $refNode is
341 undefined, the newNode will be set as the new last child of the
342 parent node. This function differs from the DOM L2 specification,
343 in the case, if the new node is not part of the document, the node
344 will be imported first, automatically.
345 $refNode has to be passed to the function even if it is undefined:
347 $node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode );
349 $node->insertBefore( $newNode ); # wrong
350 Note, that the reference node has to be a direct child of the node
352 the function is called on. Also, $newChild is not allowed to be an
353 ancestor of the new parent node.
354 insertAfter
356 $node->insertAfter( $newNode, $refNode );
357 The method inserts $newNode after $refNode. If $refNode is
359 undefined, the newNode will be set as the new last child of the
360 parent node.
361 Note, that $refNode has to be passed explicitly even if it is
363 undef.
364 findnodes
366 @nodes = $node->findnodes( $xpath_expression );
367 findnodes evaluates the xpath expression (XPath 1.0) on the current
369 node and returns the resulting node set as an array. In scalar
370 context, returns an XML::LibXML::NodeList object.
371 The xpath expression can be passed either as a string, or as a
373 XML::LibXML::XPathExpression object.
374 NOTE ON NAMESPACES AND XPATH:
376 A common mistake about XPath is to assume that node tests
378 consisting of an element name with no prefix match elements in the
379 default namespace. This assumption is wrong - by XPath
380 specification, such node tests can only match elements that are in
381 no (i.e. null) namespace.
382 So, for example, one cannot match the root element of an XHTML
384 document with "$node->find('/html')" since '/html' would only match
385 if the root element "<html>" had no namespace, but all XHTML
386 elements belong to the namespace http://www.w3.org/1999/xhtml.
387 (Note that "xmlns="..."" namespace declarations can also be
388 specified in a DTD, which makes the situation even worse, since the
389 XML document looks as if there was no default namespace).
390 There are several possible ways to deal with namespaces in XPath:
392 • The recommended way is to use the XML::LibXML::XPathContext
394 module to define an explicit context for XPath evaluation, in
395 which a document independent prefix-to-namespace mapping can be
396 defined. For example:
397 my $xpc = XML::LibXML::XPathContext->new;
399 $xpc->registerNs('x', 'http://www.w3.org/1999/xhtml');
400 $xpc->find('/x:html',$node);
401 • Another possibility is to use prefixes declared in the queried
403 document (if known). If the document declares a prefix for the
404 namespace in question (and the context node is in the scope of
405 the declaration), "XML::LibXML" allows you to use the prefix in
406 the XPath expression, e.g.:
407 $node->find('/x:html');
409 See also XML::LibXML::XPathContext->findnodes.
411 find
413 $result = $node->find( $xpath );
414 find evaluates the XPath 1.0 expression using the current node as
416 the context of the expression, and returns the result depending on
417 what type of result the XPath expression had. For example, the
418 XPath "1 * 3 + 52" results in a XML::LibXML::Number object being
419 returned. Other expressions might return an XML::LibXML::Boolean
420 object, or an XML::LibXML::Literal object (a string). Each of those
421 objects uses Perl's overload feature to "do the right thing" in
422 different contexts.
423 The xpath expression can be passed either as a string, or as a
425 XML::LibXML::XPathExpression object.
426 See also XML::LibXML::XPathContext->find.
428 findvalue
430 print $node->findvalue( $xpath );
431 findvalue is exactly equivalent to:
433 $node->find( $xpath )->to_literal;
435 That is, it returns the literal value of the results. This enables
437 you to ensure that you get a string back from your search, allowing
438 certain shortcuts. This could be used as the equivalent of XSLT's
439 <xsl:value-of select="some_xpath"/>.
440 See also XML::LibXML::XPathContext->findvalue.
442 The xpath expression can be passed either as a string, or as a
444 XML::LibXML::XPathExpression object.
445 exists
447 $bool = $node->exists( $xpath_expression );
448 This method behaves like findnodes, except that it only returns a
450 boolean value (1 if the expression matches a node, 0 otherwise) and
451 may be faster than findnodes, because the XPath evaluation may stop
452 early on the first match (this is true for libxml2 >= 2.6.27).
453 For XPath expressions that do not return node-set, the method
455 returns true if the returned value is a non-zero number or a non-
456 empty string.
457 childNodes
459 @childnodes = $node->childNodes();
460 childNodes implements a more intuitive interface to the childnodes
462 of the current node. It enables you to pass all children directly
463 to a "map" or "grep". If this function is called in scalar context,
464 a XML::LibXML::NodeList object will be returned.
465 nonBlankChildNodes
467 @childnodes = $node->nonBlankChildNodes();
468 This is like childNodes, but returns only non-blank nodes (where a
470 node is blank if it is a Text or CDATA node consisting of
471 whitespace only). This method is not defined by DOM.
472 toString
474 $xmlstring = $node->toString($format,$docencoding);
475 This method is similar to the method "toString" of a
477 XML::LibXML::Document but for a single node. It returns a string
478 consisting of XML serialization of the given node and all its
479 descendants. Unlike "XML::LibXML::Document::toString", in this case
480 the resulting string is by default a character string (UTF-8
481 encoded with UTF8 flag on). An optional flag $format controls
482 indentation, as in "XML::LibXML::Document::toString". If the second
483 optional $docencoding flag is true, the result will be a byte
484 string in the document encoding (see
485 "XML::LibXML::Document::actualEncoding").
486 toStringC14N
488 $c14nstring = $node->toStringC14N();
489 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
490 The function is similar to toString(). Instead of simply
492 serializing the document tree, it transforms it as it is specified
493 in the XML-C14N Specification (see
494 <http://www.w3.org/TR/xml-c14n>). Such transformation is known as
495 canonization.
496 If $with_comments is 0 or not defined, the result-document will not
498 contain any comments that exist in the original document. To
499 include comments into the canonized document, $with_comments has to
500 be set to 1.
501 The parameter $xpath_expression defines the nodeset of nodes that
503 should be visible in the resulting document. This can be used to
504 filter out some nodes. One has to note, that only the nodes that
505 are part of the nodeset, will be included into the result-document.
506 Their child-nodes will not exist in the resulting document, unless
507 they are part of the nodeset defined by the xpath expression.
508 If $xpath_expression is omitted or empty, toStringC14N() will
510 include all nodes in the given sub-tree, using the following XPath
511 expressions: with comments
512 (. | .//node() | .//@* | .//namespace::*)
514 and without comments
516 (. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
518 An optional parameter $xpath_context can be used to pass an
520 XML::LibXML::XPathContext object defining the context for
521 evaluation of $xpath_expression. This is useful for mapping
522 namespace prefixes used in the XPath expression to namespace URIs.
523 Note, however, that $node will be used as the context node for the
524 evaluation, not the context node of $xpath_context!
525 toStringC14N_v1_1
527 $c14nstring = $node->toStringC14N_v1_1();
528 $c14nstring = $node->toStringC14N_v1_1($with_comments, $xpath_expression , $xpath_context);
529 This function behaves like toStringC14N() except that it uses the
531 "XML_C14N_1_1" constant for canonicalising using the "C14N 1.1
532 spec".
533 toStringEC14N
535 $ec14nstring = $node->toStringEC14N();
536 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
537 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
538 The function is similar to toStringC14N() but follows the
540 XML-EXC-C14N Specification (see
541 <http://www.w3.org/TR/xml-exc-c14n>) for exclusive canonization of
542 XML.
543 The arguments $with_comments, $xpath_expression, $xpath_context are
545 as in toStringC14N(). An ARRAY reference can be passed as the last
546 argument $inclusive_prefix_list, listing namespace prefixes that
547 are to be handled in the manner described by the Canonical XML
548 Recommendation (i.e. preserved in the output even if the namespace
549 is not used). C.f. the spec for details.
550 serialize
552 $str = $doc->serialize($format);
553 An alias for toString(). This function was name added to be more
555 consistent with libxml2.
556 serialize_c14n
558 An alias for toStringC14N().
559 serialize_exc_c14n
561 An alias for toStringEC14N().
562 localname
564 $localname = $node->localname;
565 Returns the local name of a tag. This is the part behind the colon.
567 prefix
569 $nameprefix = $node->prefix;
570 Returns the prefix of a tag. This is the part before the colon.
572 namespaceURI
574 $uri = $node->namespaceURI();
575 returns the URI of the current namespace.
577 hasAttributes
579 $boolean = $node->hasAttributes();
580 returns 1 (TRUE) if the current node has any attributes set,
582 otherwise 0 (FALSE) is returned.
583 attributes
585 @attributelist = $node->attributes();
586 This function returns all attributes and namespace declarations
588 assigned to the given node.
589 Because XML::LibXML does not implement namespace declarations and
591 attributes the same way, it is required to test what kind of node
592 is handled while accessing the functions result.
593 If this function is called in array context the attribute nodes are
595 returned as an array. In scalar context, the function will return a
596 XML::LibXML::NamedNodeMap object.
597 lookupNamespaceURI
599 $URI = $node->lookupNamespaceURI( $prefix );
600 Find a namespace URI by its prefix starting at the current node.
602 lookupNamespacePrefix
604 $prefix = $node->lookupNamespacePrefix( $URI );
605 Find a namespace prefix by its URI starting at the current node.
607 NOTE Only the namespace URIs are meant to be unique. The prefix is
609 only document related. Also the document might have more than a
610 single prefix defined for a namespace.
611 normalize
613 $node->normalize;
614 This function normalizes adjacent text nodes. This function is not
616 as strict as libxml2's xmlTextMerge() function, since it will not
617 free a node that is still referenced by the perl layer.
618 getNamespaces
620 @nslist = $node->getNamespaces;
621 If a node has any namespaces defined, this function will return
623 these namespaces. Note, that this will not return all namespaces
624 that are in scope, but only the ones declared explicitly for that
625 node.
626 Although getNamespaces is available for all nodes, it only makes
628 sense if used with element nodes.
629 removeChildNodes
631 $node->removeChildNodes();
632 This function is not specified for any DOM level: It removes all
634 childnodes from a node in a single step. Other than the libxml2
635 function itself (xmlFreeNodeList), this function will not
636 immediately remove the nodes from the memory. This saves one from
637 getting memory violations, if there are nodes still referred to
638 from the Perl level.
639 baseURI ()
641 $strURI = $node->baseURI();
642 Searches for the base URL of the node. The method should work on
644 both XML and HTML documents even if base mechanisms for these are
645 completely different. It returns the base as defined in RFC 2396
646 sections "5.1.1. Base URI within Document Content" and "5.1.2. Base
647 URI from the Encapsulating Entity". However it does not return the
648 document base (5.1.3), use method "URI" of "XML::LibXML::Document"
649 for this.
650 setBaseURI ($strURI)
652 $node->setBaseURI($strURI);
653 This method only does something useful for an element node in an
655 XML document. It sets the xml:base attribute on the node to
656 $strURI, which effectively sets the base URI of the node to the
657 same value.
658 Note: For HTML documents this behaves as if the document was XML
660 which may not be desired, since it does not effectively set the
661 base URI of the node. See RFC 2396 appendix D for an example of how
662 base URI can be specified in HTML.
663 nodePath
665 $node->nodePath();
666 This function is not specified for any DOM level: It returns a
668 canonical structure based XPath for a given node.
669 line_number
671 $lineno = $node->line_number();
672 This function returns the line number where the tag was found
674 during parsing. If a node is added to the document the line number
675 is 0. Problems may occur, if a node from one document is passed to
676 another one.
677 IMPORTANT: Due to limitations in the libxml2 library line numbers
679 greater than 65535 will be returned as 65535. Please see
680 <http://bugzilla.gnome.org/show_bug.cgi?id=325533> for more
681 details.
682 Note: line_number() is special to XML::LibXML and not part of the
684 DOM specification.
685 If the line_numbers flag of the parser was not activated before
687 parsing, line_number() will always return 0.
688
690 Matt Sergeant, Christian Glahn, Petr Pajas
691
693 2.0209
694
696 2001-2007, AxKit.com Ltd.
697 2002-2006, Christian Glahn.
699 2006-2009, Petr Pajas.
701
703 This program is free software; you can redistribute it and/or modify it
704 under the same terms as Perl itself.
705perl v5.38.0 2023-07-21 XML::LibXML::Node(3)