1XML::DOM::Node(3) User Contributed Perl Documentation XML::DOM::Node(3)
2
6 XML::DOM::Node - Super class of all nodes in XML::DOM
7
9 XML::DOM::Node is the super class of all nodes in an XML::DOM document.
10 This means that all nodes that subclass XML::DOM::Node also inherit all
11 the methods that XML::DOM::Node implements.
12 GLOBAL VARIABLES
14 @NodeNames
15 The variable @XML::DOM::Node::NodeNames maps the node type
16 constants to strings. It is used by
17 XML::DOM::Node::getNodeTypeName.
18 METHODS
20 getNodeType
21 Return an integer indicating the node type. See XML::DOM constants.
22 getNodeName
24 Return a property or a hardcoded string, depending on the node
25 type. Here are the corresponding functions or values:
26 Attr getName
28 AttDef getName
29 AttlistDecl getName
30 CDATASection "#cdata-section"
31 Comment "#comment"
32 Document "#document"
33 DocumentType getNodeName
34 DocumentFragment "#document-fragment"
35 Element getTagName
36 ElementDecl getName
37 EntityReference getEntityName
38 Entity getNotationName
39 Notation getName
40 ProcessingInstruction getTarget
41 Text "#text"
42 XMLDecl "#xml-declaration"
43 Not In DOM Spec: AttDef, AttlistDecl, ElementDecl and XMLDecl were
45 added for completeness.
46 getNodeValue and setNodeValue (value)
48 Returns a string or undef, depending on the node type. This method
49 is provided for completeness. In other languages it saves the
50 programmer an upcast. The value is either available thru some
51 other method defined in the subclass, or else undef is returned.
52 Here are the corresponding methods: Attr::getValue, Text::getData,
53 CDATASection::getData, Comment::getData,
54 ProcessingInstruction::getData.
55 getParentNode and setParentNode (parentNode)
57 The parent of this node. All nodes, except Document,
58 DocumentFragment, and Attr may have a parent. However, if a node
59 has just been created and not yet added to the tree, or if it has
60 been removed from the tree, this is undef.
61 getChildNodes
63 A NodeList that contains all children of this node. If there are no
64 children, this is a NodeList containing no nodes. The content of
65 the returned NodeList is "live" in the sense that, for instance,
66 changes to the children of the node object that it was created from
67 are immediately reflected in the nodes returned by the NodeList
68 accessors; it is not a static snapshot of the content of the node.
69 This is true for every NodeList, including the ones returned by the
70 getElementsByTagName method.
71 NOTE: this implementation does not return a "live" NodeList for
73 getElementsByTagName. See CAVEATS.
74 When this method is called in a list context, it returns a regular
76 perl list containing the child nodes. Note that this list is not
77 "live". E.g.
78 @list = $node->getChildNodes; # returns a perl list
80 $nodelist = $node->getChildNodes; # returns a NodeList (object reference)
81 for my $kid ($node->getChildNodes) # iterate over the children of $node
82 getFirstChild
84 The first child of this node. If there is no such node, this
85 returns undef.
86 getLastChild
88 The last child of this node. If there is no such node, this returns
89 undef.
90 getPreviousSibling
92 The node immediately preceding this node. If there is no such node,
93 this returns undef.
94 getNextSibling
96 The node immediately following this node. If there is no such node,
97 this returns undef.
98 getAttributes
100 A NamedNodeMap containing the attributes (Attr nodes) of this node
101 (if it is an Element) or undef otherwise. Note that
102 adding/removing attributes from the returned object, also
103 adds/removes attributes from the Element node that the NamedNodeMap
104 came from.
105 getOwnerDocument
107 The Document object associated with this node. This is also the
108 Document object used to create new nodes. When this node is a
109 Document this is undef.
110 insertBefore (newChild, refChild)
112 Inserts the node newChild before the existing child node refChild.
113 If refChild is undef, insert newChild at the end of the list of
114 children.
115 If newChild is a DocumentFragment object, all of its children are
117 inserted, in the same order, before refChild. If the newChild is
118 already in the tree, it is first removed.
119 Return Value: The node being inserted.
121 DOMExceptions:
123 · HIERARCHY_REQUEST_ERR
125 Raised if this node is of a type that does not allow children
127 of the type of the newChild node, or if the node to insert is
128 one of this node's ancestors.
129 · WRONG_DOCUMENT_ERR
131 Raised if newChild was created from a different document than
133 the one that created this node.
134 · NO_MODIFICATION_ALLOWED_ERR
136 Raised if this node is readonly.
138 · NOT_FOUND_ERR
140 Raised if refChild is not a child of this node.
142 replaceChild (newChild, oldChild)
144 Replaces the child node oldChild with newChild in the list of
145 children, and returns the oldChild node. If the newChild is already
146 in the tree, it is first removed.
147 Return Value: The node replaced.
149 DOMExceptions:
151 · HIERARCHY_REQUEST_ERR
153 Raised if this node is of a type that does not allow children
155 of the type of the newChild node, or it the node to put in is
156 one of this node's ancestors.
157 · WRONG_DOCUMENT_ERR
159 Raised if newChild was created from a different document than
161 the one that created this node.
162 · NO_MODIFICATION_ALLOWED_ERR
164 Raised if this node is readonly.
166 · NOT_FOUND_ERR
168 Raised if oldChild is not a child of this node.
170 removeChild (oldChild)
172 Removes the child node indicated by oldChild from the list of
173 children, and returns it.
174 Return Value: The node removed.
176 DOMExceptions:
178 · NO_MODIFICATION_ALLOWED_ERR
180 Raised if this node is readonly.
182 · NOT_FOUND_ERR
184 Raised if oldChild is not a child of this node.
186 appendChild (newChild)
188 Adds the node newChild to the end of the list of children of this
189 node. If the newChild is already in the tree, it is first removed.
190 If it is a DocumentFragment object, the entire contents of the
191 document fragment are moved into the child list of this node
192 Return Value: The node added.
194 DOMExceptions:
196 · HIERARCHY_REQUEST_ERR
198 Raised if this node is of a type that does not allow children
200 of the type of the newChild node, or if the node to append is
201 one of this node's ancestors.
202 · WRONG_DOCUMENT_ERR
204 Raised if newChild was created from a different document than
206 the one that created this node.
207 · NO_MODIFICATION_ALLOWED_ERR
209 Raised if this node is readonly.
211 hasChildNodes
213 This is a convenience method to allow easy determination of whether
214 a node has any children.
215 Return Value: 1 if the node has any children, 0 otherwise.
217 cloneNode (deep)
219 Returns a duplicate of this node, i.e., serves as a generic copy
220 constructor for nodes. The duplicate node has no parent (parentNode
221 returns undef.).
222 Cloning an Element copies all attributes and their values,
224 including those generated by the XML processor to represent
225 defaulted attributes, but this method does not copy any text it
226 contains unless it is a deep clone, since the text is contained in
227 a child Text node. Cloning any other type of node simply returns a
228 copy of this node.
229 Parameters:
231 deep If true, recursively clone the subtree under the specified
232 node. If false, clone only the node itself (and its attributes, if
233 it is an Element).
234 Return Value: The duplicate node.
236 normalize
238 Puts all Text nodes in the full depth of the sub-tree underneath
239 this Element into a "normal" form where only markup (e.g., tags,
240 comments, processing instructions, CDATA sections, and entity
241 references) separates Text nodes, i.e., there are no adjacent Text
242 nodes. This can be used to ensure that the DOM view of a document
243 is the same as if it were saved and re-loaded, and is useful when
244 operations (such as XPointer lookups) that depend on a particular
245 document tree structure are to be used.
246 Not In DOM Spec: In the DOM Spec this method is defined in the
248 Element and Document class interfaces only, but it doesn't hurt to
249 have it here...
250 getElementsByTagName (name [, recurse])
252 Returns a NodeList of all descendant elements with a given tag
253 name, in the order in which they would be encountered in a preorder
254 traversal of the Element tree.
255 Parameters:
257 name The name of the tag to match on. The special value "*"
258 matches all tags.
259 recurse Whether it should return only direct child nodes (0) or
260 any descendant that matches the tag name (1). This argument is
261 optional and defaults to 1. It is not part of the DOM spec.
262 Return Value: A list of matching Element nodes.
264 NOTE: this implementation does not return a "live" NodeList for
266 getElementsByTagName. See CAVEATS.
267 When this method is called in a list context, it returns a regular
269 perl list containing the result nodes. E.g.
270 @list = $node->getElementsByTagName("tag"); # returns a perl list
272 $nodelist = $node->getElementsByTagName("tag"); # returns a NodeList (object ref.)
273 for my $elem ($node->getElementsByTagName("tag")) # iterate over the result nodes
274 Additional methods not in the DOM Spec
276 getNodeTypeName
277 Return the string describing the node type. E.g. returns
278 "ELEMENT_NODE" if getNodeType returns ELEMENT_NODE. It uses
279 @XML::DOM::Node::NodeNames.
280 toString
282 Returns the entire subtree as a string.
283 printToFile (filename)
285 Prints the entire subtree to the file with the specified filename.
286 Croaks: if the file could not be opened for writing.
288 printToFileHandle (handle)
290 Prints the entire subtree to the file handle. E.g. to print to
291 STDOUT:
292 $node->printToFileHandle (\*STDOUT);
294 print (obj)
296 Prints the entire subtree using the object's print method. E.g to
297 print to a FileHandle object:
298 $f = new FileHandle ("file.out", "w");
300 $node->print ($f);
301 getChildIndex (child)
303 Returns the index of the child node in the list returned by
304 getChildNodes.
305 Return Value: the index or -1 if the node is not found.
307 getChildAtIndex (index)
309 Returns the child node at the specified index or undef.
310 addText (text)
312 Appends the specified string to the last child if it is a Text
313 node, or else appends a new Text node (with the specified text.)
314 Return Value: the last child if it was a Text node or else the new
316 Text node.
317 dispose
319 Removes all circular references in this node and its descendants so
320 the objects can be claimed for garbage collection. The objects
321 should not be used afterwards.
322 setOwnerDocument (doc)
324 Sets the ownerDocument property of this node and all its children
325 (and attributes etc.) to the specified document. This allows the
326 user to cut and paste document subtrees between different
327 XML::DOM::Documents. The node should be removed from the original
328 document first, before calling setOwnerDocument.
329 This method does nothing when called on a Document node.
331 isAncestor (parent)
333 Returns 1 if parent is an ancestor of this node or if it is this
334 node itself.
335 expandEntityRefs (str)
337 Expands all the entity references in the string and returns the
338 result. The entity references can be character references (e.g.
339 "{" or "ῂ"), default entity references (""",
340 ">", "<", "'" and "&") or entity references defined
341 in Entity objects as part of the DocumentType of the owning
342 Document. Character references are expanded into UTF-8. Parameter
343 entity references (e.g. %ent;) are not expanded.
344 to_sax ( %HANDLERS )
346 E.g.
347 $node->to_sax (DocumentHandler => $my_handler,
349 Handler => $handler2 );
350 %HANDLERS may contain the following handlers:
352 · DocumentHandler
354 · DTDHandler
356 · EntityResolver
358 · Handler
360 Default handler when one of the above is not specified
362 Each XML::DOM::Node generates the appropriate SAX callbacks (for
364 the appropriate SAX handler.) Different SAX handlers can be plugged
365 in to accomplish different things, e.g. XML::Checker would check
366 the node (currently only Document and Element nodes are supported),
367 XML::Handler::BuildDOM would create a new DOM subtree (thereby, in
368 essence, copying the Node) and in the near future, XML::Writer
369 could print the node. All Perl SAX related work is still in flux,
370 so this interface may change a little.
371 See PerlSAX for the description of the SAX interface.
373 check ( [$checker] )
375 See descriptions for check() in XML::DOM::Document and
376 XML::DOM::Element.
377 xql ( @XQL_OPTIONS )
379 To use the xql method, you must first use XML::XQL and
380 XML::XQL::DOM. This method is basically a shortcut for:
381 $query = new XML::XQL::Query ( @XQL_OPTIONS );
383 return $query->solve ($node);
384 If the first parameter in @XQL_OPTIONS is the XQL expression, you
386 can leave off the 'Expr' keyword, so:
387 $node->xql ("doc//elem1[@attr]", @other_options);
389 is identical to:
391 $node->xql (Expr => "doc//elem1[@attr]", @other_options);
393 See XML::XQL::Query for other available XQL_OPTIONS. See XML::XQL
395 and XML::XQL::Tutorial for more info.
396 isHidden ()
398 Whether the node is hidden. See Hidden Nodes for details.
399perl v5.32.0 2020-07-28 XML::DOM::Node(3)