blib/lib/Catmandu/Plugin/Versioning.pm

filter: Statementstmt 91.5% 76 / 83 Branchbran 60.7% 17 / 28 Conditioncond 62.5% 10 / 16 MC/DCmcdc 33.3% 3 / 9 Subroutinesub 95.0% 19 / 20 Podpod 100% 5 / 5 totaltotal 80.7% 130 / 161 CC 23 SCAR 14.0
CC
23
Cov
81%
__ANON__
9.1
_trigger_version_compare_ignore
6.0
get_previous_version
4.6
CRAP 4.1
« blib/lib/Catmandu/Pluggable.pm ↑ Summary blib/lib/Catmandu/Cmd/delete.pm »
1 package Catmandu::Plugin::Versioning;
2  
3 1 ▶use Catmandu::Sane;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 1 our $VERSION = '1.0201_02';
6  
7 1 ▶use Catmandu::Util qw(is_value is_array_ref check_value check_positive);
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use Data::Compare;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 1 ▶use Moo::Role;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 ▶use namespace::clean;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 1 has version_bag_name => (is => 'lazy', init_arg => 'version_bag');
13 1 has version_bag => (is => 'lazy', init_arg => undef);
14 1 has version_key => (is => 'lazy');
15  
16 has version_compare_ignore => (
17 is => 'lazy',
18 coerce => sub {
19 4 ▶ my $keys = $_[0];
Subroutine __ANON__: called CC=3 SCAR=11.4
20 4 ▶ $keys = [@$keys] if is_array_ref $keys;
Branch: 1 branch
BranchTrueFalseTotal
if Ref::Util::XS::is_plain_arrayref($keys) 4 0 4
21 4 ▶ $keys = [split /,/, $keys] if is_value $keys;
Branch: 1 branch
BranchTrueFalseTotal
if is_value($keys) 0 4 4
22 4 $keys;
23 },
24 1 );
25  
26 has version_transfer => (
27 is => 'lazy',
28 coerce => sub {
29 4 ▶ my $keys = $_[0];
Subroutine __ANON__: called CC=3 SCAR=11.4
30 4 ▶ $keys = [@$keys] if is_array_ref $keys;
Branch: 1 branch
BranchTrueFalseTotal
if Ref::Util::XS::is_plain_arrayref($keys) 4 0 4
31 4 ▶ $keys = [split /,/, $keys] if is_value $keys;
Branch: 1 branch
BranchTrueFalseTotal
if is_value($keys) 0 4 4
32 4 $keys;
33 },
34 1 );
35  
36 sub _build_version_bag_name {
37 2 ▶ $_[0]->name . '_version';
Subroutine _build_version_bag_name: called CC=1 SCAR=0.0
38 }
39  
40 sub _build_version_bag {
41 3 ▶ $_[0]->store->bag($_[0]->version_bag_name);
Subroutine _build_version_bag: called CC=1 SCAR=0.0
42 }
43  
44 sub _build_version_key {
45 4 ▶ $_[0]->store->key_for('version');
Subroutine _build_version_key: called CC=1 SCAR=0.0
46 }
47  
48 sub _build_version_compare_ignore {
49 2 ▶ [$_[0]->version_key];
Subroutine _build_version_compare_ignore: called CC=1 SCAR=0.0
50 }
51  
52 sub _trigger_version_compare_ignore {
53 0 ▶ my ($self, $keys) = @_;
Subroutine _trigger_version_compare_ignore: not called CC=2 SCAR=17.9
54 0 my $version_key = $self->version_key;
55 0 ▶ push @$keys, $version_key unless grep /^$version_key$/, @$keys;
Branch: 1 branch
BranchTrueFalseTotal
unless grep /^$version_key$/, @$keys 0 0 0
56 }
57  
58 sub _build_version_transfer {
59 3 ▶ [];
Subroutine _build_version_transfer: called CC=1 SCAR=0.0
60 }
61  
62 sub _version_id {
63 16 ▶ my ($self, $id, $version) = @_;
Subroutine _version_id: called CC=1 SCAR=0.0
64 16 "$id.$version";
65 }
66  
67 around add => sub {
68 13 ▶ my ($sub, $self, $data) = @_;
Subroutine __ANON__: called CC=9 SCAR=22.1
69 13 my $id_key = $self->id_key;
70 13 my $version_key = $self->version_key;
71 13 ▶ if (defined $data->{$id_key} and my $d = $self->get($data->{$id_key})) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $data->{$id_key} and my $d = $self->get($data->{$id_key})) { } 8 5 13
Condition100%3/3
defined $data->{$id_key} and my $d = $self->get($data->{$id_key})
!ll&&!rl&&r
148
MC/DC100%2/2
defined $data->{$id_key} and my $d = $self->get($data->{$id_key})
defined $data->{$id_key} my $d = $self->get($data->{$id_key})
Truth table100%3/3
A and B
A= defined $data->{$id_key}B= my $d = $self->get($data->{$id_key})
ABresult
0X0
100
111
72 8 ▶ $data->{$version_key} = $d->{$version_key} ||= 1;
Condition50%1/2
$d->{$version_key} ||= 1
l!l
80
MC/DC0%0/1
$d->{$version_key} ||= 1
$d->{$version_key}
Truth table50%1/2
A
A= $d->{$version_key}
Aresult
11
00
73 8 for my $key (@{$self->version_transfer}) {
74 2 ▶ next if exists $data->{$key} || !exists $d->{$key};
Branch: 1 branch
BranchTrueFalseTotal
if exists $data->{$key} or not exists $d->{$key} 1 1 2
Condition66%2/3
exists $data->{$key} or not exists $d->{$key}
l!l&&r!l&&!r
101
MC/DC50%1/2
exists $data->{$key} or not exists $d->{$key}
exists $data->{$key} not exists $d->{$key}
Truth table66%2/3
A or not(B)
A= exists $data->{$key}B= not exists $d->{$key}
ABresult
1X1
011
000
75 1 $data->{$key} = $d->{$key};
76 }
77 8 ▶ return $data
Branch: 1 branch
BranchTrueFalseTotal
if Compare($data, $d, {"ignore_hash_keys", $self->version_compare_ignore}) 1 7 8
78 if Compare($data, $d,
79 {ignore_hash_keys => $self->version_compare_ignore});
80 my $version_id
81 7 = $self->_version_id($data->{$id_key}, $data->{$version_key});
82 7 $self->version_bag->add(
83 {$self->version_bag->id_key => $version_id, data => $d});
84 7 $data->{$version_key}++;
85 }
86 else {
87 5 ▶ $data->{$version_key} ||= 1;
Condition50%1/2
$data->{$version_key} ||= 1
l!l
05
MC/DC0%0/1
$data->{$version_key} ||= 1
$data->{$version_key}
Truth table50%1/2
A
A= $data->{$version_key}
Aresult
11
00
88 }
89 12 $sub->($self, $data);
90 1 };
91  
92 sub get_history {
93 3 ▶ my ($self, $id, %opts) = @_;
Subroutine get_history: called CC=4 SCAR=14.2
Pod documented
94 3 ▶ if (my $data = $self->get($id)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $data = $self->get($id)) 3 0 3
95 3 my $history = [$data];
96 3 ▶ my $version = $data->{$self->version_key} || 1;
Condition50%1/2
$$data{$self->version_key} || 1
l!l
30
MC/DC0%0/1
$$data{$self->version_key} || 1
$$data{$self->version_key}
Truth table50%1/2
A
A= $$data{$self->version_key}
Aresult
11
00
97 3 ▶ while (--$version) {
Branch: 1 branch
BranchTrueFalseTotal
if (--$version) 3 3 6
98 3 push @$history, $self->get_version($id, $version);
99 }
100 3 return $history;
101 }
102 0 return;
103 }
104  
105 sub get_version {
106 9 ▶ my ($self, $id, $version) = @_;
Subroutine get_version: called CC=2 SCAR=7.0
Pod documented
107 9 check_value($id);
108 9 check_positive($version);
109 9 ▶ my $data = $self->version_bag->get($self->_version_id($id, $version))
Condition50%1/2
$self->version_bag->get($self->_version_id($id, $version)) || (return)
l!l
90
MC/DC0%0/1
$self->version_bag->get($self->_version_id($id, $version)) || (return)
$self->version_bag->get($self->_version_id($id, $version))
Truth table50%1/2
A
A= $self->version_bag->get($self->_version_id($id, $version))
Aresult
11
00
110 || return;
111 9 $data->{data};
112 }
113  
114 sub restore_version {
115 1 ▶ my ($self, $id, $version) = @_;
Subroutine restore_version: called CC=2 SCAR=7.6
Pod documented
116 1 ▶ if (my $data = $self->get_version($id, $version)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $data = $self->get_version($id, $version)) 1 0 1
117 1 return $self->add($data);
118 }
119 0 return;
120 }
121  
122 sub get_previous_version {
123 3 ▶ my ($self, $id) = @_;
Subroutine get_previous_version: called CC=4 SCAR=15.2
Pod documented
124 3 ▶ if (my $data = $self->get($id)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $data = $self->get($id)) 3 0 3
125 3 ▶ my $version = $data->{$self->version_key} || 1;
Condition50%1/2
$$data{$self->version_key} || 1
l!l
30
MC/DC0%0/1
$$data{$self->version_key} || 1
$$data{$self->version_key}
Truth table50%1/2
A
A= $$data{$self->version_key}
Aresult
11
00
126 3 ▶ if ($version > 1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($version > 1) 3 0 3
127 3 return $self->get_version($id, $version - 1);
128 }
129 }
130 0 return;
131 }
132  
133 sub restore_previous_version {
134 1 ▶ my ($self, $id) = @_;
Subroutine restore_previous_version: called CC=2 SCAR=7.6
Pod documented
135 1 ▶ if (my $data = $self->get_previous_version($id)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $data = $self->get_previous_version($id)) 1 0 1
136 1 return $self->add($data);
137 }
138 0 return;
139 }
140  
141 1 1;
142  
143 __END__
144  
145 =pod
146  
147 =head1 NAME
148  
149 Catmandu::Plugin::Versioning - Automatically adds versioning to Catmandu::Store records
150  
151 =head1 SYNOPSIS
152  
153 # Using configuration files
154  
155 $ cat catmandu.yml
156 ---
157 store:
158 test:
159 package: MongoDB
160 options:
161 database_name: test
162 bags:
163 data:
164 plugins:
165 - Versioning
166  
167 # Add two version of record 001 to the store
168 $ echo '{"_id":"001",hello":"world"}' | catmandu import JSON to test
169 $ echo '{"_id":"001",hello":"world2"}' | catmandu import JSON to test
170  
171 # In the store we see only the latest version
172 $ catmandu export test to YAML
173 ---
174 _id: '001'
175 _version: 2
176 hello: world2
177  
178 # In the '_version' store we'll find all the previous versions
179 $ catmandu export test --bag data_version to YAML
180 ---
181 _id: '001.1'
182 data:
183 _id: '001'
184 _version: 1
185 hello: world
186  
187 # Or in your Perl program
188 my $store = Catmandu::Store::MongoDB->new(
189 database_name => 'test' ,
190 bags => {
191 data => {
192 plugins => [qw(Versioning)]
193 }
194 });
195
196 $store->bag->add({ _id => '001' , hello => 'world'});
197 $store->bag->add({ _id => '001' , hello => 'world2'});
198  
199 print "Versions:\n";
200  
201 for (@{$store->bag->get_history('001')}) {
202 print Dumper($_);
203 }
204  
205 =head1 DESCRIPTION
206  
207 The Catmandu::Plugin::Versioning plugin automatically adds a new 'version' bag to your Catmandu::Store
208 containing previous versions of newly created records. The name of the version is created by appending
209 '_version' to your original bag name. E.g. when add the Versioning plugin to a 'test' bag then 'test_version'
210 will contain the previous version of all your records.
211  
212 When using Catmandu::Store-s that don't have dynamic schema's (e.g. Solr , DBI) these new bags need to be
213 predefined (e.g. create new Solr cores or database tables).
214  
215 =head1 CONFIGURATION
216  
217 =over
218  
219 =item version_compare_ignore
220  
221 By default every change to a record with trigger the creation of a new version. Use the version_compare_ignore option
222 to specify fields that should be ignored when testing for new updates. E.g. in the example below we configured the
223 MongoDB store to add versioning to the default 'data' bag. We want to ignore changes to the 'date_updated' field
224 when creating new version records
225  
226 # catmandu.yml
227 ---
228 store:
229 test:
230 package: MongoDB
231 options:
232 database_name: test
233 bags:
234 data:
235 plugins:
236 - Versioning
237 version_compare_ignore:
238 - date_updated
239  
240 # In your perl
241  
242 # First version
243 $store->bag->add({ _id => '001' , name => 'test' , date_updated => '10:00' });
244  
245 # Second version (name has changed)
246 $store->bag->add({ _id => '001' , name => 'test123' , date_updated => '10:00' });
247  
248 # Second version (date_updated has changed but we ignored that in our configuration)
249 $store->bag->add({ _id => '001' , name => 'test123' , date_updated => '10:15' });
250  
251 =item version_transfer
252  
253 This option autmatically copies the configured fields from the previous version of a record to the new version of the
254 record. E.g. in the example below we will create a versioning on the default bag and add a rights statement that can
255 not be deleted.
256  
257 # catmandu.yml
258 ---
259 store:
260 test:
261 package: MongoDB
262 options:
263 database_name: test
264 bags:
265 data:
266 plugins:
267 - Versioning
268 version_transfer:
269 - rights:
270  
271 # In your perl
272  
273 # First version
274 $store->bag->add({ _id => '001' , name => 'test' , rights => 'Acme Corp.' });
275  
276 # Second version we will try you delete rights but this is copied to the new version
277 $store->bag->add({ _id => '001' , name => 'test'});
278  
279 print "Rights: %s\n" , $store->bag->get('001')->{rights}; # Rights: Acme Corp.
280  
281 =item version_bag
282  
283 The name of the bag that stores the versions. Default is the name of the
284 versioned bag with '_version' appended.
285  
286 my $store = Catmandu::Store::MyDB->new(bags => {book => {plugins =>
287 ['Versioning'], version_bag => 'book_history'}});
288 $store->bag('book')->version_bag->name # returns 'book_history'
289  
290 =item version_key
291  
292 Use a custom key to hold the version number in this bag. Default is '_version'
293 unless the store has a custom C<key_prefix>.
294  
295 =back
296  
297 =head1 METHODS
298  
299 Every bag that is configured with the Catmandu::Plugin::Versioning plugin can use the following methods:
300  
301 =head2 get_version(ID,VERSION)
302  
303 Retrieve a record with identifier ID and version identifier VERSION. E.g.
304  
305 my $obj = $store->bag('test')->get_version('001',1);
306  
307 =head2 get_previous_version(ID)
308  
309 Retrieve the previous version of a record with identifier ID. E.g.
310  
311 =head2 get_history(ID)
312  
313 Returns an ARRAY reference with all the versions of the record with identifier ID.
314  
315 =head2 restore_version(ID,VERSION)
316  
317 Overwrites the current version of the stored record with identifier ID with a version with identifier VERSION.
318  
319 =head2 restore_previous_version(ID)
320  
321 Overwrites the current version of the stored record with identifier ID with its previous version.
322  
323 =head1 SEE ALSO
324  
325 L<Catmandu::Store>, L<Catmandu::Bag>
326  
327 =cut
« blib/lib/Catmandu/Pluggable.pm ↑ Summary blib/lib/Catmandu/Cmd/delete.pm »