1Mixin::ExtraFields(3) User Contributed Perl DocumentationMixin::ExtraFields(3)
2
3
4

NAME

6       Mixin::ExtraFields - add extra stashes of data to your objects
7

VERSION

9       version 0.140002
10

SYNOPSIS

12       If you use the ExtraFields mixin in your class:
13
14         package Corporate::WorkOrder;
15
16         use Mixin::ExtraFields -fields => {
17           id      => 'workorder_id',
18           moniker => 'note',
19           driver  => { HashGuts => { hash_key => '_notes' } }
20         };
21
22       ...your objects will then have methods for manipulating their extra
23       fields:
24
25         my $workorder = Corporate::WorkOrder->retrieve(1234);
26
27         if ($workorder->note_exists('debug_next')) {
28           warn $workorder->note_get('debug_next');
29           $workorder->note_delete('debug_next');
30         }
31
32         if ($workorder->note_get('time_bomb')) {
33           $workorder->note_delete_all;
34           $workorder->note_set(
35             last_explosion  => time,
36             explosion_cause => 'time bomb',
37           );
38         }
39

DESCRIPTION

41       Sometimes your well-defined object needs a way to tack on arbirary
42       extra fields.  This might be a set of session-specific ephemeral data,
43       a stash of settings that need to be easy to grow over time, or any sort
44       of name-and-value parameters.  Adding more and more methods can be
45       cumbersome, and may not be helpful if the names vary greatly.
46       Accessing an object's guts directly is simple, but is difficult to
47       control when subclassing, and can make altering your object's structure
48       difficult.
49
50       Mixin::ExtraFields provides a simple way to add an arbitrary number of
51       stashes for named data.  These data can be stored in the object, in a
52       database, or anywhere else.  The storage mechanism is abstracted away
53       from the provided interface, so one storage mechanism can be easily
54       swapped for another.  Multiple ExtraFields stashes can be mixed into
55       one class, using one or many storage mechanisms.
56

MIXING IN

58       To create a stash of extra fields, just "use" Mixin::ExtraFields and
59       import the "fields" group like this:
60
61         use Mixin::ExtraFields -fields => { driver => 'SomeDriver' };
62
63       The only argument required for the group is "driver", which names the
64       driver (storage mechanism) to use.  For more information, see
65       "Specifying a Driver", below.
66
67       Other valid arguments are:
68
69         id - the name of the method to call on objects to get their unique identifier
70              default: id; an explicit undef will use each object's reference addr
71
72         moniker - the name to use in forming mixed-in method names
73                   default: extra
74
75   Specifying a Driver
76       The "driver" argument can be given as either a driver identifier or a
77       reference to a hash of options.  If given as a hash reference, one of
78       the entries in the hash must be "class", giving the driver identifier
79       for the driver.
80
81       A driver identifier must be either:
82
83       ·   an object of a class descended from the driver base class
84
85       ·   a partial class name, to follow the driver base class name
86
87       ·   a full class name, prepended with +
88
89       The driver base class is provided by the "driver_base_class" method.
90       In almost all cases, it will be "Mixin::ExtraFields::Driver".
91

GENERATED METHODS

93       The default implementation of Mixin::ExtraFields provides a number of
94       methods for accessing the extras.
95
96       Wherever "extra" appears in the following method names, the "moniker"
97       argument given to the "fields" group will be used instead.  For
98       example, if the use statement looked like this:
99
100        use Mixin::ExtraFields -fields => { moniker => 'info', driver => 'HashGuts' };
101
102       ...then a method called "exists_info" would be generated, rather than
103       "exists_extra".  The "fields" group also respects renaming options
104       documented in Sub::Exporter.
105
106   exists_extra
107         if ($obj->exists_extra($name)) { ... }
108
109       This method returns true if there is an entry in the extras for the
110       given name.
111
112   get_extra
113   get_detailed_extra
114         my $value = $obj->get_extra($name);
115
116         my $value_hash = $obj->get_detailed_extra($name);
117
118       These methods return the entry for the given name.  If none exists, the
119       method returns undef.  The detailed version of this method will return
120       a hashref describing all information available about the entry.  While
121       this information is driver-specific, it is required to have an entry
122       for the key "entry", providing the value that would have been returned
123       by "get_extra".
124
125   get_all_extra
126   get_all_detailed_extra
127         my %extra = $obj->get_all_extra;
128
129         my %extra_hash = $obj->get_all_detailed_extra;
130
131       These methods return a list of name/value pairs.  The values are in the
132       same form as those returned by the get-by-name methods, above.
133
134   get_all_extra_names
135         my @names = $obj->get_all_extra_names;
136
137       This method returns the names of all existing extras.
138
139   set_extra
140         $obj->set_extra($name => $value);
141
142       This method sets the given extra.  If no entry existed before, one is
143       created.  If one existed for this name, it is replaced.
144
145   delete_extra
146         $obj->delete_extra($name);
147
148       This method deletes the named entry.  After deletion, no entry will
149       exist for that name.
150
151   delete_all_extra
152         $obj->delete_all_extra;
153
154       This method deletes all entries for the object.
155

