|
1 =head1 NAME |
|
2 |
|
3 XML::DOM::NamedNodeMap - A hash table interface for XML::DOM |
|
4 |
|
5 =head1 DESCRIPTION |
|
6 |
|
7 Objects implementing the NamedNodeMap interface are used to represent |
|
8 collections of nodes that can be accessed by name. Note that |
|
9 NamedNodeMap does not inherit from NodeList; NamedNodeMaps are not |
|
10 maintained in any particular order. Objects contained in an object |
|
11 implementing NamedNodeMap may also be accessed by an ordinal index, but |
|
12 this is simply to allow convenient enumeration of the contents of a |
|
13 NamedNodeMap, and does not imply that the DOM specifies an order to |
|
14 these Nodes. |
|
15 |
|
16 Note that in this implementation, the objects added to a NamedNodeMap |
|
17 are kept in order. |
|
18 |
|
19 =head2 METHODS |
|
20 |
|
21 =over 4 |
|
22 |
|
23 =item getNamedItem (name) |
|
24 |
|
25 Retrieves a node specified by name. |
|
26 |
|
27 Return Value: A Node (of any type) with the specified name, or undef if |
|
28 the specified name did not identify any node in the map. |
|
29 |
|
30 =item setNamedItem (arg) |
|
31 |
|
32 Adds a node using its nodeName attribute. |
|
33 |
|
34 As the nodeName attribute is used to derive the name which |
|
35 the node must be stored under, multiple nodes of certain |
|
36 types (those that have a "special" string value) cannot be |
|
37 stored as the names would clash. This is seen as preferable |
|
38 to allowing nodes to be aliased. |
|
39 |
|
40 Parameters: |
|
41 I<arg> A node to store in a named node map. |
|
42 |
|
43 The node will later be accessible using the value of the nodeName |
|
44 attribute of the node. If a node with that name is |
|
45 already present in the map, it is replaced by the new one. |
|
46 |
|
47 Return Value: If the new Node replaces an existing node with the same |
|
48 name the previously existing Node is returned, otherwise undef is returned. |
|
49 |
|
50 DOMExceptions: |
|
51 |
|
52 =over 4 |
|
53 |
|
54 =item * WRONG_DOCUMENT_ERR |
|
55 |
|
56 Raised if arg was created from a different document than the one that |
|
57 created the NamedNodeMap. |
|
58 |
|
59 =item * NO_MODIFICATION_ALLOWED_ERR |
|
60 |
|
61 Raised if this NamedNodeMap is readonly. |
|
62 |
|
63 =item * INUSE_ATTRIBUTE_ERR |
|
64 |
|
65 Raised if arg is an Attr that is already an attribute of another Element object. |
|
66 The DOM user must explicitly clone Attr nodes to re-use them in other elements. |
|
67 |
|
68 =back |
|
69 |
|
70 =item removeNamedItem (name) |
|
71 |
|
72 Removes a node specified by name. If the removed node is an |
|
73 Attr with a default value it is immediately replaced. |
|
74 |
|
75 Return Value: The node removed from the map or undef if no node with |
|
76 such a name exists. |
|
77 |
|
78 DOMException: |
|
79 |
|
80 =over 4 |
|
81 |
|
82 =item * NOT_FOUND_ERR |
|
83 |
|
84 Raised if there is no node named name in the map. |
|
85 |
|
86 =back |
|
87 |
|
88 =item item (index) |
|
89 |
|
90 Returns the indexth item in the map. If index is greater than |
|
91 or equal to the number of nodes in the map, this returns undef. |
|
92 |
|
93 Return Value: The node at the indexth position in the NamedNodeMap, or |
|
94 undef if that is not a valid index. |
|
95 |
|
96 =item getLength |
|
97 |
|
98 Returns the number of nodes in the map. The range of valid child node |
|
99 indices is 0 to length-1 inclusive. |
|
100 |
|
101 =back |
|
102 |
|
103 =head2 Additional methods not in the DOM Spec |
|
104 |
|
105 =over 4 |
|
106 |
|
107 =item getValues |
|
108 |
|
109 Returns a NodeList with the nodes contained in the NamedNodeMap. |
|
110 The NodeList is "live", in that it reflects changes made to the NamedNodeMap. |
|
111 |
|
112 When this method is called in a list context, it returns a regular perl list |
|
113 containing the values. Note that this list is not "live". E.g. |
|
114 |
|
115 @list = $map->getValues; # returns a perl list |
|
116 $nodelist = $map->getValues; # returns a NodeList (object ref.) |
|
117 for my $val ($map->getValues) # iterate over the values |
|
118 |
|
119 =item getChildIndex (node) |
|
120 |
|
121 Returns the index of the node in the NodeList as returned by getValues, or -1 |
|
122 if the node is not in the NamedNodeMap. |
|
123 |
|
124 =item dispose |
|
125 |
|
126 Removes all circular references in this NamedNodeMap and its descendants so the |
|
127 objects can be claimed for garbage collection. The objects should not be used |
|
128 afterwards. |
|
129 |
|
130 =back |