1Mixin::ExtraFields(3) User Contributed Perl DocumentationMixin::ExtraFields(3)
2
3
4
6 Mixin::ExtraFields - add extra stashes of data to your objects
7
9 version 0.140002
10
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
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
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
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
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
240 • handle invocants without ids (classes) and drivers that don't need
241 ids
242
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.34.0 2022-01-21 Mixin::ExtraFields(3)