1 =head1 NAME

     2 

     3 XML::DOM::Node - Super class of all nodes in XML::DOM

     4 

     5 =head1 DESCRIPTION

     6 

     7 XML::DOM::Node is the super class of all nodes in an XML::DOM document.

     8 This means that all nodes that subclass XML::DOM::Node also inherit all

     9 the methods that XML::DOM::Node implements.

    10 

    11 =head2 GLOBAL VARIABLES

    12 

    13 =over 4

    14 

    15 =item @NodeNames

    16 

    17 The variable @XML::DOM::Node::NodeNames maps the node type constants to strings.

    18 It is used by XML::DOM::Node::getNodeTypeName.

    19 

    20 =back

    21 

    22 =head2 METHODS

    23 

    24 =over 4

    25 

    26 =item getNodeType

    27 

    28 Return an integer indicating the node type. See XML::DOM constants.

    29 

    30 =item getNodeName

    31 

    32 Return a property or a hardcoded string, depending on the node type.

    33 Here are the corresponding functions or values:

    34 

    35  Attr			getName

    36  AttDef			getName

    37  AttlistDecl		getName

    38  CDATASection		"#cdata-section"

    39  Comment		"#comment"

    40  Document		"#document"

    41  DocumentType		getNodeName

    42  DocumentFragment	"#document-fragment"

    43  Element		getTagName

    44  ElementDecl		getName

    45  EntityReference	getEntityName

    46  Entity			getNotationName

    47  Notation		getName

    48  ProcessingInstruction	getTarget

    49  Text			"#text"

    50  XMLDecl		"#xml-declaration"

    51 

    52 B<Not In DOM Spec>: AttDef, AttlistDecl, ElementDecl and XMLDecl were added for

    53 completeness.

    54 

    55 =item getNodeValue and setNodeValue (value)

    56 

    57 Returns a string or undef, depending on the node type. This method is provided 

    58 for completeness. In other languages it saves the programmer an upcast.

    59 The value is either available thru some other method defined in the subclass, or

    60 else undef is returned. Here are the corresponding methods: 

    61 Attr::getValue, Text::getData, CDATASection::getData, Comment::getData, 

    62 ProcessingInstruction::getData.

    63 

    64 =item getParentNode and setParentNode (parentNode)

    65 

    66 The parent of this node. All nodes, except Document,

    67 DocumentFragment, and Attr may have a parent. However, if a

    68 node has just been created and not yet added to the tree, or

    69 if it has been removed from the tree, this is undef.

    70 

    71 =item getChildNodes

    72 

    73 A NodeList that contains all children of this node. If there

    74 are no children, this is a NodeList containing no nodes. The

    75 content of the returned NodeList is "live" in the sense that,

    76 for instance, changes to the children of the node object that

    77 it was created from are immediately reflected in the nodes

    78 returned by the NodeList accessors; it is not a static

    79 snapshot of the content of the node. This is true for every

    80 NodeList, including the ones returned by the

    81 getElementsByTagName method.

    82 

    83 NOTE: this implementation does not return a "live" NodeList for

    84 getElementsByTagName. See L<CAVEATS>.

    85 

    86 When this method is called in a list context, it returns a regular perl list

    87 containing the child nodes. Note that this list is not "live". E.g.

    88 

    89  @list = $node->getChildNodes;	      # returns a perl list

    90  $nodelist = $node->getChildNodes;    # returns a NodeList (object reference)

    91  for my $kid ($node->getChildNodes)   # iterate over the children of $node

    92 

    93 =item getFirstChild

    94 

    95 The first child of this node. If there is no such node, this returns undef.

    96 

    97 =item getLastChild

    98 

    99 The last child of this node. If there is no such node, this returns undef.

   100 

   101 =item getPreviousSibling

   102 

   103 The node immediately preceding this node. If there is no such 

   104 node, this returns undef.

   105 

   106 =item getNextSibling

   107 

   108 The node immediately following this node. If there is no such node, this returns 

   109 undef.

   110 

   111 =item getAttributes

   112 

   113 A NamedNodeMap containing the attributes (Attr nodes) of this node 

   114 (if it is an Element) or undef otherwise.

   115 Note that adding/removing attributes from the returned object, also adds/removes

   116 attributes from the Element node that the NamedNodeMap came from.

   117 

   118 =item getOwnerDocument

   119 

   120 The Document object associated with this node. This is also

   121 the Document object used to create new nodes. When this node

   122 is a Document this is undef.

   123 

   124 =item insertBefore (newChild, refChild)

   125 

   126 Inserts the node newChild before the existing child node

   127 refChild. If refChild is undef, insert newChild at the end of

   128 the list of children.

   129 

   130 If newChild is a DocumentFragment object, all of its children

   131 are inserted, in the same order, before refChild. If the

   132 newChild is already in the tree, it is first removed.

   133 

   134 Return Value: The node being inserted.

   135 

   136 DOMExceptions:

   137 

   138 =over 4

   139 

   140 =item * HIERARCHY_REQUEST_ERR

   141 

   142 Raised if this node is of a type that does not allow children of the type of

   143 the newChild node, or if the node to insert is one of this node's ancestors.

   144 

   145 =item * WRONG_DOCUMENT_ERR

   146 

   147 Raised if newChild was created from a different document than the one that 

   148 created this node.

   149 

   150 =item * NO_MODIFICATION_ALLOWED_ERR

   151 

   152 Raised if this node is readonly.

   153 

   154 =item * NOT_FOUND_ERR

   155 

   156 Raised if refChild is not a child of this node.

   157 

   158 =back

   159 

   160 =item replaceChild (newChild, oldChild)

   161 

   162 Replaces the child node oldChild with newChild in the list of

   163 children, and returns the oldChild node. If the newChild is

   164 already in the tree, it is first removed.

   165 

   166 Return Value: The node replaced.

   167 

   168 DOMExceptions:

   169 

   170 =over 4

   171 

   172 =item * HIERARCHY_REQUEST_ERR

   173 

   174 Raised if this node is of a type that does not allow children of the type of

   175 the newChild node, or it the node to put in is one of this node's ancestors.

   176 

   177 =item * WRONG_DOCUMENT_ERR

   178 

   179 Raised if newChild was created from a different document than the one that 

   180 created this node.

   181 

   182 =item * NO_MODIFICATION_ALLOWED_ERR

   183 

   184 Raised if this node is readonly.

   185 

   186 =item * NOT_FOUND_ERR

   187 

   188 Raised if oldChild is not a child of this node.

   189 

   190 =back

   191 

   192 =item removeChild (oldChild)

   193 

   194 Removes the child node indicated by oldChild from the list of

   195 children, and returns it.

   196 

   197 Return Value: The node removed.

   198 

   199 DOMExceptions:

   200 

   201 =over 4

   202 

   203 =item * NO_MODIFICATION_ALLOWED_ERR

   204 

   205 Raised if this node is readonly.

   206 

   207 =item * NOT_FOUND_ERR

   208 

   209 Raised if oldChild is not a child of this node.

   210 

   211 =back

   212 

   213 =item appendChild (newChild)

   214 

   215 Adds the node newChild to the end of the list of children of

   216 this node. If the newChild is already in the tree, it is

   217 first removed. If it is a DocumentFragment object, the entire contents of 

   218 the document fragment are moved into the child list of this node

   219 

   220 Return Value: The node added.

   221 

   222 DOMExceptions:

   223 

   224 =over 4

   225 

   226 =item * HIERARCHY_REQUEST_ERR

   227 

   228 Raised if this node is of a type that does not allow children of the type of

   229 the newChild node, or if the node to append is one of this node's ancestors.

   230 

   231 =item * WRONG_DOCUMENT_ERR

   232 

   233 Raised if newChild was created from a different document than the one that 

   234 created this node.

   235 

   236 =item * NO_MODIFICATION_ALLOWED_ERR

   237 

   238 Raised if this node is readonly.

   239 

   240 =back

   241 

   242 =item hasChildNodes

   243 

   244 This is a convenience method to allow easy determination of

   245 whether a node has any children.

   246 

   247 Return Value: 1 if the node has any children, 0 otherwise.

   248 

   249 =item cloneNode (deep)

   250 

   251 Returns a duplicate of this node, i.e., serves as a generic

   252 copy constructor for nodes. The duplicate node has no parent

   253 (parentNode returns undef.).

   254 

   255 Cloning an Element copies all attributes and their values,

   256 including those generated by the XML processor to represent

   257 defaulted attributes, but this method does not copy any text

   258 it contains unless it is a deep clone, since the text is

   259 contained in a child Text node. Cloning any other type of

   260 node simply returns a copy of this node.

   261 

   262 Parameters: 

   263  I<deep>   If true, recursively clone the subtree under the specified node.

   264 If false, clone only the node itself (and its attributes, if it is an Element).

   265 

   266 Return Value: The duplicate node.

   267 

   268 =item normalize

   269 

   270 Puts all Text nodes in the full depth of the sub-tree

   271 underneath this Element into a "normal" form where only

   272 markup (e.g., tags, comments, processing instructions, CDATA

   273 sections, and entity references) separates Text nodes, i.e.,

   274 there are no adjacent Text nodes. This can be used to ensure

   275 that the DOM view of a document is the same as if it were

   276 saved and re-loaded, and is useful when operations (such as

   277 XPointer lookups) that depend on a particular document tree

   278 structure are to be used.

   279 

   280 B<Not In DOM Spec>: In the DOM Spec this method is defined in the Element and 

   281 Document class interfaces only, but it doesn't hurt to have it here...

   282 

   283 =item getElementsByTagName (name [, recurse])

   284 

   285 Returns a NodeList of all descendant elements with a given

   286 tag name, in the order in which they would be encountered in

   287 a preorder traversal of the Element tree.

   288 

   289 Parameters:

   290  I<name>  The name of the tag to match on. The special value "*" matches all tags.

   291  I<recurse>  Whether it should return only direct child nodes (0) or any descendant that matches the tag name (1). This argument is optional and defaults to 1. It is not part of the DOM spec.

   292 

   293 Return Value: A list of matching Element nodes.

   294 

   295 NOTE: this implementation does not return a "live" NodeList for

   296 getElementsByTagName. See L<CAVEATS>.

   297 

   298 When this method is called in a list context, it returns a regular perl list

   299 containing the result nodes. E.g.

   300 

   301  @list = $node->getElementsByTagName("tag");       # returns a perl list

   302  $nodelist = $node->getElementsByTagName("tag");   # returns a NodeList (object ref.)

   303  for my $elem ($node->getElementsByTagName("tag")) # iterate over the result nodes

   304 

   305 =back

   306 

   307 =head2 Additional methods not in the DOM Spec

   308 

   309 =over 4

   310 

   311 =item getNodeTypeName

   312 

   313 Return the string describing the node type. 

   314 E.g. returns "ELEMENT_NODE" if getNodeType returns ELEMENT_NODE.

   315 It uses @XML::DOM::Node::NodeNames.

   316 

   317 =item toString

   318 

   319 Returns the entire subtree as a string.

   320 

   321 =item printToFile (filename)

   322 

   323 Prints the entire subtree to the file with the specified filename.

   324 

   325 Croaks: if the file could not be opened for writing.

   326 

   327 =item printToFileHandle (handle)

   328 

   329 Prints the entire subtree to the file handle.

   330 E.g. to print to STDOUT:

   331 

   332  $node->printToFileHandle (\*STDOUT);

   333 

   334 =item print (obj)

   335 

   336 Prints the entire subtree using the object's print method. E.g to print to a

   337 FileHandle object:

   338 

   339  $f = new FileHandle ("file.out", "w");

   340  $node->print ($f);

   341 

   342 =item getChildIndex (child)

   343 

   344 Returns the index of the child node in the list returned by getChildNodes.

   345 

   346 Return Value: the index or -1 if the node is not found.

   347 

   348 =item getChildAtIndex (index)

   349 

   350 Returns the child node at the specifed index or undef.

   351 

   352 =item addText (text)

   353 

   354 Appends the specified string to the last child if it is a Text node, or else 

   355 appends a new Text node (with the specified text.)

   356 

   357 Return Value: the last child if it was a Text node or else the new Text node.

   358 

   359 =item dispose

   360 

   361 Removes all circular references in this node and its descendants so the 

   362 objects can be claimed for garbage collection. The objects should not be used

   363 afterwards.

   364 

   365 =item setOwnerDocument (doc)

   366 

   367 Sets the ownerDocument property of this node and all its children (and 

   368 attributes etc.) to the specified document.

   369 This allows the user to cut and paste document subtrees between different

   370 XML::DOM::Documents. The node should be removed from the original document

   371 first, before calling setOwnerDocument.

   372 

   373 This method does nothing when called on a Document node.

   374 

   375 =item isAncestor (parent)

   376 

   377 Returns 1 if parent is an ancestor of this node or if it is this node itself.

   378 

   379 =item expandEntityRefs (str)

   380 

   381 Expands all the entity references in the string and returns the result.

   382 The entity references can be character references (e.g. "{" or "&#x1fc2"),

   383 default entity references (""", ">", "<", "'" and "&") or

   384 entity references defined in Entity objects as part of the DocumentType of

   385 the owning Document. Character references are expanded into UTF-8.

   386 Parameter entity references (e.g. %ent;) are not expanded.

   387 

   388 =item to_sax ( %HANDLERS )

   389 

   390 E.g.

   391 

   392  $node->to_sax (DocumentHandler => $my_handler, 

   393 		Handler => $handler2 );

   394 

   395 %HANDLERS may contain the following handlers:

   396 

   397 =over 4

   398 

   399 =item * DocumentHandler

   400 

   401 =item * DTDHandler

   402 

   403 =item * EntityResolver

   404 

   405 =item * Handler 

   406 

   407 Default handler when one of the above is not specified

   408 

   409 =back

   410 

   411 Each XML::DOM::Node generates the appropriate SAX callbacks (for the

   412 appropriate SAX handler.) Different SAX handlers can be plugged in to

   413 accomplish different things, e.g. L<XML::Checker> would check the node 

   414 (currently only Document and Element nodes are supported), L<XML::Handler::BuildDOM>

   415 would create a new DOM subtree (thereby, in essence, copying the Node)

   416 and in the near future, XML::Writer could print the node.

   417 All Perl SAX related work is still in flux, so this interface may change a 

   418 little.

   419 

   420 See PerlSAX for the description of the SAX interface.

   421 

   422 =item check ( [$checker] )

   423 

   424 See descriptions for check() in L<XML::DOM::Document> and L<XML::DOM::Element>.

   425 

   426 =item xql ( @XQL_OPTIONS )

   427 

   428 To use the xql method, you must first I<use> L<XML::XQL> and L<XML::XQL::DOM>.

   429 This method is basically a shortcut for:

   430 

   431  $query = new XML::XQL::Query ( @XQL_OPTIONS );

   432  return $query->solve ($node);

   433 

   434 If the first parameter in @XQL_OPTIONS is the XQL expression, you can leave off

   435 the 'Expr' keyword, so:

   436 

   437  $node->xql ("doc//elem1[@attr]", @other_options);

   438 

   439 is identical to:

   440 

   441  $node->xql (Expr => "doc//elem1[@attr]", @other_options);

   442 

   443 See L<XML::XQL::Query> for other available XQL_OPTIONS.

   444 See L<XML::XQL> and L<XML::XQL::Tutorial> for more info.

   445 

   446 =item isHidden ()

   447 

   448 Whether the node is hidden.

   449 See L<Hidden Nodes|XML::DOM/_Hidden_Nodes_> for details.

   450 

   451 =back