File Coverage

blib/lib/Catmandu/Bag.pm
Criterion Covered Total %
statement 39 39 100.0
branch 2 2 100.0
condition 2 3 66.6
subroutine 15 15 100.0
pod 3 5 60.0
total 61 64 95.3


line stmt bran cond sub pod time code
1              
2             use Catmandu::Sane;
3 20     20   15734  
  20         40  
  20         121  
4             our $VERSION = '1.2018';
5              
6             use Catmandu::Util qw(:check is_string require_package now);
7 20     20   133 use Catmandu::Bag::IdGenerator::UUID;
  20         87  
  20         5263  
8 20     20   7641 use Moo::Role;
  20         50  
  20         685  
9 20     20   129 use MooX::Aliases;
  20         32  
  20         69  
10 20     20   15564 use namespace::clean;
  20         53617  
  20         112  
11 20     20   7204  
  20         38  
  20         172  
12             with 'Catmandu::Logger';
13             with 'Catmandu::Pluggable';
14             with 'Catmandu::Iterable';
15             with 'Catmandu::Addable';
16              
17             requires 'get';
18             requires 'delete';
19             requires 'delete_all';
20              
21             has store => (is => 'ro', required => 1);
22             has name => (is => 'ro', required => 1);
23             has id_key => (is => 'lazy', alias => 'id_field');
24             has id_generator => (
25             is => 'lazy',
26             coerce => sub {
27             if (is_string($_[0])) {
28             require_package($_[0], 'Catmandu::Bag::IdGenerator')->new;
29             }
30             else {
31             $_[0];
32             }
33             },
34             );
35              
36             $_[0]->store->id_key;
37             }
38 30     30   818  
39             state $uuid = Catmandu::Bag::IdGenerator::UUID->new;
40             }
41              
42 4     4   97 before get => sub {
43             check_value($_[1]);
44             };
45              
46             before add => sub {
47             my ($self, $data) = @_;
48             check_hash_ref($data);
49             check_value($data->{$self->id_key} //= $self->generate_id($data));
50             };
51              
52             before delete => sub {
53             check_value($_[1]);
54             };
55              
56             around delete_all => sub {
57             my ($orig, $self) = @_;
58             $orig->($self);
59             return;
60             };
61              
62             my ($self) = @_;
63             $self->id_generator->generate($self);
64             }
65              
66 12     12 0 2319 my ($self, $id) = @_;
67 12         175 defined $self->get($id) ? 1 : 0;
68             }
69              
70             my ($self, $id, $data) = @_;
71 2     2 1 1134 check_value($id);
72 2 100       42 check_hash_ref($data);
73             $self->get($id) // do {
74             $data->{$self->id_key} = $id;
75             $self->add($data);
76 3     3 1 20 };
77 3         13 }
78 3         408  
79 3   66     396 my ($self) = @_;
80 1         18 $self->reduce(
81 1         19 {},
82             sub {
83             my ($hash, $data) = @_;
84             $hash->{$data->{$self->id_key}} = $data;
85             $hash;
86 1     1 0 3 }
87             );
88             }
89              
90 1     1   3 my ($self, $key, $format) = @_;
91 1         21 $self->add_many($self->tap(sub {$_[0]->{$key} = now($format)}));
92 1         10 $self->commit;
93             }
94 1         12  
95             1;
96              
97              
98 2     2 1 19 =pod
99 2     1   19  
  1         6  
100 2         57 =head1 NAME
101              
102             Catmandu::Bag - A Catmandu::Store compartment to persist data
103              
104             =head1 SYNOPSIS
105              
106             my $store = Catmandu::Store::DBI->new(data_source => 'DBI:mysql:database=test');
107              
108             my $store = Catmandu::Store::DBI->new(
109             data_source => 'DBI:mysql:database=test',
110             bags => { journals => {
111             fix => [ ... ] ,
112             autocommit => 1 ,
113             plugins => [ ... ] ,
114             id_generator => Catmandu::IdGenerator::UUID->new ,
115             }
116             },
117             bag_class => Catmandu::Bag->with_plugins('Datestamps')
118             );
119              
120             # Use the default bag...
121             my $bag = $store->bag;
122              
123             # Or a named bag...
124             my $bag = $store->bag('journals');
125              
126             # Every bag is an iterator...
127             $bag->each(sub { ... });
128             $bag->take(10)->each(sub { ... });
129              
130             $bag->add($hash);
131             $bag->add_many($iterator);
132             $bag->add_many([ $hash, $hash , ...]);
133              
134             # Commit changes...
135             $bag->commit;
136              
137             if ($bag->exists($id)) {
138             # ...
139             }
140              
141             my $obj = $bag->get($id);
142             $bag->delete($id);
143              
144             $bag->delete_all;
145              
146             =head1 CONFIGURATION
147              
148             =over
149              
150             =item fix
151              
152             Contains an array of fixes (or Fix files) to be applied before importing data into the bag.
153              
154             =item plugins
155              
156             An array of Catmandu::Pluggable to apply to the bag items.
157              
158             =item autocommit
159              
160             When set to a true value an commit automatically gets executed when the bag
161             goes out of scope.
162              
163             =item id_generator
164              
165             A L<Catmandu::IdGenerator> or name of an IdGenerator class.
166             By default L<Catmandu::IdGenerator::UUID> is used.
167              
168             =item id_key
169              
170             Use a custom key to hold id's in this bag. See L<Catmandu::Store> for the
171             default or store wide value. Also aliased as C<id_field>.
172              
173             =back
174              
175             =head1 METHODS
176              
177             =head2 add($hash)
178              
179             Add a hash to the bag or updates an existing hash by using its '_id' key. Returns
180             the stored hash on success or undef on failure.
181              
182             =head2 add_many($array)
183              
184             =head2 add_many($iterator)
185              
186             Add or update one or more items to the bag.
187              
188             =head2 get($id)
189              
190             Retrieves the item with identifier $id from the bag.
191              
192             =head2 exists($id)
193              
194             Returns C<1> if the item with identifier $id exists in the bag.
195              
196             =head2 get_or_add($id, $hash)
197              
198             Retrieves the item with identifier $id from the store or adds C<$hash> with _id
199             C<$id> if it's not found.
200              
201             =head2 delete($id)
202              
203             Deletes the item with C<$id> from the bag.
204              
205             =head2 delete_all
206              
207             Clear the bag.
208              
209             =head2 touch($key, $format)
210              
211             Add the current datetime to each record.
212              
213             $bag->touch('date_updated', 'iso_date_time');
214              
215             See L<Catmandu::Util::now> for possible format values.
216              
217             =head2 commit
218              
219             Commit changes.
220              
221             =head2 log
222              
223             Return the current logger.
224              
225             =head1 CLASS METHODS
226              
227             =head2 with_plugins($plugin)
228              
229             =head2 with_plugins(\@plugins)
230              
231             Plugins are a kind of fixes that should be available for each bag. E.g. the Datestamps plugin will
232             automatically store into each bag item the fields 'date_updated' and 'date_created'. The with_plugins
233             accept one or an array of plugin classnames and returns a subclass of the Bag with the plugin
234             methods implemented.
235              
236             =head1 SEE ALSO
237              
238             L<Catmandu::Iterable>, L<Catmandu::Searchable>, L<Catmandu::Fix>, L<Catmandu::Pluggable>
239              
240             =cut