| 1 | package Catmandu::Store; | ||||||||||||||||||||
| 2 | |||||||||||||||||||||
| 3 | 15 | ▶ | use Catmandu::Sane; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 4 | |||||||||||||||||||||
| 5 | 15 | our $VERSION = '1.0201_02'; | |||||||||||||||||||
| 6 | |||||||||||||||||||||
| 7 | 15 | ▶ | use Hash::Util::FieldHash (); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 8 | 15 | ▶ | use Sub::Quote qw(quote_sub); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 9 | 15 | ▶ | use Moo::Role; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 10 | 15 | ▶ | use namespace::clean; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 11 | |||||||||||||||||||||
| 12 | 15 | with 'Catmandu::Logger'; | |||||||||||||||||||
| 13 | |||||||||||||||||||||
| 14 | 27 | ▶ | has bag_class => (is => 'ro', default => sub {ref($_[0]) . '::Bag'},); | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 15 | |||||||||||||||||||||
| 16 | 28 | ▶ | has default_bag => (is => 'ro', default => sub {'data'},); | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 17 | |||||||||||||||||||||
| 18 | 21 | ▶ | has bags => (is => 'ro', default => sub {+{}},); | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 19 | |||||||||||||||||||||
| 20 | 18 | ▶ | has key_prefix => (is => 'lazy', default => sub {'_'},); | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 21 | |||||||||||||||||||||
| 22 | sub key_for { | ||||||||||||||||||||
| 23 | 24 | ▶ | $_[0]->key_prefix . $_[1]; | ||||||||||||||||||
|
Subroutine
key_for: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 24 | } | ||||||||||||||||||||
| 25 | |||||||||||||||||||||
| 26 | { | ||||||||||||||||||||
| 27 | 15 | Hash::Util::FieldHash::fieldhash my %bag_instances; | |||||||||||||||||||
| 28 | |||||||||||||||||||||
| 29 | sub bag { | ||||||||||||||||||||
| 30 | 111 | ▶ | my $self = shift; | ||||||||||||||||||
|
Subroutine
bag: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||
| 31 | 111 | ▶ | my $name = shift // $self->default_bag; | ||||||||||||||||||
|
Condition66%2/3
shift() // $self->default_bag
MC/DC0%0/2
shift() // $self->default_bag
shift()
$self->default_bag
Truth table66%2/3
A // B
A= shift()B= $self->default_bag
| |||||||||||||||||||||
| 32 | 111 | ▶ | $bag_instances{$self}{$name} ||= do { | ||||||||||||||||||
|
Condition66%2/3
$bag_instances{$self}{$name} ||= do {
MC/DC0%0/2
$bag_instances{$self}{$name} ||= do {
my $pkg = $self->bag_class;
if (my $options = $self->bags->{$name}) {
$options = {%$options};
if (my $plugins = delete $options->{"plugins"}) {
$pkg = $pkg->with_plugins($plugins);
};
$pkg->new(%$options, "store", $self, "name", $name);
}
else {
$pkg->new("store", $self, "name", $name);
}
}
$bag_instances{$self}{$name}
do {
my $pkg = $self->bag_class;
if (my $options = $self->bags->{$name}) {
$options = {%$options};
if (my $plugins = delete $options->{"plugins"}) {
$pkg = $pkg->with_plugins($plugins);
};
$pkg->new(%$options, "store", $self, "name", $name);
}
else {
$pkg->new("store", $self, "name", $name);
}
}
Truth table66%2/3
A ||= B
A= $bag_instances{$self}{$name}B= do {
my $pkg = $self->bag_class;
if (my $options = $self->bags->{$name}) {
$options = {%$options};
if (my $plugins = delete $options->{"plugins"}) {
$pkg = $pkg->with_plugins($plugins);
};
$pkg->new(%$options, "store", $self, "name", $name);
}
else {
$pkg->new("store", $self, "name", $name);
}
}
| |||||||||||||||||||||
| 33 | 24 | my $pkg = $self->bag_class; | |||||||||||||||||||
| 34 | 24 | ▶ | if (my $options = $self->bags->{$name}) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 35 | 8 | $options = {%$options}; | |||||||||||||||||||
| 36 | 8 | ▶ | if (my $plugins = delete $options->{plugins}) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 37 | 6 | $pkg = $pkg->with_plugins($plugins); | |||||||||||||||||||
| 38 | } | ||||||||||||||||||||
| 39 | 8 | $pkg->new(%$options, store => $self, name => $name); | |||||||||||||||||||
| 40 | } | ||||||||||||||||||||
| 41 | else { | ||||||||||||||||||||
| 42 | 16 | $pkg->new(store => $self, name => $name); | |||||||||||||||||||
| 43 | } | ||||||||||||||||||||
| 44 | }; | ||||||||||||||||||||
| 45 | } | ||||||||||||||||||||
| 46 | } | ||||||||||||||||||||
| 47 | |||||||||||||||||||||
| 48 | # forward methods to default bag | ||||||||||||||||||||
| 49 | { | ||||||||||||||||||||
| 50 | 15 | my $pkg = __PACKAGE__; | |||||||||||||||||||
| 51 | 15 | my @delegate = ( | |||||||||||||||||||
| 52 | |||||||||||||||||||||
| 53 | # Catmandu::Iterable methods | ||||||||||||||||||||
| 54 | qw(to_array count slice each tap any many all map reduce first rest | ||||||||||||||||||||
| 55 | take pluck invoke contains includes group interleave max min | ||||||||||||||||||||
| 56 | benchmark), | ||||||||||||||||||||
| 57 | |||||||||||||||||||||
| 58 | # Catmandu::Addable methods | ||||||||||||||||||||
| 59 | qw(add add_many commit), | ||||||||||||||||||||
| 60 | |||||||||||||||||||||
| 61 | # Catmandu::Bag methods | ||||||||||||||||||||
| 62 | qw(get delete delete_all get_or_add to_hash), | ||||||||||||||||||||
| 63 | ); | ||||||||||||||||||||
| 64 | |||||||||||||||||||||
| 65 | 15 | for my $sub (@delegate) { | |||||||||||||||||||
| 66 | 450 | quote_sub("${pkg}::${sub}", | |||||||||||||||||||
| 67 | "my \$self = shift; \$self->bag->${sub}(\@_)"); | ||||||||||||||||||||
| 68 | } | ||||||||||||||||||||
| 69 | } | ||||||||||||||||||||
| 70 | |||||||||||||||||||||
| 71 | 15 | 1; | |||||||||||||||||||
| 72 | |||||||||||||||||||||
| 73 | __END__ | ||||||||||||||||||||
| 74 | |||||||||||||||||||||
| 75 | =pod | ||||||||||||||||||||
| 76 | |||||||||||||||||||||
| 77 | =head1 NAME | ||||||||||||||||||||
| 78 | |||||||||||||||||||||
| 79 | Catmandu::Store - Namespace for packages that can make data persistent | ||||||||||||||||||||
| 80 | |||||||||||||||||||||
| 81 | =head1 SYNOPSIS | ||||||||||||||||||||
| 82 | |||||||||||||||||||||
| 83 | # From the command line | ||||||||||||||||||||
| 84 | |||||||||||||||||||||
| 85 | $ catmandu import JSON into MongoDB --database_name 'bibliography' < data.json | ||||||||||||||||||||
| 86 | |||||||||||||||||||||
| 87 | $ catmandu export MongoDB --database_name 'bibliography' to YAML | ||||||||||||||||||||
| 88 | $ catmandu export MongoDB --database_name 'bibliography' --query '{"PublicationYear": "1937"}' | ||||||||||||||||||||
| 89 | $ catmandu count MongoDB --database_name 'bibliography' --query '{"PublicationYear": "1937"}' | ||||||||||||||||||||
| 90 | |||||||||||||||||||||
| 91 | # From Perl | ||||||||||||||||||||
| 92 | use Catmandu; | ||||||||||||||||||||
| 93 | |||||||||||||||||||||
| 94 | my $store = Catmandu->store('MongoDB',database_name => 'bibliography'); | ||||||||||||||||||||
| 95 | |||||||||||||||||||||
| 96 | my $obj1 = $store->bag->add({ name => 'Patrick' }); | ||||||||||||||||||||
| 97 | |||||||||||||||||||||
| 98 | printf "obj1 stored as %s\n" , $obj1->{_id}; | ||||||||||||||||||||
| 99 | |||||||||||||||||||||
| 100 | # Force an id in the store | ||||||||||||||||||||
| 101 | my $obj2 = $store->bag->add({ _id => 'test123' , name => 'Nicolas' }); | ||||||||||||||||||||
| 102 | |||||||||||||||||||||
| 103 | my $obj3 = $store->bag->get('test123'); | ||||||||||||||||||||
| 104 | |||||||||||||||||||||
| 105 | $store->bag->delete('test123'); | ||||||||||||||||||||
| 106 | |||||||||||||||||||||
| 107 | $store->bag->delete_all; | ||||||||||||||||||||
| 108 | |||||||||||||||||||||
| 109 | # Some stores can be searched | ||||||||||||||||||||
| 110 | my $hits = $store->bag->search(query => 'name:Patrick'); | ||||||||||||||||||||
| 111 | |||||||||||||||||||||
| 112 | =head1 DESCRIPTION | ||||||||||||||||||||
| 113 | |||||||||||||||||||||
| 114 | A Catmandu::Store is a stub for Perl packages that can store data into | ||||||||||||||||||||
| 115 | databases or search engines. The database as a whole is called a 'store'. | ||||||||||||||||||||
| 116 | Databases also have compartments (e.g. tables) called L<Catmandu::Bag>-s. | ||||||||||||||||||||
| 117 | Some stores can be searched using L<Catmandu::Searchable> methods. | ||||||||||||||||||||
| 118 | |||||||||||||||||||||
| 119 | =head1 CONFIGURATION | ||||||||||||||||||||
| 120 | |||||||||||||||||||||
| 121 | =over | ||||||||||||||||||||
| 122 | |||||||||||||||||||||
| 123 | =item default_bag | ||||||||||||||||||||
| 124 | |||||||||||||||||||||
| 125 | The name of the bag to use if no explicit bag is given. Default is 'data'. | ||||||||||||||||||||
| 126 | |||||||||||||||||||||
| 127 | my $store = Catmandu::Store::MyDB->new(default_bag => 'stuff'); | ||||||||||||||||||||
| 128 | # this will return the stuff bag | ||||||||||||||||||||
| 129 | my $bag = $store->bag; | ||||||||||||||||||||
| 130 | |||||||||||||||||||||
| 131 | =item bags | ||||||||||||||||||||
| 132 | |||||||||||||||||||||
| 133 | Specify configuration for individual bags. | ||||||||||||||||||||
| 134 | |||||||||||||||||||||
| 135 | my $store = Catmandu::Store::Hash->new( | ||||||||||||||||||||
| 136 | bags => {stuff => {plugins => ['Datestamps']}}); | ||||||||||||||||||||
| 137 | # this bag will use the L<Catmandu::Plugin::Datestamps> role | ||||||||||||||||||||
| 138 | $store->bag('stuff') | ||||||||||||||||||||
| 139 | # this bag won't | ||||||||||||||||||||
| 140 | $store->bag('otherbag') | ||||||||||||||||||||
| 141 | |||||||||||||||||||||
| 142 | =item bag_class | ||||||||||||||||||||
| 143 | |||||||||||||||||||||
| 144 | An optional custom class to use for bags. Default is C<Bag> in the store's | ||||||||||||||||||||
| 145 | namespace. This class should consume the L<Catmandu::Bag> role. | ||||||||||||||||||||
| 146 | |||||||||||||||||||||
| 147 | # this will use the Catmandu::Store::MyDB::Bag class for bags | ||||||||||||||||||||
| 148 | Catmandu::Store::MyDB->new() | ||||||||||||||||||||
| 149 | # this will use MyBag | ||||||||||||||||||||
| 150 | Catmandu::Store::MyDB->new(bag_class => 'MyBag') | ||||||||||||||||||||
| 151 | |||||||||||||||||||||
| 152 | =item key_prefix | ||||||||||||||||||||
| 153 | |||||||||||||||||||||
| 154 | Use a custom prefix to mark the reserved or special keys that the store uses. | ||||||||||||||||||||
| 155 | By default an underscore gets prependend. The only special key in a normal | ||||||||||||||||||||
| 156 | store is '_id'. L<Catmandu::Plugin::Versioning> will also use '_version'. Other | ||||||||||||||||||||
| 157 | plugins or stores may add their own special keys. | ||||||||||||||||||||
| 158 | |||||||||||||||||||||
| 159 | # this store will use the my_id key to hold id's | ||||||||||||||||||||
| 160 | Catmandu::Store::MyDB->new(key_prefix => 'my_') | ||||||||||||||||||||
| 161 | |||||||||||||||||||||
| 162 | =back | ||||||||||||||||||||
| 163 | |||||||||||||||||||||
| 164 | =head1 METHODS | ||||||||||||||||||||
| 165 | |||||||||||||||||||||
| 166 | =head2 bag($name) | ||||||||||||||||||||
| 167 | |||||||||||||||||||||
| 168 | Create or retieve a bag with name C<$name>. Returns a L<Catmandu::Bag>. | ||||||||||||||||||||
| 169 | |||||||||||||||||||||
| 170 | =head2 key_for($key) | ||||||||||||||||||||
| 171 | |||||||||||||||||||||
| 172 | Helper method that applies C<key_prefix> to the C<$key> given. | ||||||||||||||||||||
| 173 | |||||||||||||||||||||
| 174 | =head2 log | ||||||||||||||||||||
| 175 | |||||||||||||||||||||
| 176 | Return the current logger. Can be used when creating your own Stores. | ||||||||||||||||||||
| 177 | |||||||||||||||||||||
| 178 | E.g. | ||||||||||||||||||||
| 179 | |||||||||||||||||||||
| 180 | package Catmandu::Store::Hash; | ||||||||||||||||||||
| 181 | |||||||||||||||||||||
| 182 | ... | ||||||||||||||||||||
| 183 | |||||||||||||||||||||
| 184 | sub generator { | ||||||||||||||||||||
| 185 | my ($self) = @_; | ||||||||||||||||||||
| 186 | |||||||||||||||||||||
| 187 | $self->log->debug("generating record"); | ||||||||||||||||||||
| 188 | ... | ||||||||||||||||||||
| 189 | } | ||||||||||||||||||||
| 190 | |||||||||||||||||||||
| 191 | See also: L<Catmandu> for activating the logger in your main code. | ||||||||||||||||||||
| 192 | |||||||||||||||||||||
| 193 | =head1 SEE ALSO | ||||||||||||||||||||
| 194 | |||||||||||||||||||||
| 195 | L<Catmandu::Bag>, L<Catmandu::Searchable> | ||||||||||||||||||||
| 196 | |||||||||||||||||||||
| 197 | =cut | ||||||||||||||||||||