1Class::Accessor::GroupeUds(e3r)Contributed Perl DocumentCaltaisosn::Accessor::Grouped(3)
2
6 Class::Accessor::Grouped - Lets you build groups of accessors
7
9 use base 'Class::Accessor::Grouped';
10 # make basic accessors for objects
12 __PACKAGE__->mk_group_accessors(simple => qw(id name email));
13 # make accessor that works for objects and classes
15 __PACKAGE__->mk_group_accessors(inherited => 'awesome_level');
16 # make an accessor which calls a custom pair of getters/setters
18 sub get_column { ... this will be called when you do $obj->name() ... }
19 sub set_column { ... this will be called when you do $obj->name('foo') ... }
20 __PACKAGE__->mk_group_accessors(column => 'name');
21
23 This class lets you build groups of accessors that will call different
24 getters and setters. The documentation of this module still requires a
25 lot of work (volunteers welcome >.>), but in the meantime you can refer
26 to this post <http://lo-
27 f.at/glahn/2009/08/WritingPowerfulAccessorsForPerlClasses.html> for
28 more information.
29 Notes on accessor names
31 In general method names in Perl are considered identifiers, and as such
32 need to conform to the identifier specification of
33 "qr/\A[A-Z_a-z][0-9A-Z_a-z]*\z/". While it is rather easy to invoke
34 methods with non-standard names ("$obj->${\"anything goes"}"), it is
35 not possible to properly declare such methods without the use of
36 Sub::Name. Since this module must be able to function identically with
37 and without its optional dependencies, starting with version 0.10008
38 attempting to declare an accessor with a non-standard name is a fatal
39 error (such operations would silently succeed since version 0.08004, as
40 long as Sub::Name is present, or otherwise would result in a syntax
41 error during a string eval).
42 Unfortunately in the years since 0.08004 a rather large body of code
44 accumulated in the wild that does attempt to declare accessors with
45 funny names. One notable perpetrator is DBIx::Class::Schema::Loader,
46 which under certain conditions could create accessors of the "column"
47 group which start with numbers and/or some other punctuation (the
48 proper way would be to declare columns with the "accessor" attribute
49 set to "undef").
50 Therefore an escape mechanism is provided via the environment variable
52 "CAG_ILLEGAL_ACCESSOR_NAME_OK". When set to a true value, one warning
53 is issued per class on attempts to declare an accessor with a non-
54 conforming name, and as long as Sub::Name is available all accessors
55 will be properly created. Regardless of this setting, accessor names
56 containing nulls "\0" are disallowed, due to various deficiencies in
57 perl itself.
58 If your code base has too many instances of illegal accessor
60 declarations, and a fix is not feasible due to time constraints, it is
61 possible to disable the warnings altogether by setting
62 $ENV{CAG_ILLEGAL_ACCESSOR_NAME_OK} to "DO_NOT_WARN" (observe
63 capitalization).
64
66 mk_group_accessors
67 __PACKAGE__->mk_group_accessors(simple => 'hair_length', [ hair_color => 'hc' ]);
68 Arguments: $group, @fieldspec
70 Returns: none
71 Creates a set of accessors in a given group.
73 $group is the name of the accessor group for the generated accessors;
75 they will call get_$group($field) on get and set_$group($field, $value)
76 on set.
77 If you want to mimic Class::Accessor's mk_accessors $group has to be
79 'simple' to tell Class::Accessor::Grouped to use its own get_simple and
80 set_simple methods.
81 @fieldspec is a list of field/accessor names; if a fieldspec is a
83 scalar this is used as both field and accessor name, if a listref it is
84 expected to be of the form [ $accessor, $field ].
85 mk_group_ro_accessors
87 __PACKAGE__->mk_group_ro_accessors(simple => 'birthdate', [ social_security_number => 'ssn' ]);
88 Arguments: $group, @fieldspec
90 Returns: none
91 Creates a set of read only accessors in a given group. Identical to
93 "mk_group_accessors" but accessors will throw an error if passed a
94 value rather than setting the value.
95 mk_group_wo_accessors
97 __PACKAGE__->mk_group_wo_accessors(simple => 'lie', [ subject => 'subj' ]);
98 Arguments: $group, @fieldspec
100 Returns: none
101 Creates a set of write only accessors in a given group. Identical to
103 "mk_group_accessors" but accessors will throw an error if not passed a
104 value rather than getting the value.
105 get_simple
107 Arguments: $field
108 Returns: $value
109 Simple getter for hash-based objects which returns the value for the
111 field name passed as an argument.
112 set_simple
114 Arguments: $field, $new_value
115 Returns: $new_value
116 Simple setter for hash-based objects which sets and then returns the
118 value for the field name passed as an argument.
119 get_inherited
121 Arguments: $field
122 Returns: $value
123 Simple getter for Classes and hash-based objects which returns the
125 value for the field name passed as an argument. This behaves much like
126 Class::Data::Accessor where the field can be set in a base class,
127 inherited and changed in subclasses, and inherited and changed for
128 object instances.
129 set_inherited
131 Arguments: $field, $new_value
132 Returns: $new_value
133 Simple setter for Classes and hash-based objects which sets and then
135 returns the value for the field name passed as an argument. When called
136 on a hash-based object it will set the appropriate hash key value. When
137 called on a class, it will set a class level variable.
138 Note:: This method will die if you try to set an object variable on a
140 non hash-based object.
141 get_component_class
143 Arguments: $field
144 Returns: $value
145 Gets the value of the specified component class.
147 __PACKAGE__->mk_group_accessors('component_class' => 'result_class');
149 $self->result_class->method();
151 ## same as
153 $self->get_component_class('result_class')->method();
154 set_component_class
156 Arguments: $field, $class
157 Returns: $new_value
158 Inherited accessor that automatically loads the specified class before
160 setting it. This method will die if the specified class could not be
161 loaded.
162 __PACKAGE__->mk_group_accessors('component_class' => 'result_class');
164 __PACKAGE__->result_class('MyClass');
165 $self->result_class->method();
167
169 These methods are documented for clarity, but are never meant to be
170 called directly, and are not really meant for overriding either.
171 get_super_paths
173 Returns a list of 'parent' or 'super' class names that the current
174 class inherited from. This is what drives the traversal done by
175 "get_inherited".
176 make_group_accessor
178 __PACKAGE__->make_group_accessor('simple', 'hair_length', 'hair_length');
179 __PACKAGE__->make_group_accessor('simple', 'hc', 'hair_color');
180 Arguments: $group, $field, $accessor
182 Returns: \&accessor_coderef ?
183 Called by mk_group_accessors for each entry in @fieldspec. Either
185 returns a coderef which will be installed at "&__PACKAGE__::$accessor",
186 or returns "undef" if it elects to install the coderef on its own.
187 make_group_ro_accessor
189 __PACKAGE__->make_group_ro_accessor('simple', 'birthdate', 'birthdate');
190 __PACKAGE__->make_group_ro_accessor('simple', 'ssn', 'social_security_number');
191 Arguments: $group, $field, $accessor
193 Returns: \&accessor_coderef ?
194 Called by mk_group_ro_accessors for each entry in @fieldspec. Either
196 returns a coderef which will be installed at "&__PACKAGE__::$accessor",
197 or returns "undef" if it elects to install the coderef on its own.
198 make_group_wo_accessor
200 __PACKAGE__->make_group_wo_accessor('simple', 'lie', 'lie');
201 __PACKAGE__->make_group_wo_accessor('simple', 'subj', 'subject');
202 Arguments: $group, $field, $accessor
204 Returns: \&accessor_coderef ?
205 Called by mk_group_wo_accessors for each entry in @fieldspec. Either
207 returns a coderef which will be installed at "&__PACKAGE__::$accessor",
208 or returns "undef" if it elects to install the coderef on its own.
209
211 To provide total flexibility Class::Accessor::Grouped calls methods
212 internally while performing get/set actions, which makes it noticeably
213 slower than similar modules. To compensate, this module will
214 automatically use the insanely fast Class::XSAccessor to generate the
215 "simple"-group accessors if this module is available on your system.
216 Benchmark
218 This is the benchmark of 200 get/get/set/get/set cycles on perl 5.16.2
219 with thread support, showcasing how this modules simple (CAG_S),
220 inherited (CAG_INH) and inherited with parent-class data (CAG_INHP)
221 accessors stack up against most popular accessor builders: Moose, Moo,
222 Mo, Mouse (both pure-perl and XS variant), Object::Tiny::RW (OTRW),
223 Class::Accessor (CA), Class::Accessor::Lite (CAL),
224 Class::Accessor::Fast (CAF), Class::Accessor::Fast::XS (CAF_XS) and
225 Class::XSAccessor (XSA)
226 Rate CAG_INHP CAG_INH CA CAG_S CAF moOse OTRW CAL mo moUse HANDMADE moo CAF_XS moUse_XS XSA
228 CAG_INHP 287.021+-0.02/s -- -0.3% -10.0% -37.1% -53.1% -53.6% -53.7% -54.1% -56.9% -59.0% -59.6% -59.8% -78.7% -81.9% -83.5%
230 CAG_INH 288.025+-0.031/s 0.3% -- -9.7% -36.9% -52.9% -53.5% -53.5% -53.9% -56.7% -58.8% -59.5% -59.7% -78.6% -81.9% -83.5%
232 CA 318.967+-0.047/s 11.1% 10.7% -- -30.1% -47.9% -48.5% -48.5% -49.0% -52.1% -54.4% -55.1% -55.3% -76.3% -79.9% -81.7%
234 CAG_S 456.107+-0.054/s 58.9% 58.4% 43.0% -- -25.4% -26.3% -26.4% -27.0% -31.5% -34.8% -35.8% -36.1% -66.1% -71.3% -73.9%
236 CAF 611.745+-0.099/s 113.1% 112.4% 91.8% 34.1% -- -1.2% -1.2% -2.1% -8.1% -12.6% -14.0% -14.3% -54.5% -61.5% -64.9%
238 moOse 619.051+-0.059/s 115.7% 114.9% 94.1% 35.7% 1.2% -- -0.1% -1.0% -7.0% -11.6% -12.9% -13.3% -54.0% -61.0% -64.5%
240 OTRW 619.475+-0.1/s 115.8% 115.1% 94.2% 35.8% 1.3% 0.1% -- -0.9% -6.9% -11.5% -12.9% -13.2% -54.0% -61.0% -64.5%
242 CAL 625.106+-0.085/s 117.8% 117.0% 96.0% 37.1% 2.2% 1.0% 0.9% -- -6.1% -10.7% -12.1% -12.5% -53.5% -60.6% -64.2%
244 mo 665.44+-0.12/s 131.8% 131.0% 108.6% 45.9% 8.8% 7.5% 7.4% 6.5% -- -4.9% -6.4% -6.8% -50.5% -58.1% -61.9%
246 moUse 699.9+-0.15/s 143.9% 143.0% 119.4% 53.5% 14.4% 13.1% 13.0% 12.0% 5.2% -- -1.6% -2.0% -48.0% -55.9% -59.9%
248 HANDMADE 710.98+-0.16/s 147.7% 146.8% 122.9% 55.9% 16.2% 14.9% 14.8% 13.7% 6.8% 1.6% -- -0.4% -47.2% -55.2% -59.2%
250 moo 714.04+-0.13/s 148.8% 147.9% 123.9% 56.6% 16.7% 15.3% 15.3% 14.2% 7.3% 2.0% 0.4% -- -46.9% -55.0% -59.1%
252 CAF_XS 1345.55+-0.051/s 368.8% 367.2% 321.8% 195.0% 120.0% 117.4% 117.2% 115.3% 102.2% 92.2% 89.3% 88.4% -- -15.3% -22.9%
254 moUse_XS 1588+-0.036/s 453.3% 451.3% 397.9% 248.2% 159.6% 156.5% 156.3% 154.0% 138.6% 126.9% 123.4% 122.4% 18.0% -- -9.0%
256 XSA 1744.67+-0.052/s 507.9% 505.7% 447.0% 282.5% 185.2% 181.8% 181.6% 179.1% 162.2% 149.3% 145.4% 144.3% 29.7% 9.9% --
258 Benchmarking program is available in the root of the repository
260 <http://search.cpan.org/dist/Class-Accessor-Grouped/>:
261 Notes on Class::XSAccessor
263 You can force (or disable) the use of Class::XSAccessor before creating
264 a particular "simple" accessor by either manipulating the global
265 variable $Class::Accessor::Grouped::USE_XS to true or false (preferably
266 with localization, or you can do so before runtime via the "CAG_USE_XS"
267 environment variable.
268 Since Class::XSAccessor has no knowledge of "get_simple" and
270 "set_simple" this module does its best to detect if you are overriding
271 one of these methods and will fall back to using the perl version of
272 the accessor in order to maintain consistency. However be aware that if
273 you enable use of "Class::XSAccessor" (automatically or explicitly),
274 create an object, invoke a simple accessor on that object, and then
275 manipulate the symbol table to install a "get/set_simple" override -
276 you get to keep all the pieces.
277
279 Matt S. Trout <mst@shadowcatsystems.co.uk>
280 Christopher H. Laco <claco@chrislaco.com>
282
284 Caelum: Rafael Kitover <rkitover@cpan.org>
285 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
287 groditi: Guillermo Roditi <groditi@cpan.org>
289 Jason Plum <jason.plum@bmmsi.com>
291 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
293
295 Copyright (c) 2006-2010 Matt S. Trout <mst@shadowcatsystems.co.uk>
296 This program is free software; you can redistribute it and/or modify it
298 under the same terms as perl itself.
299perl v5.32.1 2021-01-26 Class::Accessor::Grouped(3)