dummy_foundation/lib/XML/DOM/Node.pod
changeset 0 02cd6b52f378
equal deleted inserted replaced
-1:000000000000 0:02cd6b52f378
       
     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. "&#123;" or "&#x1fc2"),
       
   383 default entity references ("&quot;", "&gt;", "&lt;", "&apos;" and "&amp;") 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