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/>). Please
80 refer to the specification for extensive documentation.
81 nodeName
83 $name = $node->nodeName;
84 Returns the node's name. This function is aware of namespaces and
86 returns the full name of the current node ("prefix:localname").
87 Since 1.62 this function also returns the correct DOM names for
89 node types with constant names, namely: #text, #cdata-section,
90 #comment, #document, #document-fragment.
91 setNodeName
93 $node->setNodeName( $newName );
94 In very limited situations, it is useful to change a nodes name. In
96 the DOM specification this should throw an error. This Function is
97 aware of namespaces.
98 isSameNode
100 $bool = $node->isSameNode( $other_node );
101 returns TRUE (1) if the given nodes refer to the same node
103 structure, otherwise FALSE (0) is returned.
104 isEqual
106 $bool = $node->isEqual( $other_node );
107 deprecated version of isSameNode().
109 NOTE isEqual will change behaviour to follow the DOM specification
111 nodeValue
113 $content = $node->nodeValue;
114 If the node has any content (such as stored in a "text node") it
116 can get requested through this function.
117 NOTE: Element Nodes have no content per definition. To get the text
119 value of an Element use textContent() instead!
120 textContent
122 $content = $node->textContent;
123 this function returns the content of all text nodes in the
125 descendants of the given node as specified in DOM.
126 nodeType
128 $type = $node->nodeType;
129 Return a numeric value representing the node type of this node. The
131 module XML::LibXML by default exports constants for the node types
132 (see the EXPORT section in the XML::LibXML manual page).
133 unbindNode
135 $node->unbindNode();
136 Unbinds the Node from its siblings and Parent, but not from the
138 Document it belongs to. If the node is not inserted into the DOM
139 afterwards it will be lost after the program terminated. From a low
140 level view, the unbound node is stripped from the context it is and
141 inserted into a (hidden) document-fragment.
142 removeChild
144 $childnode = $node->removeChild( $childnode );
145 This will unbind the Child Node from its parent $node. The function
147 returns the unbound node. If "oldNode" is not a child of the given
148 Node the function will fail.
149 replaceChild
151 $oldnode = $node->replaceChild( $newNode, $oldNode );
152 Replaces the $oldNode with the $newNode. The $oldNode will be
154 unbound from the Node. This function differs from the DOM L2
155 specification, in the case, if the new node is not part of the
156 document, the node will be imported first.
157 replaceNode
159 $node->replaceNode($newNode);
160 This function is very similar to replaceChild(), but it replaces
162 the node itself rather than a childnode. This is useful if a node
163 found by any XPath function, should be replaced.
164 appendChild
166 $childnode = $node->appendChild( $childnode );
167 The function will add the $childnode to the end of $node's
169 children. The function should fail, if the new childnode is already
170 a child of $node. This function differs from the DOM L2
171 specification, in the case, if the new node is not part of the
172 document, the node will be imported first.
173 addChild
175 $childnode = $node->addChild( $chilnode );
176 As an alternative to appendChild() one can use the addChild()
178 function. This function is a bit faster, because it avoids all DOM
179 conformity checks. Therefore this function is quite useful if one
180 builds XML documents in memory where the order and ownership
181 ("ownerDocument") is assured.
182 addChild() uses libxml2's own xmlAddChild() function. Thus it has
184 to be used with extra care: If a text node is added to a node and
185 the node itself or its last childnode is as well a text node, the
186 node to add will be merged with the one already available. The
187 current node will be removed from memory after this action. Because
188 perl is not aware of this action, the perl instance is still
189 available. XML::LibXML will catch the loss of a node and refuse to
190 run any function called on that node.
191 my $t1 = $doc->createTextNode( "foo" );
193 my $t2 = $doc->createTextNode( "bar" );
194 $t1->addChild( $t2 ); # is OK
195 my $val = $t2->nodeValue(); # will fail, script dies
196 Also addChild() will not check if the added node belongs to the
198 same document as the node it will be added to. This could lead to
199 inconsistent documents and in more worse cases even to memory
200 violations, if one does not keep track of this issue.
201 Although this sounds like a lot of trouble, addChild() is useful if
203 a document is built from a stream, such as happens sometimes in SAX
204 handlers or filters.
205 If you are not sure about the source of your nodes, you better stay
207 with appendChild(), because this function is more user friendly in
208 the sense of being more error tolerant.
209 addNewChild
211 $node = $parent->addNewChild( $nsURI, $name );
212 Similar to "addChild()", this function uses low level libxml2
214 functionality to provide faster interface for DOM building.
215 addNewChild() uses "xmlNewChild()" to create a new node on a given
216 parent element.
217 addNewChild() has two parameters $nsURI and $name, where $nsURI is
219 an (optional) namespace URI. $name is the fully qualified element
220 name; addNewChild() will determine the correct prefix if necessary.
221 The function returns the newly created node.
223 This function is very useful for DOM building, where a created node
225 can be directly associated with its parent. NOTE this function is
226 not part of the DOM specification and its use will limit your code
227 to XML::LibXML.
228 addSibling
230 $node->addSibling($newNode);
231 addSibling() allows adding an additional node to the end of a
233 nodelist, defined by the given node.
234 cloneNode
236 $newnode =$node->cloneNode( $deep );
237 cloneNode creates a copy of $node. When $deep is set to 1 (true)
239 the function will copy all childnodes as well. If $deep is 0 only
240 the current node will be copied. Note that in case of element,
241 attributes are copied even if $deep is 0.
242 Note that the behavior of this function for $deep=0 has changed in
244 1.62 in order to be consistent with the DOM spec (in older versions
245 attributes and namespace information was not copied for elements).
246 parentNode
248 $parentnode = $node->parentNode;
249 Returns simply the Parent Node of the current node.
251 nextSibling
253 $nextnode = $node->nextSibling();
254 Returns the next sibling if any .
256 nextNonBlankSibling
258 $nextnode = $node->nextNonBlankSibling();
259 Returns the next non-blank sibling if any (a node is blank if it is
261 a Text or CDATA node consisting of whitespace only). This method is
262 not defined by DOM.
263 previousSibling
265 $prevnode = $node->previousSibling();
266 Analogous to getNextSibling the function returns the previous
268 sibling if any.
269 previousNonBlankSibling
271 $prevnode = $node->previousNonBlankSibling();
272 Returns the previous non-blank sibling if any (a node is blank if
274 it is a Text or CDATA node consisting of whitespace only). This
275 method is not defined by DOM.
276 hasChildNodes
278 $boolean = $node->hasChildNodes();
279 If the current node has Childnodes this function returns TRUE (1),
281 otherwise it returns FALSE (0, not undef).
282 firstChild
284 $childnode = $node->firstChild;
285 If a node has childnodes this function will return the first node
287 in the childlist.
288 lastChild
290 $childnode = $node->lastChild;
291 If the $node has childnodes this function returns the last child
293 node.
294 ownerDocument
296 $documentnode = $node->ownerDocument;
297 Through this function it is always possible to access the document
299 the current node is bound to.
300 getOwner
302 $node = $node->getOwner;
303 This function returns the node the current node is associated with.
305 In most cases this will be a document node or a document fragment
306 node.
307 setOwnerDocument
309 $node->setOwnerDocument( $doc );
310 This function binds a node to another DOM. This method unbinds the
312 node first, if it is already bound to another document.
313 This function is the opposite calling of XML::LibXML::Document's
315 adoptNode() function. Because of this it has the same limitations
316 with Entity References as adoptNode().
317 insertBefore
319 $node->insertBefore( $newNode, $refNode );
320 The method inserts $newNode before $refNode. If $refNode is
322 undefined, the newNode will be set as the new last child of the
323 parent node. This function differs from the DOM L2 specification,
324 in the case, if the new node is not part of the document, the node
325 will be imported first, automatically.
326 $refNode has to be passed to the function even if it is undefined:
328 $node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode );
330 $node->insertBefore( $newNode ); # wrong
331 Note, that the reference node has to be a direct child of the node
333 the function is called on. Also, $newChild is not allowed to be an
334 ancestor of the new parent node.
335 insertAfter
337 $node->insertAfter( $newNode, $refNode );
338 The method inserts $newNode after $refNode. If $refNode is
340 undefined, the newNode will be set as the new last child of the
341 parent node.
342 Note, that $refNode has to be passed explicitly even if it is
344 undef.
345 findnodes
347 @nodes = $node->findnodes( $xpath_expression );
348 findnodes evaluates the xpath expression (XPath 1.0) on the current
350 node and returns the resulting node set as an array. In scalar
351 context returns a XML::LibXML::NodeList object.
352 The xpath expression can be passed either as a string or or as a
354 XML::LibXML::XPathExpression object.
355 NOTE ON NAMESPACES AND XPATH:
357 A common mistake about XPath is to assume that node tests
359 consisting of an element name with no prefix match elements in the
360 default namespace. This assumption is wrong - by XPath
361 specification, such node tests can only match elements that are in
362 no (i.e. null) namespace.
363 So, for example, one cannot match the root element of an XHTML
365 document with "$node->find('/html')" since '/html' would only match
366 if the root element "<html>" had no namespace, but all XHTML
367 elements belong to the namespace http://www.w3.org/1999/xhtml.
368 (Note that "xmlns="..."" namespace declarations can also be
369 specified in a DTD, which makes the situation even worse, since the
370 XML document looks as if there was no default namespace).
371 There are several possible ways to deal with namespaces in XPath:
373 · The recommended way is to use the XML::LibXML::XPathContext
375 module to define an explicit context for XPath evaluation, in
376 which a document independent prefix-to-namespace mapping can be
377 defined. For example:
378 my $xpc = XML::LibXML::XPathContext->new;
380 $xpc->registerNs('x', 'http://www.w3.org/1999/xhtml');
381 $xpc->find('/x:html',$node);
382 · Another possibility is to use prefixes declared in the queried
384 document (if known). If the document declares a prefix for the
385 namespace in question (and the context node is in the scope of
386 the declaration), "XML::LibXML" allows you to use the prefix in
387 the XPath expression, e.g.:
388 $node->find('/x:html');
390 See also XML::LibXML::XPathContext->findnodes.
392 find
394 $result = $node->find( $xpath );
395 find evaluates the XPath 1.0 expression using the current node as
397 the context of the expression, and returns the result depending on
398 what type of result the XPath expression had. For example, the
399 XPath "1 * 3 + 52" results in a XML::LibXML::Number object being
400 returned. Other expressions might return a XML::LibXML::Boolean
401 object, or a XML::LibXML::Literal object (a string). Each of those
402 objects uses Perl's overload feature to "do the right thing" in
403 different contexts.
404 The xpath expression can be passed either as a string or or as a
406 XML::LibXML::XPathExpression object.
407 See also XML::LibXML::XPathContext->find.
409 findvalue
411 print $node->findvalue( $xpath );
412 findvalue is exactly equivalent to:
414 $node->find( $xpath )->to_literal;
416 That is, it returns the literal value of the results. This enables
418 you to ensure that you get a string back from your search, allowing
419 certain shortcuts. This could be used as the equivalent of XSLT's
420 <xsl:value-of select="some_xpath"/>.
421 See also XML::LibXML::XPathContext->findvalue.
423 The xpath expression can be passed either as a string or or as a
425 XML::LibXML::XPathExpression object.
426 exists
428 $bool = $node->exists( $xpath_expression );
429 This method behaves like findnodes, except that it only returns a
431 boolean value (1 if the expression matches a node, 0 otherwise) and
432 may be faster than findnodes, because the XPath evaluation may stop
433 early on the first match (this is true for libxml2 >= 2.6.27).
434 For XPath expressions that do not return node-set, the method
436 returns true if the returned value is a non-zero number or a non-
437 empty string.
438 childNodes
440 @childnodes = $node->childNodes();
441 childNodes implements a more intuitive interface to the childnodes
443 of the current node. It enables you to pass all children directly
444 to a "map" or "grep". If this function is called in scalar context,
445 a XML::LibXML::NodeList object will be returned.
446 nonBlankChildNodes
448 @childnodes = $node->nonBlankChildNodes();
449 This is like childNodes, but returns only non-blank nodes (where a
451 node is blank if it is a Text or CDATA node consisting of
452 whitespace only). This method is not defined by DOM.
453 toString
455 $xmlstring = $node->toString($format,$docencoding);
456 This method is similar to the method "toString" of a
458 XML::LibXML::Document but for a single node. It returns a string
459 consisting of XML serialization of the given node and all its
460 descendants. Unlike "XML::LibXML::Document::toString", in this case
461 the resulting string is by default a character string (UTF-8
462 encoded with UTF8 flag on). An optional flag $format controls
463 indentation, as in "XML::LibXML::Document::toString". If the second
464 optional $docencoding flag is true, the result will be a byte
465 string in the document encoding (see
466 "XML::LibXML::Document::actualEncoding").
467 toStringC14N
469 $c14nstring = $node->toStringC14N();
470 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
471 The function is similar to toString(). Instead of simply
473 serializing the document tree, it transforms it as it is specified
474 in the XML-C14N Specification (see
475 <http://www.w3.org/TR/xml-c14n>). Such transformation is known as
476 canonization.
477 If $with_comments is 0 or not defined, the result-document will not
479 contain any comments that exist in the original document. To
480 include comments into the canonized document, $with_comments has to
481 be set to 1.
482 The parameter $xpath_expression defines the nodeset of nodes that
484 should be visible in the resulting document. This can be used to
485 filter out some nodes. One has to note, that only the nodes that
486 are part of the nodeset, will be included into the result-document.
487 Their child-nodes will not exist in the resulting document, unless
488 they are part of the nodeset defined by the xpath expression.
489 If $xpath_expression is omitted or empty, toStringC14N() will
491 include all nodes in the given sub-tree, using the following XPath
492 expressions: with comments
493 (. | .//node() | .//@* | .//namespace::*)
495 and without comments
497 (. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
499 An optional parameter $xpath_context can be used to pass an
501 XML::LibXML::XPathContext object defining the context for
502 evaluation of $xpath_expression. This is useful for mapping
503 namespace prefixes used in the XPath expression to namespace URIs.
504 Note, however, that $node will be used as the context node for the
505 evaluation, not the context node of $xpath_context!
506 toStringEC14N
508 $ec14nstring = $node->toStringEC14N();
509 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
510 $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
511 The function is similar to toStringC14N() but follows the
513 XML-EXC-C14N Specification (see
514 <http://www.w3.org/TR/xml-exc-c14n>) for exclusive canonization of
515 XML.
516 The arguments $with_comments, $xpath_expression, $xpath_context are
518 as in toStringC14N(). An ARRAY reference can be passed as the last
519 argument $inclusive_prefix_list, listing namespace prefixes that
520 are to be handled in the manner described by the Canonical XML
521 Recommendation (i.e. preserved in the output even if the namespace
522 is not used). C.f. the spec for details.
523 serialize
525 $str = $doc->serialize($format);
526 An alias for toString(). This function was name added to be more
528 consistent with libxml2.
529 serialize_c14n
531 An alias for toStringC14N().
532 serialize_exc_c14n
534 An alias for toStringEC14N().
535 localname
537 $localname = $node->localname;
538 Returns the local name of a tag. This is the part behind the colon.
540 prefix
542 $nameprefix = $node->prefix;
543 Returns the prefix of a tag. This is the part before the colon.
545 namespaceURI
547 $uri = $node->namespaceURI();
548 returns the URI of the current namespace.
550 hasAttributes
552 $boolean = $node->hasAttributes();
553 returns 1 (TRUE) if the current node has any attributes set,
555 otherwise 0 (FALSE) is returned.
556 attributes
558 @attributelist = $node->attributes();
559 This function returns all attributes and namespace declarations
561 assigned to the given node.
562 Because XML::LibXML does not implement namespace declarations and
564 attributes the same way, it is required to test what kind of node
565 is handled while accessing the functions result.
566 If this function is called in array context the attribute nodes are
568 returned as an array. In scalar context the function will return a
569 XML::LibXML::NamedNodeMap object.
570 lookupNamespaceURI
572 $URI = $node->lookupNamespaceURI( $prefix );
573 Find a namespace URI by its prefix starting at the current node.
575 lookupNamespacePrefix
577 $prefix = $node->lookupNamespacePrefix( $URI );
578 Find a namespace prefix by its URI starting at the current node.
580 NOTE Only the namespace URIs are meant to be unique. The prefix is
582 only document related. Also the document might have more than a
583 single prefix defined for a namespace.
584 normalize
586 $node->normalize;
587 This function normalizes adjacent text nodes. This function is not
589 as strict as libxml2's xmlTextMerge() function, since it will not
590 free a node that is still referenced by the perl layer.
591 getNamespaces
593 @nslist = $node->getNamespaces;
594 If a node has any namespaces defined, this function will return
596 these namespaces. Note, that this will not return all namespaces
597 that are in scope, but only the ones declared explicitly for that
598 node.
599 Although getNamespaces is available for all nodes, it only makes
601 sense if used with element nodes.
602 removeChildNodes
604 $node->removeChildNodes();
605 This function is not specified for any DOM level: It removes all
607 childnodes from a node in a single step. Other than the libxml2
608 function itself (xmlFreeNodeList), this function will not
609 immediately remove the nodes from the memory. This saves one from
610 getting memory violations, if there are nodes still referred to
611 from the Perl level.
612 baseURI ()
614 $strURI = $node->baseURI();
615 Searches for the base URL of the node. The method should work on
617 both XML and HTML documents even if base mechanisms for these are
618 completely different. It returns the base as defined in RFC 2396
619 sections "5.1.1. Base URI within Document Content" and "5.1.2. Base
620 URI from the Encapsulating Entity". However it does not return the
621 document base (5.1.3), use method "URI" of "XML::LibXML::Document"
622 for this.
623 setBaseURI ($strURI)
625 $node->setBaseURI($strURI);
626 This method only does something useful for an element node in a XML
628 document. It sets the xml:base attribute on the node to $strURI,
629 which effectively sets the base URI of the node to the same value.
630 Note: For HTML documents this behaves as if the document was XML
632 which may not be desired, since it does not effectively set the
633 base URI of the node. See RFC 2396 appendix D for an example of how
634 base URI can be specified in HTML.
635 nodePath
637 $node->nodePath();
638 This function is not specified for any DOM level: It returns a
640 canonical structure based XPath for a given node.
641 line_number
643 $lineno = $node->line_number();
644 This function returns the line number where the tag was found
646 during parsing. If a node is added to the document the line number
647 is 0. Problems may occur, if a node from one document is passed to
648 another one.
649 IMPORTANT: Due to limitations in the libxml2 library line numbers
651 greater than 65535 will be returned as 65535. Please see
652 <http://bugzilla.gnome.org/show_bug.cgi?id=325533> for more
653 details.
654 Note: line_number() is special to XML::LibXML and not part of the
656 DOM specification.
657 If the line_numbers flag of the parser was not activated before
659 parsing, line_number() will always return 0.
660
662 Matt Sergeant, Christian Glahn, Petr Pajas
663
665 1.70
666
668 2001-2007, AxKit.com Ltd.
669 2002-2006, Christian Glahn.
671 2006-2009, Petr Pajas.
673perl v5.10.1 2009-10-07 XML::LibXML::Node(3)