Pensieve.pm untested

filter: Statementstmt 0.0% 0 / 128 Branchbran 0.0% 0 / 44 Conditioncond 0.0% 0 / 36 MC/DCmcdc 0.0% 0 / 21 Subroutinesub 0.0% 0 / 17 Podpod 0.0% 0 / 7 totaltotal 0.0% 0 / 253 CC 23 SCAR 38.7
CC
23
Cov
0%
store_revision
132.0
compare_revisions
42.0
_inflate_revision
20.0
CRAP 47.8
1 package Data::Pensieve;
2  
3 use strict;
4 use warnings;
5  
6 use Carp qw(croak);
7 use DateTime qw();
8 use List::Util qw(first);
9 use List::MoreUtils qw(uniq);
10 use Storable qw(freeze);
11 use Text::Diff qw(diff);
12  
13 use Moose;
14  
15 use Data::Pensieve::Revision;
16  
17 our $VERSION = 0.03;
18  
19 has 'revision_rs' => ( is => 'rw' );
20 has 'revision_data_rs' => ( is => 'rw' );
21 has 'definitions' => ( is => 'rw' );
22  
23 =head1 NAME
24  
25 Data::Pensieve - Simple tool for interacting with revisioned data
26  
27 =head1 SYNOPSIS
28  
29 use Data::Pensieve;
30
31 my $pensieve = Data::Pensieve->new(
32 revision_rs => $c->model('DB::Revision'),
33 revision_data_rs => $c->model('DB::RevisionData'),
34 definitions => {
35 lolcats => [ qw/name saying picture/ ],
36 },
37 );
38
39 $pensieve->store_revision(
40 lolcats => 1,
41 {
42 # data
43 name => 'lazy lolcat',
44 saying => 'i cannot brian today. i have the dumb',
45 picture => 'lazycat.png',
46 },
47 {
48 # change metadata
49 modified_by => 'waffle wizard',
50 },
51 );
52  
53 # oops! a typo! time to denote a change.
54 $pensieve->store_revision(
55 lolcats => 1,
56 {
57 # data
58 saying => 'i cannot brain today. i have the dumb',
59 },
60 {
61 # change metadata
62 modified_by => 'assistant regional manager',
63 },
64 );
65
66 my @revisions = $pensieve->get_revisions(lolcats => 1);
67
68 my ($rev1, $rev2) = @revisions;
69  
70 my $comparison = $pensieve->compare_revisions($rev1, $rev2);
71 # {
72 # saying => [
73 # 'i cannot brian today. i have the dumb',
74 # 'i cannot brain today. i have the dumb'
75 # ]
76 # }
77  
78 =head1 DESCRIPTION
79  
80 "I use the Pensieve. One simply siphons the excess thoughts from one's mind, pours them into the basin, and examines them at one's leisure. It becomes easier to spot patterns and links, you understand, when they are in this form." - Albus Dumbledore
81  
82 In the world of Harry Potter, a Pensieve is a magical device that allows a wizard to store and review his or her thoughts. Data::Pensieve serves a similar purpose for Perl applications, allowing you to easily record revision histories and analyze differences between revisions.
83  
84 Data::Pensieve uses a DBIx::Class backend to store revision data.
85  
86 =head1 METHODS
87  
88 =head2 new()
89  
90 Returns a new Data::Pensieve object. Takes the following required parameters.
91  
92 =over 4
93  
94 =item * B<definitions>
95  
96 A hash reference, where the keys are the names of groups of data and the values are array references of the expected columns.
97  
98 For instance:
99  
100 # {
101 # cats => [ qw/ name favorite_toy / ],
102 # people => [ qw/ name occupation / ],
103 # food => [ qw/ name calories / ],
104 # japh => [ qw/ cpan_name num_yapcs_attended /],
105 # }
106  
107 =item * B<revision_rs>
108  
109 A DBIx::Class::ResultSet representing the revision table, which must have the following schema:
110  
111 revision_id int auto_increment primary key,
112 grouping varchar(255),
113 identifier varchar(255),
114 recorded datetime,
115 metadata blob
116  
117 =item * B<revision_data_rs>
118  
119 A DBIx::Class::ResultSet reprensenting the revision data table, which must have the following schema:
120  
121 revision_data_id int auto_increment primary key,
122 revision_id int,
123 datum varchar(255),
124 datum_value blob
125  
126 =back
127  
128 =cut
129  
130 =head2 store_revision()
131  
132 Given a grouping, item, hash reference of data, and optional hash reference of metadata related to this change, stores a change.
133  
134 =cut
135  
136 sub store_revision
137 {
138 my ($self, $grouping, $item, $params, $metadata) = @_;
139  
140 $metadata ||= {};
141 $metadata = freeze $metadata;
142  
143 my $schema = $self->schema($grouping);
144 my @columns = ($schema and @$schema) ? @$schema : keys %$params;
145  
146 # overloaded objects can be provided as both the item identifier and the
147 # object that generates the data itself. nifty!
148 if (not defined $params and ref $item) {
149 $params = $item;
150 $item = "$item";
151 }
152  
153 # objects can be provided in lieu of a hash of parameters. however, you
154 # must provide a definition so we know what parameters to retrieve
155 if (ref $params and ref $params ne 'HASH')
156 {
157 if ($schema) {
158 my $data = {};
159 for my $column (@columns) {
160 my $id = ref $column ? $column->{id} : $column;
161
162 if ($params->can($id)) {
163 $data->{$id} = $params->$id;
164 } else {
165 $data->{$id} = $params->{$id};
166 }
167 }
168  
169 $params = $data;
170 } else {
171 croak "An object may not be provided for revision storage unless a definition is provided";
172 }
173 }
174  
175 my $last_rev = $self->get_last_revision($grouping, $item);
176  
177 my $revision = $self->revision_rs->create({
178 grouping => $grouping,
179 identifier => $item,
180 recorded => DateTime->now->ymd('-') . ' ' . DateTime->now->hms(':'),
181 metadata => $metadata,
182 });
183  
184 for my $column (@columns)
185 {
186 $column = $column->{id}
187 if ref $column;
188  
189 my $value;
190 if (exists $params->{$column})
191 {
192 $value = $params->{$column};
193 }
194 elsif ($last_rev)
195 {
196 if (exists $last_rev->data->{$column}) {
197 $value = $last_rev->data->{$column};
198 } else {
199 next;
200 }
201 }
202 else
203 {
204 next;
205 }
206  
207 $self->revision_data_rs->create({
208 revision_id => $revision->revision_id,
209 datum => $column,
210 datum_value => $value,
211 });
212 }
213  
214 return $self->_inflate_revision($revision);
215 }
216  
217 =head2 get_revisions()
218  
219 Given a grouping and item number, returns all associated revisions.
220  
221 =cut
222  
223 sub get_revisions
224 {
225 my ($self, $grouping, $item, $revision_ids) = @_;
226  
227 $item = "$item";
228  
229 my %query = (
230 grouping => $grouping,
231 identifier => $item,
232 );
233  
234 if ($revision_ids) {
235 $query{revision_id} = $revision_ids;
236 }
237  
238 return map { $self->_inflate_revision($_) } $self->revision_rs->search( \%query );
239 }
240  
241 =head2 get_last_revision()
242  
243 Given a grouping and item number, returns the last revision.
244  
245 =cut
246  
247 sub get_last_revision
248 {
249 my ($self, $grouping, $item) = @_;
250  
251 $item = "$item";
252  
253 my $record = $self->revision_rs->search({
254 grouping => $grouping,
255 identifier => $item,
256 }, {
257 order_by => { -desc => 'revision_id' },
258 rows => 1,
259 })->first;
260  
261 return $self->_inflate_revision($record);
262 }
263  
264 =head2 compare_revisions()
265  
266 Given two Data::Pensieve::Revision objects, returns a hash reference, keyed by column name, containing array references of the prior and current version of all changed data between the two provided revisions.
267  
268 =cut
269  
270 sub compare_revisions
271 {
272 my ($self, $rev1, $rev2) = @_;
273  
274 croak "Two revisions must be provided"
275 unless ($rev1 and $rev2);
276  
277 # Swap revisions 1 and 2 if revision 1 is newer
278 my @revisions = ($rev1, $rev2);
279 @revisions = sort {
280 $a->row->revision_id <=> $b->row->revision_id ||
281 $a->row->recorded <=> $b->row->recorded
282 } @revisions;
283 ($rev1, $rev2) = @revisions;
284  
285 my $data1 = $rev1->data;
286 my $data2 = $rev2->data;
287  
288 my $schema = $self->schema($rev1->row->grouping);
289 my @columns = ($schema and @$schema) ? @$schema : uniq (keys %$data1, keys %$data2);
290  
291 my %differences;
292 for my $key (@columns)
293 {
294 $key = ref $key ? $key->{id} : $key;
295  
296 next unless (
297 ( ((exists $data1->{$key}) + (exists $data2->{$key})) == 1 ) or
298 ( ((defined $data1->{$key}) + (defined $data2->{$key})) == 1 ) or
299 ( $data1->{$key} ne $data2->{$key} )
300 );
301  
302 $differences{$key} = [ $data1->{$key}, $data2->{$key} ];
303 }
304  
305 return wantarray ? %differences : \%differences;
306 }
307  
308 =head2 diff_revisions()
309  
310 Same as compare_revisions(), but returns a diff between the two values instead of an array reference.
311  
312 =cut
313  
314 sub diff_revisions
315 {
316 my ($self, $rev1, $rev2) = @_;
317  
318 my $comparison = $self->compare_revisions($rev1, $rev2);
319  
320 for my $key (keys %$comparison)
321 {
322 my $values = $comparison->{$key};
323 my ($cmp1, $cmp2) = @$values;
324  
325 my $diff = diff( \$cmp1, \$cmp2, { STYLE => 'Text::Diff::HTML' } );
326 $comparison->{$key} = $diff;
327 }
328  
329 return wantarray ? %$comparison : $comparison;
330 }
331  
332 #
333 # Here be undocumented methods.
334 #
335  
336 sub _inflate_revision
337 {
338 my ($self, $revision) = @_;
339  
340 return unless $revision;
341  
342 my $row = ref $revision
343 ? $revision
344 : $self->revision_rs->find($revision);
345  
346 return unless $row;
347  
348 return Data::Pensieve::Revision->new(
349 pensieve => $self,
350 row => $row,
351 );
352 }
353  
354 sub schema
355 {
356 my ($self, $grouping, $key) = @_;
357  
358 my $definitions = $self->definitions || {};
359 my $definition = $definitions->{$grouping};
360  
361 my $i = 0;
362 for my $col (@$definition)
363 {
364 unless (ref $col and ref $col eq 'HASH') {
365 $col = { id => $col };
366 }
367  
368 $col->{label} ||= ucfirst $col->{id} || '';
369 $definition->[$i] = $col;
370  
371 $i++;
372 }
373  
374 if ($key) {
375 return first { $_->{id} eq $key } @$definition;
376 }
377  
378 return $definition;
379 }
380  
381 =head1 SEE ALSO
382  
383 Data::Pensieve is intended as a quick & dirty, plug & play way to easily manage revisioned data.
384  
385 If you're looking to do something more substantial, you probably want to consider journaling your data at the database level -- check out L<DBIx::Class::AuditLog> or L<DBIx::Class::Journal>.
386  
387 =head1 DEPENDENCIES
388  
389 L<Carp>, L<DateTime>, L<DateTime::Format::MySQL>, L<DBIx::Class>, L<List::Util>, L<List::MoreUtils>, L<Moose>, L<Storable>, L<Text::Diff>
390  
391 =head1 AUTHORS
392  
393 Michael Aquilina <aquilina@cpan.org>
394  
395 Developed for Grant Street Group's Testafy (L<< http://testafy.com >>)
396  
397 =cut
398  
399 1;
400