Advanced/Dictionary.pm untested

filter: Statementstmt 0.0% 0 / 74 Branchbran 0.0% 0 / 18 Conditioncond 0.0% 0 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 0.0% 0 / 14 Podpod 0.0% 0 / 12 totaltotal 0.0% 0 / 123 CC 10 SCAR 20.6
CC
10
Cov
0%
find
20.0
get_value
12.0
update
6.0
CRAP 7.8
1 #
2 # AI::ExpertSystem::Advanced::Dictionary
3 #
4 # Author(s): Pablo Fischer (pfischer@cpan.org)
5 # Created: 11/29/2009 20:06:22 CST 20:06:22
6 package AI::ExpertSystem::Advanced::Dictionary;
7  
8 =head1 NAME
9  
10 AI::ExpertSystem::Advanced::Dictionary - Array/hash dictionary
11  
12 =head1 DESCRIPTION
13  
14 The dictionary offers a unified interface for:
15  
16 =over 4
17  
18 =item 1
19  
20 Reading through a list of items with a minimal use of memory since it offers an
21 iterator that works with a stack. So everytime it gets asked for the next
22 element it I<drops> the first or last element of the stack.
23  
24 =item 2
25  
26 Finding an element in the stack.
27  
28 =item 3
29  
30 Adding or removing elements from the stack.
31  
32 =back
33  
34 =cut
35 use Moose;
36 use List::MoreUtils qw(firstidx);
37  
38 our $VERSION = '0.03';
39  
40 =head1 Attributes
41  
42 =over 4
43  
44 =item B<stack>
45  
46 An array with all the keys of C<stack_hash>. Useful for creating the
47 C<iterable_array> and for knowing the order of the items as they get added or
48 removed.
49  
50 =cut
51 has 'stack' => (
52 is => 'rw',
53 isa => 'ArrayRef');
54  
55 =item B<stack_hash>
56  
57 The original hash, has all the elements with all their properties (eg extra
58 keys). The I<disadvantage> of it is that it doesn't keeps the order of the
59 elements, hence the need of C<stack>.
60  
61 =cut
62 has 'stack_hash' => (
63 is => 'ro',
64 isa => 'HashRef[Str]');
65  
66 =item B<iterable_array>
67  
68 Used by the C<iterate()> and C<iterate_reverse()> methods. It starts as a copy
69 of C<stack> and as the iterate methods start running this array starts getting
70 I<reduced> until it gets to an empty list.
71  
72 =back
73  
74 =cut
75 has 'iterable_array' => (
76 is => 'ro',
77 isa => 'ArrayRef');
78  
79 =head1 Methods
80  
81 =head2 B<find($look_for, $find_by)>
82  
83 Looks for a given value (C<$look_for>). By default it will look for the value
84 by reading the C<id> of each item, however this can be changed by passing
85 a different hash key (C<$find_by>).
86  
87 In case there's no match C<undef> is returned.
88  
89 =cut
90 sub find {
91 my ($self, $look_for, $find_by) = @_;
92  
93 if (!defined($find_by)) {
94 if (defined $self->{'stack_hash'}->{$look_for}) {
95 return $look_for;
96 }
97 return undef;
98 }
99  
100 foreach my $key (keys %{$self->{'stack_hash'}}) {
101 if ($self->{'stack_hash'}->{$key}->{$find_by} eq $look_for) {
102 return $key;
103 }
104 }
105 return undef;
106 }
107  
108 =head2 B<get_value($id, $key)>
109  
110 The L<AI::ExpertSystem::Advanced::Dictionary> consists of a hash of elements,
111 each element has its own properties (eg, extra keys).
112  
113 This method looks for the value of the given C<$key> of a given element C<id>.
114  
115 It will return the value, but if element doesn't have the given C<$key> then
116 C<undef> will be returned.
117  
118 =cut
119 sub get_value {
120 my ($self, $id, $key) = @_;
121  
122 if (!defined $self->{'stack_hash'}->{$id}) {
123 return undef;
124 }
125 if (defined $self->{'stack_hash'}->{$id}->{$key}) {
126 return $self->{'stack_hash'}->{$id}->{$key};
127 } else {
128 return undef;
129 }
130 }
131  
132 =head2 B<append($id, %extra_keys)>
133  
134 Adds a new element to the C<stack_hash> and C<stack>. The element gets added to
135 the end of C<stack>.
136  
137 The C<$id> parameter specifies the id of the new element and the next parameter
138 is a stack of I<extra> keys.
139  
140 =cut
141 sub append {
142 my $self = shift;
143 my $id = shift;
144  
145 return $self->_add($id, undef, @_);
146 }
147  
148 =head2 B<prepend($id, %extra_keys)>
149  
150 Same as C<append()>, but the element gets added to the top of the C<stack>.
151  
152 =cut
153 sub prepend {
154 my $self = shift;
155 my $id = shift;
156  
157 return $self->_add($id, 1, @_);
158 }
159  
160 =head2 B<update($id, %extra_keys)>
161  
162 Updates the I<extra> keys of the element that matches the given C<$id>.
163  
164 Please note that it will only update or add new keys. So if the given element
165 already has a key and this is not provided in C<%extra_keys> then it wont
166 be modified.
167  
168 =cut
169 sub update {
170 my ($self, $id, $properties) = @_;
171  
172 if (defined $self->{'stack_hash'}->{$id}) {
173 foreach my $key (keys %$properties) {
174 $self->{'stack_hash'}->{$id}->{$key} = $properties->{$key};
175 }
176 } else {
177 warn "Not updating $id, does not exist!";
178 }
179 }
180  
181 =head2 B<remove($id)>
182  
183 Removes the element that matches the given C<$id> from C<stack_hash> and
184 C<stack>.
185  
186 Returns true if the removal is successful, otherwise false is returned.
187  
188 =cut
189 sub remove {
190 my ($self, $id) = @_;
191  
192 if (defined $self->{'stack_hash'}->{$id}) {
193 delete($self->{'stack_hash'}->{$id});
194 # Find the index in the array, lets suppose our arrays are big
195 my $index = List::MoreUtils::first_index {
196 defined $_ and $_ eq $id
197 } @{$self->{'stack'}};
198 splice(@{$self->{'stack'}}, $index, 1);
199 return 1;
200 }
201 return 0;
202 }
203  
204 =head2 B<size()>
205  
206 Returns the size of C<stack>.
207  
208 =cut
209 sub size {
210 my ($self) = @_;
211  
212 return scalar(@{$self->{'stack'}});
213 }
214  
215 =head2 B<iterate()>
216  
217 Returns the first element of the C<iterable_array> and C<iterable_array> is
218 reduced by one.
219  
220 If no more items are found in C<iterable_array> then C<undef> is returned.
221  
222 =cut
223 sub iterate {
224 my ($self) = @_;
225  
226 return shift(@{$self->{'iterable_array'}});
227 }
228  
229 =head2 B<iterate_reverse()>
230  
231 Same as C<iterate()>, but instead of returning the first element, it returns
232 the last element of C<iterable_array>.
233  
234 =cut
235 sub iterate_reverse {
236 my ($self) = @_;
237  
238 return pop(@{$self->{'iterable_array'}});
239 }
240  
241 =head2 B<populate_iterable_array()>
242  
243 The C<iterable_array> gets populated when a dictionary instance is created,
244 however if new items are added or removed then it's B<extremely> needed to call
245 this method so C<iterable_array> gets populated again.
246  
247 =cut
248 sub populate_iterable_array {
249 my ($self) = @_;
250  
251 @{$self->{'iterable_array'}} = @{$self->{'stack'}};
252 }
253  
254 # No need to document it, used by L<Moose>.
255 sub BUILD {
256 my ($self) = @_;
257  
258 foreach (@{$self->{'stack'}}) {
259 if (ref($_) eq 'ARRAY') {
260 $self->{'stack_hash'}->{$_->[0]} = {
261 name => $_->[0],
262 sign => $_->[1]
263 };
264 } else {
265 $self->{'stack_hash'}->{$_} = {
266 name => $_,
267 sign => '+'
268 };
269 }
270 }
271 $self->populate_iterable_array();
272 }
273  
274 ################# Private methods ######################
275 sub _add {
276 my ($self, $id, $prepend, $properties) = @_;
277
278 $self->{'stack_hash'}->{$id} = $properties;
279 if ($prepend) {
280 unshift(@{$self->{'stack'}}, $id);
281 } else {
282 push(@{$self->{'stack'}}, $id);
283 }
284 }
285  
286 =head1 AUTHOR
287
288 Pablo Fischer (pablo@pablo.com.mx).
289  
290 =head1 COPYRIGHT
291
292 Copyright (C) 2010 by Pablo Fischer.
293
294 This library is free software; you can redistribute it and/or modify
295 it under the same terms as Perl itself.
296  
297 =cut
298  
299 1;