1XML::DOM::Node(3)     User Contributed Perl Documentation    XML::DOM::Node(3)
2
3
4

NAME

6       XML::DOM::Node - Super class of all nodes in XML::DOM
7

DESCRIPTION

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
13   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
19   METHODS
20       getNodeType
21           Return an integer indicating the node type. See XML::DOM constants.
22
23       getNodeName
24           Return a property or a hardcoded string, depending on the node
25           type.  Here are the corresponding functions or values:
26
27            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
44           Not In DOM Spec: AttDef, AttlistDecl, ElementDecl and XMLDecl were
45           added for completeness.
46
47       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
56       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
62       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
72           NOTE: this implementation does not return a "live" NodeList for
73           getElementsByTagName. See CAVEATS.
74
75           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
79            @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
83       getFirstChild
84           The first child of this node. If there is no such node, this
85           returns undef.
86
87       getLastChild
88           The last child of this node. If there is no such node, this returns
89           undef.
90
91       getPreviousSibling
92           The node immediately preceding this node. If there is no such node,
93           this returns undef.
94
95       getNextSibling
96           The node immediately following this node. If there is no such node,
97           this returns undef.
98
99       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
106       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
111       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
116           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
120           Return Value: The node being inserted.
121
122           DOMExceptions:
123
124           •   HIERARCHY_REQUEST_ERR
125
126               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
130           •   WRONG_DOCUMENT_ERR
131
132               Raised if newChild was created from a different document than
133               the one that created this node.
134
135           •   NO_MODIFICATION_ALLOWED_ERR
136
137               Raised if this node is readonly.
138
139           •   NOT_FOUND_ERR
140
141               Raised if refChild is not a child of this node.
142
143       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
148           Return Value: The node replaced.
149
150           DOMExceptions:
151
152           •   HIERARCHY_REQUEST_ERR
153
154               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
158           •   WRONG_DOCUMENT_ERR
159
160               Raised if newChild was created from a different document than
161               the one that created this node.
162
163           •   NO_MODIFICATION_ALLOWED_ERR
164
165               Raised if this node is readonly.
166
167           •   NOT_FOUND_ERR
168
169               Raised if oldChild is not a child of this node.
170
171       removeChild (oldChild)
172           Removes the child node indicated by oldChild from the list of
173           children, and returns it.
174
175           Return Value: The node removed.
176
177           DOMExceptions:
178
179           •   NO_MODIFICATION_ALLOWED_ERR
180
181               Raised if this node is readonly.
182
183           •   NOT_FOUND_ERR
184
185               Raised if oldChild is not a child of this node.
186
187       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
193           Return Value: The node added.
194
195           DOMExceptions:
196
197           •   HIERARCHY_REQUEST_ERR
198
199               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
203           •   WRONG_DOCUMENT_ERR
204
205               Raised if newChild was created from a different document than
206               the one that created this node.
207
208           •   NO_MODIFICATION_ALLOWED_ERR
209
210               Raised if this node is readonly.
211
212       hasChildNodes
213           This is a convenience method to allow easy determination of whether
214           a node has any children.
215
216           Return Value: 1 if the node has any children, 0 otherwise.
217
218       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
223           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
230           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
235           Return Value: The duplicate node.
236
237       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
247           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
251       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
256           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
263           Return Value: A list of matching Element nodes.
264
265           NOTE: this implementation does not return a "live" NodeList for
266           getElementsByTagName. See CAVEATS.
267
268           When this method is called in a list context, it returns a regular
269           perl list containing the result nodes. E.g.
270
271            @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
275   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
281       toString
282           Returns the entire subtree as a string.
283
284       printToFile (filename)
285           Prints the entire subtree to the file with the specified filename.
286
287           Croaks: if the file could not be opened for writing.
288
289       printToFileHandle (handle)
290           Prints the entire subtree to the file handle.  E.g. to print to
291           STDOUT:
292
293            $node->printToFileHandle (\*STDOUT);
294
295       print (obj)
296           Prints the entire subtree using the object's print method. E.g to
297           print to a FileHandle object:
298
299            $f = new FileHandle ("file.out", "w");
300            $node->print ($f);
301
302       getChildIndex (child)
303           Returns the index of the child node in the list returned by
304           getChildNodes.
305
306           Return Value: the index or -1 if the node is not found.
307
308       getChildAtIndex (index)
309           Returns the child node at the specified index or undef.
310
311       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
315           Return Value: the last child if it was a Text node or else the new
316           Text node.
317
318       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
323       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
330           This method does nothing when called on a Document node.
331
332       isAncestor (parent)
333           Returns 1 if parent is an ancestor of this node or if it is this
334           node itself.
335
336       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 "&#x1fc2"), 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
345       to_sax ( %HANDLERS )
346           E.g.
347
348            $node->to_sax (DocumentHandler => $my_handler,
349                           Handler => $handler2 );
350
351           %HANDLERS may contain the following handlers:
352
353           •   DocumentHandler
354
355           •   DTDHandler
356
357           •   EntityResolver
358
359           •   Handler
360
361               Default handler when one of the above is not specified
362
363           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
372           See PerlSAX for the description of the SAX interface.
373
374       check ( [$checker] )
375           See descriptions for check() in XML::DOM::Document and
376           XML::DOM::Element.
377
378       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
382            $query = new XML::XQL::Query ( @XQL_OPTIONS );
383            return $query->solve ($node);
384
385           If the first parameter in @XQL_OPTIONS is the XQL expression, you
386           can leave off the 'Expr' keyword, so:
387
388            $node->xql ("doc//elem1[@attr]", @other_options);
389
390           is identical to:
391
392            $node->xql (Expr => "doc//elem1[@attr]", @other_options);
393
394           See XML::XQL::Query for other available XQL_OPTIONS.  See XML::XQL
395           and XML::XQL::Tutorial for more info.
396
397       isHidden ()
398           Whether the node is hidden.  See Hidden Nodes for details.
399
400
401
402perl v5.34.0                      2021-07-27                 XML::DOM::Node(3)
Impressum