ExtraFields/Driver.pm

filter: Statementstmt 100% 35 / 35 Branchbran 100% 4 / 4 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 12 / 12 Podpod 100% 6 / 6 totaltotal 100% 57 / 57 CC 5 SCAR 4.1
CC
5
Cov
100%
BEGIN
2.0
get_extra
2.0
get_detailed_extra
2.0
CRAP 1.5
« ExtraFields/Driver/HashGuts.pm ↑ Summary
1  
2 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 package Mixin::ExtraFields::Driver 0.140004;
6 # ABSTRACT: a backend for extra field storage
7  
8 4 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9 4 ▶use Sub::Install ();
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 #pod =head1 SYNOPSIS
12 #pod
13 #pod This is really not something you'd use on your own, it's just used by
14 #pod Mixin::ExtraFields, but if you insist...
15 #pod
16 #pod my $driver = Mixin::ExtraFields::Driver::Phlogiston->from_args(\%arg);
17 #pod
18 #pod $driver->set($obj, $obj_id, flammable => "very!");
19 #pod
20 #pod =head1 DESCRIPTION
21 #pod
22 #pod Mixin::ExtraFields::Driver is a base class for drivers used by
23 #pod Mixin::ExtraFields -- hence the name. A driver is expected to store and
24 #pod retrieve data keyed to an object and a name or key. It can store this in any
25 #pod way it likes, and does not need to guarantee persistence across processes.
26 #pod
27 #pod =head1 SUBCLASSING
28 #pod
29 #pod All drivers must implement the four methods listed below. The base class has
30 #pod implementations of these methods which will die noisily (C<confess>-ing) when
31 #pod called.
32 #pod
33 #pod Almost all methods are passed the same data as their first two arguments:
34 #pod C<$object>, the object for which the driver is to find or alter data, and
35 #pod C<$id>, that object's unique id. While this may be slighly redundant, it keeps
36 #pod the id-finding call in one place.
37 #pod
38 #pod =head2 from_args
39 #pod
40 #pod my $driver = Mixin::ExtraFields::Driver::Subclass->from_args(\%arg);
41 #pod
42 #pod This method must return a driver object appropriate to the given args. It is
43 #pod not called C<new> because it need not return a new object for each call to it.
44 #pod Returning identical objects for identical configurations may be safe for some
45 #pod driver implementations, and it is expressly allowed.
46 #pod
47 #pod The arguments passed to this method are those given as the C<driver> option to
48 #pod the C<fields> import group in Mixin::ExtraFields, less the C<class> option.
49 #pod
50 #pod =head2 get_all_detailed_extra
51 #pod
52 #pod my %extra = $driver->get_all_detailed_extra($object, $id);
53 #pod
54 #pod This method must return all available information about all existing extra
55 #pod fields for the given object. It must be returned as a list of name/value
56 #pod pairs. The values must be references to hashes. Each hash must have an entry
57 #pod for the key C<value> giving the value for that name.
58 #pod
59 #pod =head2 set_extra
60 #pod
61 #pod $driver->set_extra($object, $id, $name, $value);
62 #pod
63 #pod This method must set the named extra to the given value.
64 #pod
65 #pod =head2 delete_extra
66 #pod
67 #pod $driver->delete_extra($object, $id, $name);
68 #pod
69 #pod This method must delete the named extra, causing it to cease to exist.
70 #pod
71 #pod =cut
72  
73 4 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
74 4 for my $name (qw(from_args get_all_detailed_extra set_extra delete_extra)) {
75 Sub::Install::install_sub({
76 as => $name,
77 4 ▶ code => sub { Carp::confess "method $name called but not implemented!" },
Subroutine __ANON__: called CC=1 SCAR=0.0
78 16 });
79 }
80 }
81  
82 #pod =head1 OPTIMIZING
83 #pod
84 #pod The methods below can all be implemented in terms of those above. If they are
85 #pod not provided by the subclass, basic implementations exist. These
86 #pod implementations may be less efficient than implementations crafted for the
87 #pod specifics of the storage engine behind the driver, so authors of driver
88 #pod subclasses should consider implementing these methods.
89 #pod
90 #pod =head2 get_all_extra
91 #pod
92 #pod my %extra = $driver->get_all_extra($object, $id);
93 #pod
94 #pod This method behaves like C<get_all_detailed_extra>, above, but provides the
95 #pod entry's value, not a detailed hashref, as the value for each entry.
96 #pod
97 #pod =cut
98  
99 2 ▶sub get_all_extra {
Subroutine get_all_extra: called CC=1 SCAR=0.0
Pod documented
100 2 my ($self, $object, $id) = @_;
101
102 2 my %extra = $self->get_all_detailed_extra($object, $id);
103 2 my @simple = map { $_ => $extra{$_}{value} } keys %extra;
104 }
105  
106 #pod =head2 get_extra
107 #pod
108 #pod =head2 get_detailed_extra
109 #pod
110 #pod my $value = $driver->get_extra($object, $id, $name);
111 #pod
112 #pod my $hash = $driver->get_detailed_extra($object, $id, $name);
113 #pod
114 #pod These methods return a single value requested by name, either as the value
115 #pod itself or a detailed hashref describing it.
116 #pod
117 #pod =cut
118  
119 3 ▶sub get_extra {
Subroutine get_extra: called CC=2 SCAR=6.9
Pod documented
120 3 my ($self, $object, $id, $name) = @_;
121
122 3 my $extra = $self->get_detailed_extra($object, $id, $name);
123 3 ▶ return $extra ? $extra->{value} : ();
Branch: 1 branch
BranchTrueFalseTotal
$extra ? : 1 2 3
124 }
125  
126 4 ▶sub get_detailed_extra {
Subroutine get_detailed_extra: called CC=2 SCAR=6.9
Pod documented
127 4 my ($self, $object, $id, $name) = @_;
128  
129 4 my %extra = $self->get_all_detailed_extra($object, $id);
130 4 ▶ return exists $extra{$name} ? $extra{$name} : ();
Branch: 1 branch
BranchTrueFalseTotal
exists $extra{$name} ? : 2 2 4
131 }
132  
133 #pod =head2 get_all_extra_names
134 #pod
135 #pod my @names = $driver->get_all_extra_names($object, $id);
136 #pod
137 #pod This method returns the names of all existing extras for the given object.
138 #pod
139 #pod =cut
140  
141 3 ▶sub get_all_extra_names {
Subroutine get_all_extra_names: called CC=1 SCAR=0.0
Pod documented
142 3 my ($self, $object, $id) = @_;
143 3 my %extra = $self->get_all_detailed_extra($object, $id);
144 3 return keys %extra;
145 }
146  
147 #pod =head2 exists_extra
148 #pod
149 #pod if ($driver->exists_extra($object, $id, $name)) { ... }
150 #pod
151 #pod This method returns true if an entry exists for the given name and false
152 #pod otherwise.
153 #pod
154 #pod =cut
155  
156 4 ▶sub exists_extra {
Subroutine exists_extra: called CC=1 SCAR=0.0
Pod documented
157 4 my ($self, $object, $id, $name) = @_;
158 4 my %extra = $self->get_all_detailed_extra($object, $id);
159  
160 4 return exists $extra{ $name };
161 }
162  
163 #pod =head2 delete_all_extra
164 #pod
165 #pod $driver->delete_all_extra($object, $id);
166 #pod
167 #pod This method deletes all extras for the object, as per the C<delete_extra>
168 #pod method.
169 #pod
170 #pod =cut
171  
172 1 ▶sub delete_all_extra {
Subroutine delete_all_extra: called CC=2 SCAR=6.9
Pod documented
173 1 my ($self, $object, $id) = @_;
174  
175 1 for my $name ($self->get_all_extra_names($object, $id)) {
176 1 $self->delete_extra($object, $id, $name);
177 }
178 }
179  
180 4 1;
181  
182 __END__
« ExtraFields/Driver/HashGuts.pm ↑ Summary