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
16 The variable @XML::DOM::Node::NodeNames maps the node type con‐
17 stants to strings. It is used by XML::DOM::Node::getNodeTypeName.
18 METHODS
20 getNodeType
22 Return an integer indicating the node type. See XML::DOM constants.
23 getNodeName
25 Return a property or a hardcoded string, depending on the node
26 type. Here are the corresponding functions or values:
27 Attr getName
29 AttDef getName
30 AttlistDecl getName
31 CDATASection "#cdata-section"
32 Comment "#comment"
33 Document "#document"
34 DocumentType getNodeName
35 DocumentFragment "#document-fragment"
36 Element getTagName
37 ElementDecl getName
38 EntityReference getEntityName
39 Entity getNotationName
40 Notation getName
41 ProcessingInstruction getTarget
42 Text "#text"
43 XMLDecl "#xml-declaration"
44 Not In DOM Spec: AttDef, AttlistDecl, ElementDecl and XMLDecl were
46 added for completeness.
47 getNodeValue and setNodeValue (value)
49 Returns a string or undef, depending on the node type. This method
50 is provided for completeness. In other languages it saves the pro‐
51 grammer an upcast. The value is either available thru some other
52 method defined in the subclass, or else undef is returned. Here are
53 the corresponding methods: Attr::getValue, Text::getData, CDATASec‐
54 tion::getData, Comment::getData, ProcessingInstruction::getData.
55 getParentNode and setParentNode (parentNode)
57 The parent of this node. All nodes, except Document, DocumentFrag‐
58 ment, and Attr may have a parent. However, if a node has just been
59 created and not yet added to the tree, or if it has been removed
60 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 adding/remov‐
102 ing attributes from the returned object, also adds/removes
103 attributes from the Element node that the NamedNodeMap came from.
104 getOwnerDocument
106 The Document object associated with this node. This is also the
107 Document object used to create new nodes. When this node is a Docu‐
108 ment this is undef.
109 insertBefore (newChild, refChild)
111 Inserts the node newChild before the existing child node refChild.
112 If refChild is undef, insert newChild at the end of the list of
113 children.
114 If newChild is a DocumentFragment object, all of its children are
116 inserted, in the same order, before refChild. If the newChild is
117 already in the tree, it is first removed.
118 Return Value: The node being inserted.
120 DOMExceptions:
122 * HIERARCHY_REQUEST_ERR
124 Raised if this node is of a type that does not allow children
125 of the type of the newChild node, or if the node to insert is
126 one of this node's ancestors.
127 * WRONG_DOCUMENT_ERR
129 Raised if newChild was created from a different document than
130 the one that created this node.
131 * NO_MODIFICATION_ALLOWED_ERR
133 Raised if this node is readonly.
134 * NOT_FOUND_ERR
136 Raised if refChild is not a child of this node.
137 replaceChild (newChild, oldChild)
139 Replaces the child node oldChild with newChild in the list of chil‐
140 dren, and returns the oldChild node. If the newChild is already in
141 the tree, it is first removed.
142 Return Value: The node replaced.
144 DOMExceptions:
146 * HIERARCHY_REQUEST_ERR
148 Raised if this node is of a type that does not allow children
149 of the type of the newChild node, or it the node to put in is
150 one of this node's ancestors.
151 * WRONG_DOCUMENT_ERR
153 Raised if newChild was created from a different document than
154 the one that created this node.
155 * NO_MODIFICATION_ALLOWED_ERR
157 Raised if this node is readonly.
158 * NOT_FOUND_ERR
160 Raised if oldChild is not a child of this node.
161 removeChild (oldChild)
163 Removes the child node indicated by oldChild from the list of chil‐
164 dren, and returns it.
165 Return Value: The node removed.
167 DOMExceptions:
169 * NO_MODIFICATION_ALLOWED_ERR
171 Raised if this node is readonly.
172 * NOT_FOUND_ERR
174 Raised if oldChild is not a child of this node.
175 appendChild (newChild)
177 Adds the node newChild to the end of the list of children of this
178 node. If the newChild is already in the tree, it is first removed.
179 If it is a DocumentFragment object, the entire contents of the doc‐
180 ument fragment are moved into the child list of this node
181 Return Value: The node added.
183 DOMExceptions:
185 * HIERARCHY_REQUEST_ERR
187 Raised if this node is of a type that does not allow children
188 of the type of the newChild node, or if the node to append is
189 one of this node's ancestors.
190 * WRONG_DOCUMENT_ERR
192 Raised if newChild was created from a different document than
193 the one that created this node.
194 * NO_MODIFICATION_ALLOWED_ERR
196 Raised if this node is readonly.
197 hasChildNodes
199 This is a convenience method to allow easy determination of whether
200 a node has any children.
201 Return Value: 1 if the node has any children, 0 otherwise.
203 cloneNode (deep)
205 Returns a duplicate of this node, i.e., serves as a generic copy
206 constructor for nodes. The duplicate node has no parent (parentNode
207 returns undef.).
208 Cloning an Element copies all attributes and their values, includ‐
210 ing those generated by the XML processor to represent defaulted
211 attributes, but this method does not copy any text it contains
212 unless it is a deep clone, since the text is contained in a child
213 Text node. Cloning any other type of node simply returns a copy of
214 this node.
215 Parameters:
217 deep If true, recursively clone the subtree under the specified
218 node. If false, clone only the node itself (and its attributes, if
219 it is an Element).
220 Return Value: The duplicate node.
222 normalize
224 Puts all Text nodes in the full depth of the sub-tree underneath
225 this Element into a "normal" form where only markup (e.g., tags,
226 comments, processing instructions, CDATA sections, and entity ref‐
227 erences) separates Text nodes, i.e., there are no adjacent Text
228 nodes. This can be used to ensure that the DOM view of a document
229 is the same as if it were saved and re-loaded, and is useful when
230 operations (such as XPointer lookups) that depend on a particular
231 document tree structure are to be used.
232 Not In DOM Spec: In the DOM Spec this method is defined in the Ele‐
234 ment and Document class interfaces only, but it doesn't hurt to
235 have it here...
236 getElementsByTagName (name [, recurse])
238 Returns a NodeList of all descendant elements with a given tag
239 name, in the order in which they would be encountered in a preorder
240 traversal of the Element tree.
241 Parameters:
243 name The name of the tag to match on. The special value "*"
244 matches all tags.
245 recurse Whether it should return only direct child nodes (0) or
246 any descendant that matches the tag name (1). This argument is
247 optional and defaults to 1. It is not part of the DOM spec.
248 Return Value: A list of matching Element nodes.
250 NOTE: this implementation does not return a "live" NodeList for
252 getElementsByTagName. See CAVEATS.
253 When this method is called in a list context, it returns a regular
255 perl list containing the result nodes. E.g.
256 @list = $node->getElementsByTagName("tag"); # returns a perl list
258 $nodelist = $node->getElementsByTagName("tag"); # returns a NodeList (object ref.)
259 for my $elem ($node->getElementsByTagName("tag")) # iterate over the result nodes
260 Additional methods not in the DOM Spec
262 getNodeTypeName
264 Return the string describing the node type. E.g. returns "ELE‐
265 MENT_NODE" if getNodeType returns ELEMENT_NODE. It uses
266 @XML::DOM::Node::NodeNames.
267 toString
269 Returns the entire subtree as a string.
270 printToFile (filename)
272 Prints the entire subtree to the file with the specified filename.
273 Croaks: if the file could not be opened for writing.
275 printToFileHandle (handle)
277 Prints the entire subtree to the file handle. E.g. to print to
278 STDOUT:
279 $node->printToFileHandle (\*STDOUT);
281 print (obj)
283 Prints the entire subtree using the object's print method. E.g to
284 print to a FileHandle object:
285 $f = new FileHandle ("file.out", "w");
287 $node->print ($f);
288 getChildIndex (child)
290 Returns the index of the child node in the list returned by
291 getChildNodes.
292 Return Value: the index or -1 if the node is not found.
294 getChildAtIndex (index)
296 Returns the child node at the specifed index or undef.
297 addText (text)
299 Appends the specified string to the last child if it is a Text
300 node, or else appends a new Text node (with the specified text.)
301 Return Value: the last child if it was a Text node or else the new
303 Text node.
304 dispose
306 Removes all circular references in this node and its descendants so
307 the objects can be claimed for garbage collection. The objects
308 should not be used afterwards.
309 setOwnerDocument (doc)
311 Sets the ownerDocument property of this node and all its children
312 (and attributes etc.) to the specified document. This allows the
313 user to cut and paste document subtrees between different
314 XML::DOM::Documents. The node should be removed from the original
315 document first, before calling setOwnerDocument.
316 This method does nothing when called on a Document node.
318 isAncestor (parent)
320 Returns 1 if parent is an ancestor of this node or if it is this
321 node itself.
322 expandEntityRefs (str)
324 Expands all the entity references in the string and returns the
325 result. The entity references can be character references (e.g.
326 "{" or "ῂ"), default entity references (""",
327 ">", "<", "'" and "&") or entity references defined
328 in Entity objects as part of the DocumentType of the owning Docu‐
329 ment. Character references are expanded into UTF-8. Parameter
330 entity references (e.g. %ent;) are not expanded.
331 to_sax ( %HANDLERS )
333 E.g.
334 $node->to_sax (DocumentHandler => $my_handler,
336 Handler => $handler2 );
337 %HANDLERS may contain the following handlers:
339 * DocumentHandler
341 * DTDHandler
342 * EntityResolver
343 * Handler
344 Default handler when one of the above is not specified
345 Each XML::DOM::Node generates the appropriate SAX callbacks (for
347 the appropriate SAX handler.) Different SAX handlers can be plugged
348 in to accomplish different things, e.g. XML::Checker would check
349 the node (currently only Document and Element nodes are supported),
350 XML::Handler::BuildDOM would create a new DOM subtree (thereby, in
351 essence, copying the Node) and in the near future, XML::Writer
352 could print the node. All Perl SAX related work is still in flux,
353 so this interface may change a little.
354 See PerlSAX for the description of the SAX interface.
356 check ( [$checker] )
358 See descriptions for check() in XML::DOM::Document and
359 XML::DOM::Element.
360 xql ( @XQL_OPTIONS )
362 To use the xql method, you must first use XML::XQL and
363 XML::XQL::DOM. This method is basically a shortcut for:
364 $query = new XML::XQL::Query ( @XQL_OPTIONS );
366 return $query->solve ($node);
367 If the first parameter in @XQL_OPTIONS is the XQL expression, you
369 can leave off the 'Expr' keyword, so:
370 $node->xql ("doc//elem1[@attr]", @other_options);
372 is identical to:
374 $node->xql (Expr => "doc//elem1[@attr]", @other_options);
376 See XML::XQL::Query for other available XQL_OPTIONS. See XML::XQL
378 and XML::XQL::Tutorial for more info.
379 isHidden ()
381 Whether the node is hidden. See Hidden Nodes for details.
382perl v5.8.8 2002-02-08 XML::DOM::Node(3)