SUBCLASSING

157       Mixin::ExtraFields can be subclassed to produce different methods,
158       provide different names, or behave differently in other ways.
159       Subclassing Mixin::ExtraFields can produce many distinct and powerful
160       tools.
161
162       None of the generated methods, above, are implemented in
163       Mixin::ExtraFields.  The methods below are its actual methods, which
164       work together to build and export the methods that are mixed in.  These
165       are the methods you should override when subclassing
166       Mixin::ExtraFields.
167
168       For information on writing drivers, see Mixin::ExtraFields::Driver.
169
170   default_moniker
171       This method returns the default moniker.  The default default moniker
172       defaults to the default "extra".
173
174   methods
175       This method returns a list of base method names to construct and
176       install.  These method names will be transformed into the installed
177       method names via "method_name".
178
179         my @methods = Mixin::ExtraFields->methods;
180
181   method_name
182         my $method_name = Mixin::ExtraFields->method_name($method_base, $moniker);
183
184       This method returns the method name that will be installed into the
185       importing class.  Its default behavior is to join the method base
186       (which comes from the "methods" method) and the moniker with an
187       underscore, more or less.
188
189   driver_method_name
190       This method returns the name of the driver method used to implement the
191       given method name.  This is primarily useful in the default
192       implementation of MixinExtraFields, where there is a one-to-one
193       correspondence between installed methods and driver methods.
194
195       Changing this method could very easily cause incompatibility with
196       standard driver classes, and should only be done by the wise, brave, or
197       reckless.
198
199   gen_fields_group
200         my $sub_href = Mixin::ExtraFields->gen_fields_group($name, \%arg, \%col);
201
202       This method is a group generator, as used by Sub::Exporter and
203       described in its documentation.  It is the method you are least likely
204       to subclass.
205
206   build_method
207         my $code = Mixin::ExtraFields->build_method($method_name, \%arg);
208
209       This routine builds the requested method.  It is passed a method name
210       in the form returned by the "methods" method and a hashref of the
211       following data:
212
213         id_method - the method to call on objects to get their unique id
214         driver    - the storage driver
215         moniker   - the moniker of the set of extras being built
216
217       Note!  The values for the above arguments are references to the values
218       you'd expect.  That is, if the id method is "foo" you will be given an
219       reference to the string foo.  (This reduces the copies of common values
220       that will be enclosed into generated code.)
221
222   default_driver_arg
223         my $arg = Mixin::ExtraFields->default_driver_arg;
224
225       This method a default value for the "driver" argument to the fields
226       group generator.  By default, this method will croak if called.
227
228   build_driver
229         my $driver = Mixin::ExtraFields->build_driver($arg);
230
231       This method constructs and returns the driver object to be used by the
232       generated methods.  It is passed the "driver" argument given in the
233       importing code's "use" statement.
234
235   driver_base_class
236       This is the name of the name of the class which drivers are expected to
237       subclass.  By default it returns "Mixin::ExtraFields::Driver".
238

TODO

240       ·   handle invocants without ids (classes) and drivers that don't need
241           ids
242

AUTHOR

244       Ricardo Signes <rjbs@cpan.org>
245
247       This software is copyright (c) 2013 by Ricardo Signes.
248
249       This is free software; you can redistribute it and/or modify it under
250       the same terms as the Perl 5 programming language system itself.
251
252
253
254perl v5.28.1                      2013-10-03             Mixin::ExtraFields(3)
Impressum