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