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 $name = $node->nodeName;
10 $node->setNodeName( $newName );
11 $bool = $node->isSameNode( $other_node );
12 $bool = $node->isEqual( $other_node );
13 $content = $node->nodeValue;
14 $content = $node->textContent;
15 $type = $node->nodeType;
16 $node->unbindNode();
17 $childnode = $node->removeChild( $childnode );
18 $oldnode = $node->replaceChild( $newNode, $oldNode );
19 $node->replaceNode($newNode);
20 $childnode = $node->appendChild( $childnode );
21 $childnode = $node->addChild( $chilnode );
22 $node = $parent->addNewChild( $nsURI, $name );
23 $node->addSibling($newNode);
24 $newnode =$node->cloneNode( $deep );
25 $parentnode = $node->parentNode;
26 $nextnode = $node->nextSibling();
27 $prevnode = $node->previousSibling();
28 $boolean = $node->hasChildNodes();
29 $childnode = $node->firstChild;
30 $childnode = $node->lastChild;
31 $documentnode = $node->ownerDocument;
32 $node = $node->getOwner;
33 $node->setOwnerDocument( $doc );
34 $node->insertBefore( $newNode, $refNode );
35 $node->insertAfter( $newNode, $refNode );
36 @nodes = $node->findnodes( $xpath_expression );
37 $result = $node->find( $xpath );
38 print $node->findvalue( $xpath );
39 @childnodes = $node->childNodes;
40 $xmlstring = $node->toString($format,$docencoding);
41 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression);
42 $str = $doc->serialze($format);
43 $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);
44 $localname = $node->localname;
45 $nameprefix = $node->prefix;
46 $uri = $node->namespaceURI();
47 $boolean = $node->hasAttributes();
48 @attributelist = $node->attributes();
49 $URI = $node->lookupNamespaceURI( $prefix );
50 $prefix = $node->lookupNamespacePrefix( $URI );
51 $iter = $node->iterator;
52 $node->normalize;
53 @nslist = $node->getNamespaces;
54 $node->removeChildNodes();
55 $node->nodePath();
56 $lineno = $node->line_number();
57
59 XML::LibXML::Node defines functions that are common to all Node Types.
60 A LibXML::Node should never be created standalone, but as an instance
61 of a high level class such as LibXML::Element or LibXML::Text. The
62 class itself should provide only common functionality. In XML::LibXML
63 each node is part either of a document or a document-fragment. Because
64 of this there is no node without a parent. This may causes confusion
65 with "unbound" nodes.
66 nodeName
68 $name = $node->nodeName;
69 Returns the node's name. This function is aware of namespaces and
71 returns the full name of the current node (prefix:localname).
72 Since 1.62 this function also returns the correct DOM names for
74 node types with constant names, namely: #text, #cdata-section,
75 #comment, #document, #document-fragment.
76 setNodeName
78 $node->setNodeName( $newName );
79 In very limited situations, it is useful to change a nodes name. In
81 the DOM specification this should throw an error. This Function is
82 aware of namespaces.
83 isSameNode
85 $bool = $node->isSameNode( $other_node );
86 returns TRUE (1) if the given nodes refer to the same node struc‐
88 ture, otherwise FALSE (0) is returned.
89 isEqual
91 $bool = $node->isEqual( $other_node );
92 deprecated version of isSameNode().
94 NOTE isEqual will change behaviour to follow the DOM specification
96 nodeValue
98 $content = $node->nodeValue;
99 If the node has any content (such as stored in a text node) it can
101 get requested through this function.
102 NOTE: Element Nodes have no content per definition. To get the text
104 value of an Element use textContent() instead!
105 textContent
107 $content = $node->textContent;
108 this function returns the content of all text nodes in the descen‐
110 dants of the given node as spacified in DOM.
111 nodeType
113 $type = $node->nodeType;
114 Retrun the node's type. The possible types are described in the
116 libxml2 tree.h documentation. The return value of this function is
117 a numeric value. Therefore it differs from the result of perl ref
118 function.
119 unbindNode
121 $node->unbindNode();
122 Unbinds the Node from its siblings and Parent, but not from the
124 Document it belongs to. If the node is not inserted into the DOM
125 afterwards it will be lost after the programm terminated. From a
126 low level view, the unbound node is stripped from the context it is
127 and inserted into a (hidden) document-fragment.
128 removeChild
130 $childnode = $node->removeChild( $childnode );
131 This will unbind the Child Node from its parent $node. The function
133 returns the unbound node. If oldNode is not a child of the given
134 Node the function will fail.
135 replaceChild
137 $oldnode = $node->replaceChild( $newNode, $oldNode );
138 Replaces the $oldNode with the $newNode. The $oldNode will be
140 unbound from the Node. This function differs from the DOM L2 speci‐
141 fication, in the case, if the new node is not part of the document,
142 the node will be imported first.
143 replaceNode
145 $node->replaceNode($newNode);
146 This function is very similar to replaceChild(), but it replaces
148 the node itself rather than a childnode. This is useful if a node
149 found by any XPath function, should be replaced.
150 appendChild
152 $childnode = $node->appendChild( $childnode );
153 The function will add the $childnode to the end of $node's chil‐
155 dren. The function should fail, if the new childnode is allready a
156 child of $node. This function differs from the DOM L2 specifica‐
157 tion, in the case, if the new node is not part of the document, the
158 node will be imported first.
159 addChild
161 $childnode = $node->addChild( $chilnode );
162 As an alternative to appendChild() one can use the addChild() func‐
164 tion. This function is a bit faster, because it avoids all DOM con‐
165 formity checks. Therefore this function is quite useful if one
166 builds XML documents in memory where the order and ownership (own‐
167 erDocument) is assured.
168 addChild() uses libxml2's own xmlAddChild() function. Thus it has
170 to be used with extra care: If a text node is added to a node and
171 the node itself or its last childnode is as well a text node, the
172 node to add will be merged with the one already available. The cur‐
173 rent node will be removed from memory after this action. Because
174 perl is not aware of this action, the perl instance is still avail‐
175 able. XML::LibXML will catch the loss of a node and refuse to run
176 any function called on that node.
177 my $t1 = $doc->createTextNode( "foo" );
179 my $t2 = $doc->createTextNode( "bar" );
180 $t1->addChild( $t2 ); # is ok
181 my $val = $t2->nodeValue(); # will fail, script dies
182 Also addChild() will not check it the added node belongs to the
184 same document as the node it will be added to. This could lead to
185 inconsistent documents and in more worse cases even to memory vio‐
186 lations, if one does not keep track of this issue.
187 Although this sounds like a lot of trouble, addChild() is useful if
189 a document is built from a stream, such as happens sometimes in SAX
190 handlers or filters.
191 If you are not sure about the source of your nodes, you better stay
193 with appendChild(), because this function is more user friendly in
194 the sense of being more error tolerant.
195 addNewChild
197 $node = $parent->addNewChild( $nsURI, $name );
198 Similar to addChild(), this function uses low level libxml2 func‐
200 tionality to provide faster interface for DOM building.
201 addNewChild() uses xmlNewChild() to create a new node on a given
202 parent element.
203 addNewChild() has two parameters $nsURI and $name, where $nsURI is
205 an (optional) namespace URI. $name is the fully qualified element
206 name; addNewChild() will determine the correct prefix if nessecary.
207 The function returns the newly created node.
209 This function is very useful for DOM building, where a created node
211 can be directly associated with its parent. NOTE this function is
212 not part of the DOM specification and its use will limit your code
213 to XML::LibXML.
214 addSibling
216 $node->addSibling($newNode);
217 addSibling() allows adding an additional node to the end of a
219 nodelist, defined by the given node.
220 cloneNode
222 $newnode =$node->cloneNode( $deep );
223 cloneNode creates a copy of $node. When $deep is set to 1 (true)
225 the function will copy all childnodes as well. If $deep is 0 only
226 the current node will be copied. Note that in case of element,
227 attributes are copied iven if $deep is 0.
228 Note that the behavior of this function for $deep=0 has changed in
230 1.62 in order to be consistent with the DOM spec (in older versions
231 attributes and namespace information was not copied for elements).
232 parentNode
234 $parentnode = $node->parentNode;
235 Returns simply the Parent Node of the current node.
237 nextSibling
239 $nextnode = $node->nextSibling();
240 Returns the next sibling if any .
242 previousSibling
244 $prevnode = $node->previousSibling();
245 Analogous to getNextSibling the function returns the previous sib‐
247 ling if any.
248 hasChildNodes
250 $boolean = $node->hasChildNodes();
251 If the current node has Childnodes this function returns TRUE (1),
253 otherwise it returns FALSE (0, not undef).
254 firstChild
256 $childnode = $node->firstChild;
257 If a node has childnodes this function will return the first node
259 in the childlist.
260 lastChild
262 $childnode = $node->lastChild;
263 If the $node has childnodes this function returns the last child
265 node.
266 ownerDocument
268 $documentnode = $node->ownerDocument;
269 Through this function it is always possible to access the document
271 the current node is bound to.
272 getOwner
274 $node = $node->getOwner;
275 This function returns the node the current node is associated with.
277 In most cases this will be a document node or a document fragment
278 node.
279 setOwnerDocument
281 $node->setOwnerDocument( $doc );
282 This function binds a node to another DOM. This method unbinds the
284 node first, if it is allready bound to another document.
285 This function is the oposite calling of XML::LibXML::Document's
287 adoptNode() function. Because of this it has the same limitations
288 with Entity References as adoptNode().
289 insertBefore
291 $node->insertBefore( $newNode, $refNode );
292 The method inserts $newNode before $refNode. If $refNode is unde‐
294 fined, the newNode will be set as the new last child of the parent
295 node. This function differs from the DOM L2 specification, in the
296 case, if the new node is not part of the document, the node will be
297 imported first, automatically.
298 $refNode has to be passed to the function even if it is undefined:
300 $node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode );
302 $node->insertBefore( $newNode ); # wrong
303 Note, that the reference node has to be a direct child of the node
305 the function is called on. Also, $newChild is not allowed to be an
306 ancestor of the new parent node.
307 insertAfter
309 $node->insertAfter( $newNode, $refNode );
310 The method inserts $newNode after $refNode. If $refNode is unde‐
312 fined, the newNode will be set as the new last child of the parent
313 node.
314 Note, that $refNode has to be passed explicitly even if it is
316 undef.
317 findnodes
319 @nodes = $node->findnodes( $xpath_expression );
320 findnodes evaluates the xpath expression (XPath 1.0) on the current
322 node and returns the resulting node set as an array. In scalar con‐
323 text returns a XML::LibXML::NodeList object.
324 NOTE ON NAMESPACES AND XPATH:
326 A common mistake about XPath is to assume that node tests consist‐
328 ing of an element name with no prefix match elements in the default
329 namespace. This assumption is wrong - by XPath specification, such
330 node tests can only match elements that are in no (i.e. null)
331 namespace.
332 So, for example, one cannot match the root element of an XHTML doc‐
334 ument with $node->find('/html') since '/html' would only match if
335 the root element <html> had no namespace, but all XHTML elements
336 belong to the namespace http://www.w3.org/1999/xhtml. (Note that
337 xmlns="..." namespace declarations can also be specified in a DTD,
338 which makes the situation even worse, since the XML document looks
339 as if there was no default namespace).
340 There are several possible ways to deal with namespaces in XPath:
342 * The recommended way is to use the XML::LibXML::XPathContext
344 module to define an explicit context for XPath evaluation, in
345 which a document independent prefix-to-namespace mapping can be
346 defined. For example:
347 my $xpc = XML::LibXML::XPathContext->new;
349 $xpc->registerNs('x', 'http://www.w3.org/1999/xhtml');
350 $xpc->find('/x:html',$node);
351 * Another possibility is to use prefixes declared in the queried
353 document (if known). If the document declares a prefix for the
354 namespace in question (and the context node is in the scope of
355 the declaration), XML::LibXML allows you to use the prefix in
356 the XPath expression, e.g.:
357 $node->find('/x:html');
359 See also XML::LibXML::XPathContext->findnodes.
361 find
363 $result = $node->find( $xpath );
364 find evaluates the XPath 1.0 expression using the current node as
366 the context of the expression, and returns the result depending on
367 what type of result the XPath expression had. For example, the
368 XPath "1 * 3 + 52" results in a XML::LibXML::Number object being
369 returned. Other expressions might return a XML::LibXML::Boolean
370 object, or a XML::LibXML::Literal object (a string). Each of those
371 objects uses Perl's overload feature to "do the right thing" in
372 different contexts.
373 See also XML::LibXML::XPathContext->find.
375 findvalue
377 print $node->findvalue( $xpath );
378 findvalue is exactly equivalent to:
380 $node->find( $xpath )->to_literal;
382 That is, it returns the literal value of the results. This enables
384 you to ensure that you get a string back from your search, allowing
385 certain shortcuts. This could be used as the equivalent of XSLT's
386 <xsl:value-of select="some_xpath"/>.
387 See also XML::LibXML::XPathContext->findvalue.
389 childNodes
391 @childnodes = $node->childNodes;
392 getChildnodes implements a more intuitive interface to the
394 childnodes of the current node. It enables you to pass all children
395 directly to a map or grep. If this function is called in scalar
396 context, a XML::LibXML::NodeList object will be returned.
397 toString
399 $xmlstring = $node->toString($format,$docencoding);
400 This is the equivalent to XML::LibXML::Document::toString for a
402 single node. This means a node and all its childnodes will be
403 dumped into the result string.
404 Additionally to the $format flag of XML::LibXML::Document, this
406 version accepts the optional $docencoding flag. If this flag is set
407 this function returns the string in its original encoding (the
408 encoding of the document) rather than UTF-8.
409 toStringC14N
411 $c14nstring = $node->toStringC14N($with_comments, $xpath_expression);
412 The function is similar to toString(). Instead of simply serializ‐
414 ing the document tree, it transforms it as it is specified in the
415 XML-C14N Specification. Such transformation is known as canoniza‐
416 tion.
417 If $with_comments is 0 or not defined, the result-document will not
419 contain any comments that exist in the original document. To
420 include comments into the canonized document, $with_comments has to
421 be set to 1.
422 The parameter $xpath_expression defines the nodeset of nodes that
424 should be visible in the resulting document. This can be used to
425 filter out some nodes. One has to note, that only the nodes that
426 are part of the nodeset, will be included into the result-document.
427 Their child-nodes will not exist in the resulting document, unless
428 they are part of the nodeset defined by the xpath expression.
429 If $xpath_expression is ommitted or empty, toStringC14N() will
431 include all nodes in the given sub-tree.
432 No serializing flags will be recognized by this function!
434 serialize
436 $str = $doc->serialze($format);
437 Alternative form of toString(). This function name added to be more
439 conform with libxml2's examples.
440 serialize_c14n
442 $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);
443 Alternative form of toStringC14N().
445 localname
447 $localname = $node->localname;
448 Returns the local name of a tag. This is the part behind the colon.
450 prefix
452 $nameprefix = $node->prefix;
453 Returns the prefix of a tag. This is the part before the colon.
455 namespaceURI
457 $uri = $node->namespaceURI();
458 returns the URI of the current namespace.
460 hasAttributes
462 $boolean = $node->hasAttributes();
463 returns 1 (TRUE) if the current node has any attributes set, other‐
465 wise 0 (FALSE) is returned.
466 attributes
468 @attributelist = $node->attributes();
469 This function returns all attributes and namespace declarations
471 assigned to the given node.
472 Because XML::LibXML does not implement namespace declarations and
474 attributes the same way, it is required to test what kind of node
475 is handled while accessing the functions result.
476 If this function is called in array context the attribute nodes are
478 returned as an array. In scalar context the function will return a
479 XML::LibXML::NamedNodeMap object.
480 lookupNamespaceURI
482 $URI = $node->lookupNamespaceURI( $prefix );
483 Find a namespace URI by its prefix starting at the current node.
485 lookupNamespacePrefix
487 $prefix = $node->lookupNamespacePrefix( $URI );
488 Find a namespace prefix by its URI starting at the current node.
490 NOTE Only the namespace URIs are meant to be unique. The prefix is
492 only document related. Also the document might have more than a
493 single prefix defined for a namespace.
494 iterator
496 $iter = $node->iterator;
497 This function is deprecated since XML::LibXML 1.54. It is only a
499 dummy function that will get removed entirely in one of the next
500 versions.
501 To make use of iterator functions use XML::LibXML::Iterator Module
503 available on CPAN.
504 normalize
506 $node->normalize;
507 This function normalizes adjacent textnodes. This function is not
509 as strict as libxml2's xmlTextMerge() function, since it will not
510 free a node that is still referenced by the perl layer.
511 getNamespaces
513 @nslist = $node->getNamespaces;
514 If a node has any namespaces defined, this function will return
516 these namespaces. Note, that this will not return all namespaces
517 that are in scope, but only the ones declared explicitly for that
518 node.
519 Although getNamespaces is available for all nodes, it only makes
521 sense if used with element nodes.
522 removeChildNodes
524 $node->removeChildNodes();
525 This function is not specified for any DOM level: It removes all
527 childnodes from a node in a single step. Other than the libxml2
528 function itself (xmlFreeNodeList), this function will not immedi‐
529 ately remove the nodes from the memory. This saves one from getting
530 memory violations, if there are nodes still referred to from the
531 Perl level.
532 nodePath
534 $node->nodePath();
535 This function is not specified for any DOM level: It returns a can‐
537 nonical structure based XPath for a given node.
538 line_number
540 $lineno = $node->line_number();
541 This function returns the line number where the tag was found dur‐
543 ing parsing. If a node is added to the document the line number is
544 0. Problems may occour, if a node from one document is passed to
545 another one.
546 Note: line_number() is special to XML::LibXML and not part of the
548 DOM specification.
549 If the line_numbers flag of the parser was not activated before
551 parsing, line_number() will always return 0.
552
554 Matt Sergeant, Christian Glahn, Petr Pajas,
555
557 1.62
558
560 2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas,
561 All rights reserved.
562perl v5.8.8 2006-11-17 XML::LibXML::Node(3)