--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/deprecated/buildtools/buildsystemtools/lib/XML/DOM/NamedNodeMap.pod	Wed Oct 27 16:03:51 2010 +0800
@@ -0,0 +1,130 @@
+=head1 NAME
+
+XML::DOM::NamedNodeMap - A hash table interface for XML::DOM
+
+=head1 DESCRIPTION
+
+Objects implementing the NamedNodeMap interface are used to represent
+collections of nodes that can be accessed by name. Note that
+NamedNodeMap does not inherit from NodeList; NamedNodeMaps are not
+maintained in any particular order. Objects contained in an object
+implementing NamedNodeMap may also be accessed by an ordinal index, but
+this is simply to allow convenient enumeration of the contents of a
+NamedNodeMap, and does not imply that the DOM specifies an order to
+these Nodes.
+
+Note that in this implementation, the objects added to a NamedNodeMap
+are kept in order.
+
+=head2 METHODS
+
+=over 4
+
+=item getNamedItem (name)
+
+Retrieves a node specified by name.
+
+Return Value: A Node (of any type) with the specified name, or undef if
+the specified name did not identify any node in the map.
+
+=item setNamedItem (arg)
+
+Adds a node using its nodeName attribute.
+
+As the nodeName attribute is used to derive the name which
+the node must be stored under, multiple nodes of certain
+types (those that have a "special" string value) cannot be
+stored as the names would clash. This is seen as preferable
+to allowing nodes to be aliased.
+
+Parameters:
+ I<arg>  A node to store in a named node map. 
+
+The node will later be accessible using the value of the nodeName
+attribute of the node. If a node with that name is
+already present in the map, it is replaced by the new one.
+
+Return Value: If the new Node replaces an existing node with the same
+name the previously existing Node is returned, otherwise undef is returned.
+
+DOMExceptions:
+
+=over 4
+
+=item * WRONG_DOCUMENT_ERR
+
+Raised if arg was created from a different document than the one that 
+created the NamedNodeMap.
+
+=item * NO_MODIFICATION_ALLOWED_ERR
+
+Raised if this NamedNodeMap is readonly.
+
+=item * INUSE_ATTRIBUTE_ERR
+
+Raised if arg is an Attr that is already an attribute of another Element object.
+The DOM user must explicitly clone Attr nodes to re-use them in other elements.
+
+=back
+
+=item removeNamedItem (name)
+
+Removes a node specified by name. If the removed node is an
+Attr with a default value it is immediately replaced.
+
+Return Value: The node removed from the map or undef if no node with
+such a name exists.
+
+DOMException:
+
+=over 4
+
+=item * NOT_FOUND_ERR
+
+Raised if there is no node named name in the map.
+
+=back
+
+=item item (index)
+
+Returns the indexth item in the map. If index is greater than
+or equal to the number of nodes in the map, this returns undef.
+
+Return Value: The node at the indexth position in the NamedNodeMap, or
+undef if that is not a valid index.
+
+=item getLength
+
+Returns the number of nodes in the map. The range of valid child node
+indices is 0 to length-1 inclusive.
+
+=back
+
+=head2 Additional methods not in the DOM Spec
+
+=over 4
+
+=item getValues
+
+Returns a NodeList with the nodes contained in the NamedNodeMap.
+The NodeList is "live", in that it reflects changes made to the NamedNodeMap.
+
+When this method is called in a list context, it returns a regular perl list
+containing the values. Note that this list is not "live". E.g.
+
+ @list = $map->getValues;	 # returns a perl list
+ $nodelist = $map->getValues;    # returns a NodeList (object ref.)
+ for my $val ($map->getValues)   # iterate over the values
+
+=item getChildIndex (node)
+
+Returns the index of the node in the NodeList as returned by getValues, or -1
+if the node is not in the NamedNodeMap.
+
+=item dispose
+
+Removes all circular references in this NamedNodeMap and its descendants so the 
+objects can be claimed for garbage collection. The objects should not be used
+afterwards.
+
+=back