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.140003
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

PERL VERSION

58       This library should run on perls released even a long time ago.  It
59       should work on any version of perl released in the last five years.
60
61       Although it may work on older versions of perl, no guarantee is made
62       that the minimum required version will not be increased.  The version
63       may be increased for any reason, and there is no promise that patches
64       will be accepted to lower the minimum required perl.
65

MIXING IN

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

GENERATED METHODS

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

SUBCLASSING

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

TODO

249       •   handle invocants without ids (classes) and drivers that don't need
250           ids
251

AUTHOR

253       Ricardo Signes <cpan@semiotic.systems>
254

CONTRIBUTORS

256       •   Ricardo SIGNES <rjbs@codesimply.com>
257
258       •   Ricardo Signes <rjbs@semiotic.systems>
259
261       This software is copyright (c) 2022 by Ricardo Signes.
262
263       This is free software; you can redistribute it and/or modify it under
264       the same terms as the Perl 5 programming language system itself.
265
266
267
268perl v5.36.0                      2023-01-20             Mixin::ExtraFields(3)
Impressum