1Mixin::ExtraFields(3) User Contributed Perl DocumentationMixin::ExtraFields(3)
2
6 Mixin::ExtraFields - add extra stashes of data to your objects
7
9 version 0.140003
10
12 If you use the ExtraFields mixin in your class:
13 package Corporate::WorkOrder;
15 use Mixin::ExtraFields -fields => {
17 id => 'workorder_id',
18 moniker => 'note',
19 driver => { HashGuts => { hash_key => '_notes' } }
20 };
21 ...your objects will then have methods for manipulating their extra
23 fields:
24 my $workorder = Corporate::WorkOrder->retrieve(1234);
26 if ($workorder->note_exists('debug_next')) {
28 warn $workorder->note_get('debug_next');
29 $workorder->note_delete('debug_next');
30 }
31 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
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 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
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 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
67 To create a stash of extra fields, just "use" Mixin::ExtraFields and
68 import the "fields" group like this:
69 use Mixin::ExtraFields -fields => { driver => 'SomeDriver' };
71 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 Other valid arguments are:
77 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 moniker - the name to use in forming mixed-in method names
82 default: extra
83 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 A driver identifier must be either:
91 • an object of a class descended from the driver base class
93 • a partial class name, to follow the driver base class name
95 • a full class name, prepended with +
97 The driver base class is provided by the "driver_base_class" method.
99 In almost all cases, it will be "Mixin::ExtraFields::Driver".
100
102 The default implementation of Mixin::ExtraFields provides a number of
103 methods for accessing the extras.
104 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 use Mixin::ExtraFields -fields => { moniker => 'info', driver => 'HashGuts' };
110 ...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 exists_extra
116 if ($obj->exists_extra($name)) { ... }
117 This method returns true if there is an entry in the extras for the
119 given name.
120 get_extra
122 get_detailed_extra
123 my $value = $obj->get_extra($name);
124 my $value_hash = $obj->get_detailed_extra($name);
126 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 get_all_extra
135 get_all_detailed_extra
136 my %extra = $obj->get_all_extra;
137 my %extra_hash = $obj->get_all_detailed_extra;
139 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 get_all_extra_names
144 my @names = $obj->get_all_extra_names;
145 This method returns the names of all existing extras.
147 set_extra
149 $obj->set_extra($name => $value);
150 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 delete_extra
155 $obj->delete_extra($name);
156 This method deletes the named entry. After deletion, no entry will
158 exist for that name.
159 delete_all_extra
161 $obj->delete_all_extra;
162 This method deletes all entries for the object.
164
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 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 For information on writing drivers, see Mixin::ExtraFields::Driver.
178 default_moniker
180 This method returns the default moniker. The default default moniker
181 defaults to the default "extra".
182 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 my @methods = Mixin::ExtraFields->methods;
189 method_name
191 my $method_name = Mixin::ExtraFields->method_name($method_base, $moniker);
192 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 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 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 gen_fields_group
209 my $sub_href = Mixin::ExtraFields->gen_fields_group($name, \%arg, \%col);
210 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 build_method
216 my $code = Mixin::ExtraFields->build_method($method_name, \%arg);
217 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 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 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 default_driver_arg
232 my $arg = Mixin::ExtraFields->default_driver_arg;
233 This method a default value for the "driver" argument to the fields
235 group generator. By default, this method will croak if called.
236 build_driver
238 my $driver = Mixin::ExtraFields->build_driver($arg);
239 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 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
249 • handle invocants without ids (classes) and drivers that don't need
250 ids
251
253 Ricardo Signes <cpan@semiotic.systems>
254
256 • Ricardo SIGNES <rjbs@codesimply.com>
257 • Ricardo Signes <rjbs@semiotic.systems>
259
261 This software is copyright (c) 2022 by Ricardo Signes.
262 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.
265perl v5.38.0 2023-07-20 Mixin::ExtraFields(3)