ExtraFields.pm

filter: Statementstmt 100% 67 / 67 Branchbran 87.5% 14 / 16 Conditioncond 77.7% 7 / 9 MC/DCmcdc 33.3% 2 / 6 Subroutinesub 100% 17 / 17 Podpod 100% 9 / 9 totaltotal 93.5% 116 / 124 CC 13 SCAR 11.3
CC
13
Cov
96%
gen_fields_group
7.0
build_driver
4.1
method_name
2.0
CRAP 3.1
↑ Summary ExtraFields/Driver/HashGuts.pm »
1 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
2 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
3  
4 package Mixin::ExtraFields 0.140004;
5 # ABSTRACT: add extra stashes of data to your objects
6  
7 4 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
8 4 ▶use Params::SomeUtil ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9 4 ▶use String::RewritePrefix;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 #pod =head1 SYNOPSIS
12 #pod
13 #pod If you use the ExtraFields mixin in your class:
14 #pod
15 #pod package Corporate::WorkOrder;
16 #pod
17 #pod use Mixin::ExtraFields -fields => {
18 #pod id => 'workorder_id',
19 #pod moniker => 'note',
20 #pod driver => { HashGuts => { hash_key => '_notes' } }
21 #pod };
22 #pod
23 #pod ...your objects will then have methods for manipulating their extra fields:
24 #pod
25 #pod my $workorder = Corporate::WorkOrder->retrieve(1234);
26 #pod
27 #pod if ($workorder->note_exists('debug_next')) {
28 #pod warn $workorder->note_get('debug_next');
29 #pod $workorder->note_delete('debug_next');
30 #pod }
31 #pod
32 #pod if ($workorder->note_get('time_bomb')) {
33 #pod $workorder->note_delete_all;
34 #pod $workorder->note_set(
35 #pod last_explosion => time,
36 #pod explosion_cause => 'time bomb',
37 #pod );
38 #pod }
39 #pod
40 #pod =head1 DESCRIPTION
41 #pod
42 #pod Sometimes your well-defined object needs a way to tack on arbirary extra
43 #pod fields. This might be a set of session-specific ephemeral data, a stash of
44 #pod settings that need to be easy to grow over time, or any sort of name-and-value
45 #pod parameters. Adding more and more methods can be cumbersome, and may not be
46 #pod helpful if the names vary greatly. Accessing an object's guts directly is
47 #pod simple, but is difficult to control when subclassing, and can make altering
48 #pod your object's structure difficult.
49 #pod
50 #pod Mixin::ExtraFields provides a simple way to add an arbitrary number of stashes
51 #pod for named data. These data can be stored in the object, in a database, or
52 #pod anywhere else. The storage mechanism is abstracted away from the provided
53 #pod interface, so one storage mechanism can be easily swapped for another.
54 #pod Multiple ExtraFields stashes can be mixed into one class, using one or many
55 #pod storage mechanisms.
56 #pod
57 #pod =head1 MIXING IN
58 #pod
59 #pod To create a stash of extra fields, just C<use> Mixin::ExtraFields and import
60 #pod the C<fields> group like this:
61 #pod
62 #pod use Mixin::ExtraFields -fields => { driver => 'SomeDriver' };
63 #pod
64 #pod The only argument required for the group is C<driver>, which names the driver
65 #pod (storage mechanism) to use. For more information, see L</Specifying a Driver>,
66 #pod below.
67 #pod
68 #pod Other valid arguments are:
69 #pod
70 #pod id - the name of the method to call on objects to get their unique identifier
71 #pod default: id; an explicit undef will use each object's reference addr
72 #pod
73 #pod moniker - the name to use in forming mixed-in method names
74 #pod default: extra
75 #pod
76 #pod =head2 Specifying a Driver
77 #pod
78 #pod The C<driver> argument can be given as either a driver identifier or a
79 #pod reference to a hash of options. If given as a hash reference, one of the
80 #pod entries in the hash must be C<class>, giving the driver identifier for the
81 #pod driver.
82 #pod
83 #pod A driver identifier must be either:
84 #pod
85 #pod =over
86 #pod
87 #pod =item * an object of a class descended from the driver base class
88 #pod
89 #pod =item * a partial class name, to follow the driver base class name
90 #pod
91 #pod =item * a full class name, prepended with +
92 #pod
93 #pod =back
94 #pod
95 #pod The driver base class is provided by the C<L</driver_base_class>> method. In
96 #pod almost all cases, it will be C<Mixin::ExtraFields::Driver>.
97 #pod
98 #pod =head1 GENERATED METHODS
99 #pod
100 #pod The default implementation of Mixin::ExtraFields provides a number of methods
101 #pod for accessing the extras.
102 #pod
103 #pod Wherever "extra" appears in the following method names, the C<moniker> argument
104 #pod given to the C<fields> group will be used instead. For example, if the use
105 #pod statement looked like this:
106 #pod
107 #pod use Mixin::ExtraFields -fields => { moniker => 'info', driver => 'HashGuts' };
108 #pod
109 #pod ...then a method called C<exists_info> would be generated, rather than
110 #pod C<exists_extra>. The C<fields> group also respects renaming options documented
111 #pod in L<Sub::Exporter>.
112 #pod
113 #pod =head2 exists_extra
114 #pod
115 #pod if ($obj->exists_extra($name)) { ... }
116 #pod
117 #pod This method returns true if there is an entry in the extras for the given name.
118 #pod
119 #pod =head2 get_extra
120 #pod
121 #pod =head2 get_detailed_extra
122 #pod
123 #pod my $value = $obj->get_extra($name);
124 #pod
125 #pod my $value_hash = $obj->get_detailed_extra($name);
126 #pod
127 #pod These methods return the entry for the given name. If none exists, the method
128 #pod returns undef. The detailed version of this method will return a hashref
129 #pod describing all information available about the entry. While this information
130 #pod is driver-specific, it is required to have an entry for the key C<entry>,
131 #pod providing the value that would have been returned by C<get_extra>.
132 #pod
133 #pod =head2 get_all_extra
134 #pod
135 #pod =head2 get_all_detailed_extra
136 #pod
137 #pod my %extra = $obj->get_all_extra;
138 #pod
139 #pod my %extra_hash = $obj->get_all_detailed_extra;
140 #pod
141 #pod These methods return a list of name/value pairs. The values are in the same
142 #pod form as those returned by the get-by-name methods, above.
143 #pod
144 #pod =head2 get_all_extra_names
145 #pod
146 #pod my @names = $obj->get_all_extra_names;
147 #pod
148 #pod This method returns the names of all existing extras.
149 #pod
150 #pod =head2 set_extra
151 #pod
152 #pod $obj->set_extra($name => $value);
153 #pod
154 #pod This method sets the given extra. If no entry existed before, one is created.
155 #pod If one existed for this name, it is replaced.
156 #pod
157 #pod =head2 delete_extra
158 #pod
159 #pod $obj->delete_extra($name);
160 #pod
161 #pod This method deletes the named entry. After deletion, no entry will exist for
162 #pod that name.
163 #pod
164 #pod =head2 delete_all_extra
165 #pod
166 #pod $obj->delete_all_extra;
167 #pod
168 #pod This method deletes all entries for the object.
169 #pod
170 #pod =cut
171  
172 #pod =head1 SUBCLASSING
173 #pod
174 #pod Mixin::ExtraFields can be subclassed to produce different methods, provide
175 #pod different names, or behave differently in other ways. Subclassing
176 #pod Mixin::ExtraFields can produce many distinct and powerful tools.
177 #pod
178 #pod None of the generated methods, above, are implemented in Mixin::ExtraFields.
179 #pod The methods below are its actual methods, which work together to build and
180 #pod export the methods that are mixed in. These are the methods you should
181 #pod override when subclassing Mixin::ExtraFields.
182 #pod
183 #pod For information on writing drivers, see L<Mixin::ExtraFields::Driver>.
184 #pod
185 #pod =cut
186  
187 #pod =begin wishful_thinking
188 #pod
189 #pod Wouldn't that be super? Too bad that I can't defer the calling of this method
190 #pod until C<import> is called.
191 #pod
192 #pod =head2 default_group_name
193 #pod
194 #pod my $name = Mixin::ExtraFields->default_group_name;
195 #pod
196 #pod This method returns the name to be used as the exported group. It defaults to
197 #pod "fields". By overriding this to return, for example, "stuff," your module
198 #pod could be used as follows:
199 #pod
200 #pod use Mixin::ExtraFields::Subclass -stuff => { moniker => "things" };
201 #pod
202 #pod =end wishful_thinking
203 #pod
204 #pod =cut
205  
206 4 ▶use Sub::Exporter 0.972 -setup => {
Subroutine BEGIN: called CC=1 SCAR=0.0
207 groups => [ fields => \'gen_fields_group', ],
208 4 };
209  
210 #pod =head2 default_moniker
211 #pod
212 #pod This method returns the default moniker. The default default moniker defaults
213 #pod to the default "extra".
214 #pod
215 #pod =cut
216  
217 3 ▶sub default_moniker { 'extra' }
Subroutine default_moniker: called CC=1 SCAR=0.0
Pod documented
218  
219 #pod =head2 methods
220 #pod
221 #pod This method returns a list of base method names to construct and install.
222 #pod These method names will be transformed into the installed method names via
223 #pod C<L</method_name>>.
224 #pod
225 #pod my @methods = Mixin::ExtraFields->methods;
226 #pod
227 #pod =cut
228  
229 7 ▶sub methods {
Subroutine methods: called CC=1 SCAR=0.0
Pod documented
230 7 qw(
231 exists
232 get_detailed get_all_detailed
233 get get_all
234 get_all_names
235 set
236 delete delete_all
237 )
238 }
239  
240 #pod =head2 method_name
241 #pod
242 #pod my $method_name = Mixin::ExtraFields->method_name($method_base, $moniker);
243 #pod
244 #pod This method returns the method name that will be installed into the importing
245 #pod class. Its default behavior is to join the method base (which comes from the
246 #pod C<L</methods>> method) and the moniker with an underscore, more or less.
247 #pod
248 #pod =cut
249  
250 126 ▶sub method_name {
Subroutine method_name: called CC=2 SCAR=6.9
Pod documented
251 126 my ($self, $method, $moniker) = @_;
252  
253 126 ▶ return "get_all_$moniker\_names" if $method eq 'get_all_names';
Branch: 1 branch
BranchTrueFalseTotal
if $method eq "get_all_names" 14 112 126
254 112 return "$method\_$moniker";
255 }
256  
257 #pod =head2 driver_method_name
258 #pod
259 #pod This method returns the name of the driver method used to implement the given
260 #pod method name. This is primarily useful in the default implementation of
261 #pod MixinExtraFields, where there is a one-to-one correspondence between installed
262 #pod methods and driver methods.
263 #pod
264 #pod Changing this method could very easily cause incompatibility with standard
265 #pod driver classes, and should only be done by the wise, brave, or reckless.
266 #pod
267 #pod =cut
268  
269 63 ▶sub driver_method_name {
Subroutine driver_method_name: called CC=1 SCAR=0.0
Pod documented
270 63 my ($self, $method) = @_;
271 63 $self->method_name($method, 'extra');
272 }
273  
274 #pod =head2 gen_fields_group
275 #pod
276 #pod my $sub_href = Mixin::ExtraFields->gen_fields_group($name, \%arg, \%col);
277 #pod
278 #pod This method is a group generator, as used by L<Sub::Exporter> and described in
279 #pod its documentation. It is the method you are least likely to subclass.
280 #pod
281 #pod =cut
282  
283 9 ▶sub gen_fields_group {
Subroutine gen_fields_group: called CC=7 SCAR=19.5
Pod documented
284 9 my ($class, $name, $arg, $col) = @_;
285  
286 9 ▶ $arg->{driver} ||= $class->default_driver_arg;
Condition66%2/3
$arg->{"driver"} ||= $class->default_driver_arg
l!l&&r!l&&!r
810
MC/DC0%0/2
$arg->{"driver"} ||= $class->default_driver_arg
$arg->{"driver"} $class->default_driver_arg
Truth table66%2/3
A ||= B
A= $arg->{"driver"}B= $class->default_driver_arg
ABresult
1X1
011
000
287 8 my $driver = $class->build_driver($arg->{driver});
288  
289 7 my $id_method;
290 7 ▶ if (exists $arg->{id} and defined $arg->{id}) {
Branch: 2 branches
BranchTrueFalseTotal
if (exists $arg->{'id'} and defined $arg->{'id'}) { } 2 5 7
elsif (exists $arg->{'id'}) { } 1 4 5
Condition100%3/3
exists $arg->{"id"} and defined $arg->{"id"}
!ll&&!rl&&r
412
MC/DC100%2/2
exists $arg->{"id"} and defined $arg->{"id"}
exists $arg->{"id"} defined $arg->{"id"}
Truth table100%3/3
A and B
A= exists $arg->{"id"}B= defined $arg->{"id"}
ABresult
0X0
100
111
291 2 $id_method = $arg->{id};
292 } elsif (exists $arg->{id}) {
293 1 require Scalar::Util;
294 1 $id_method = \&Scalar::Util::refaddr;
295 } else {
296 4 $id_method = 'id';
297 }
298  
299 7 ▶ my $moniker = $arg->{moniker} || $class->default_moniker;
Condition66%2/3
$arg->{'moniker'} || $class->default_moniker
l!l&&r!l&&!r
430
MC/DC0%0/2
$arg->{'moniker'} || $class->default_moniker
$arg->{'moniker'} $class->default_moniker
Truth table66%2/3
A || B
A= $arg->{'moniker'}B= $class->default_moniker
ABresult
1X1
011
000
300  
301 7 my %method;
302 7 for my $method_name ($class->methods) {
303 63 my $install_method = $class->method_name($method_name, $moniker);
304  
305 63 $method{ $install_method } = $class->build_method(
306 $method_name,
307 {
308 id_method => \$id_method,
309 driver => \$driver,
310 moniker => \$moniker, # So that things can refer to one another
311 }
312 );
313 }
314  
315 7 return \%method;
316 }
317  
318 #pod =head2 build_method
319 #pod
320 #pod my $code = Mixin::ExtraFields->build_method($method_name, \%arg);
321 #pod
322 #pod This routine builds the requested method. It is passed a method name in the
323 #pod form returned by the C<methods> method and a hashref of the following data:
324 #pod
325 #pod id_method - the method to call on objects to get their unique id
326 #pod driver - the storage driver
327 #pod moniker - the moniker of the set of extras being built
328 #pod
329 #pod B<Note!> The values for the above arguments are references to the values you'd
330 #pod expect. That is, if the id method is "foo" you will be given an reference to
331 #pod the string foo. (This reduces the copies of common values that will be enclosed
332 #pod into generated code.)
333 #pod
334 #pod =cut
335  
336 63 ▶sub build_method {
Subroutine build_method: called CC=1 SCAR=0.0
Pod documented
337 63 my ($self, $method_name, $arg) = @_;
338  
339 # Remember that these are all passed in as references, to avoid unneeded
340 # copying. -- rjbs, 2006-12-07
341 63 my $id_method = $arg->{id_method};
342 63 my $driver = $arg->{driver};
343  
344 63 my $driver_method = $self->driver_method_name($method_name);
345  
346 54 ▶ return sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
347 54 my $object = shift;
348 54 my $id = $object->$$id_method;
349 54 ▶ Carp::confess "couldn't determine id for object" unless defined $id;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $id 1 53 54
350 53 $$driver->$driver_method($object, $id, @_);
351 63 };
352 }
353  
354 #pod =head2 default_driver_arg
355 #pod
356 #pod my $arg = Mixin::ExtraFields->default_driver_arg;
357 #pod
358 #pod This method a default value for the C<driver> argument to the fields group
359 #pod generator. By default, this method will croak if called.
360 #pod
361 #pod =cut
362  
363 1 ▶sub default_driver_arg {
Subroutine default_driver_arg: called CC=1 SCAR=0.0
Pod documented
364 1 my ($class) = shift;
365 1 Carp::croak "no driver supplied to $class";
366 }
367  
368 #pod =head2 build_driver
369 #pod
370 #pod my $driver = Mixin::ExtraFields->build_driver($arg);
371 #pod
372 #pod This method constructs and returns the driver object to be used by the
373 #pod generated methods. It is passed the C<driver> argument given in the importing
374 #pod code's C<use> statement.
375 #pod
376 #pod =cut
377  
378 8 ▶sub build_driver {
Subroutine build_driver: called CC=4 SCAR=14.0
Pod documented
379 8 my ($self, $arg) = @_;
380  
381 8 ▶ return $arg if Params::SomeUtil::_INSTANCE($arg, $self->driver_base_class);
Branch: 1 branch
BranchTrueFalseTotal
if &Params::SomeUtil::_INSTANCE($arg, scalar $self->driver_base_class) 0 8 8
382  
383 8 my ($driver_class, $driver_args) = $self->_driver_class_and_args($arg);
384  
385 8 ▶ Carp::croak("invalid class name for driver: $driver_class")
Branch: 1 branch
BranchTrueFalseTotal
unless &Params::SomeUtil::_CLASS($driver_class) 0 8 8
386 unless Params::SomeUtil::_CLASS($driver_class);
387  
388 8 ▶ eval "require $driver_class; 1" or Carp::croak $@;
Branch: 1 branch
BranchTrueFalseTotal
eval "require $driver_class; 1" or Carp::croak($@) 7 1 8
389  
390 7 my $driver = $driver_class->from_args($driver_args);
391 }
392  
393 8 ▶sub _driver_class_and_args {
Subroutine _driver_class_and_args: called CC=2 SCAR=6.9
394 8 my ($self, $arg) = @_;
395  
396 8 my $class;
397 8 ▶ if (ref $arg) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $arg) { } 3 5 8
398 3 $class = delete $arg->{class};
399 } else {
400 5 $class = $arg;
401 5 $arg = {};
402 }
403  
404 8 $class = String::RewritePrefix->rewrite(
405 {
406 '+' => '',
407 '=' => '',
408 '' => $self->driver_base_class . '::',
409 },
410 $class,
411 );
412  
413 8 return $class, $arg;
414 }
415  
416 #pod =head2 driver_base_class
417 #pod
418 #pod This is the name of the name of the class which drivers are expected to
419 #pod subclass. By default it returns C<Mixin::ExtraFields::Driver>.
420 #pod
421 #pod =cut
422  
423 16 ▶sub driver_base_class { 'Mixin::ExtraFields::Driver' }
Subroutine driver_base_class: called CC=1 SCAR=0.0
Pod documented
424  
425 #pod =head1 TODO
426 #pod
427 #pod =over
428 #pod
429 #pod =item * handle invocants without ids (classes) and drivers that don't need ids
430 #pod
431 #pod =back
432 #pod
433 #pod =cut
434  
435 4 1;
436  
437 __END__
↑ Summary ExtraFields/Driver/HashGuts.pm »