1Class::Accessor::GroupeUds(e3r)Contributed Perl DocumentCaltaisosn::Accessor::Grouped(3)
2
3
4

NAME

6       Class::Accessor::Grouped - Lets you build groups of accessors
7

SYNOPSIS

9        use base 'Class::Accessor::Grouped';
10
11        # make basic accessors for objects
12        __PACKAGE__->mk_group_accessors(simple => qw(id name email));
13
14        # make accessor that works for objects and classes
15        __PACKAGE__->mk_group_accessors(inherited => 'awesome_level');
16
17        # 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

DESCRIPTION

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
30   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
43       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
51       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
59       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

METHODS

66   mk_group_accessors
67        __PACKAGE__->mk_group_accessors(simple => 'hair_length', [ hair_color => 'hc' ]);
68
69       Arguments: $group, @fieldspec
70           Returns: none
71
72       Creates a set of accessors in a given group.
73
74       $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
78       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
82       @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
86   mk_group_ro_accessors
87        __PACKAGE__->mk_group_ro_accessors(simple => 'birthdate', [ social_security_number => 'ssn' ]);
88
89       Arguments: $group, @fieldspec
90           Returns: none
91
92       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
96   mk_group_wo_accessors
97        __PACKAGE__->mk_group_wo_accessors(simple => 'lie', [ subject => 'subj' ]);
98
99       Arguments: $group, @fieldspec
100           Returns: none
101
102       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
106   get_simple
107       Arguments: $field
108           Returns: $value
109
110       Simple getter for hash-based objects which returns the value for the
111       field name passed as an argument.
112
113   set_simple
114       Arguments: $field, $new_value
115           Returns: $new_value
116
117       Simple setter for hash-based objects which sets and then returns the
118       value for the field name passed as an argument.
119
120   get_inherited
121       Arguments: $field
122           Returns: $value
123
124       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
130   set_inherited
131       Arguments: $field, $new_value
132           Returns: $new_value
133
134       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
139       Note:: This method will die if you try to set an object variable on a
140       non hash-based object.
141
142   get_component_class
143       Arguments: $field
144           Returns: $value
145
146       Gets the value of the specified component class.
147
148        __PACKAGE__->mk_group_accessors('component_class' => 'result_class');
149
150        $self->result_class->method();
151
152        ## same as
153        $self->get_component_class('result_class')->method();
154
155   set_component_class
156       Arguments: $field, $class
157           Returns: $new_value
158
159       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
163        __PACKAGE__->mk_group_accessors('component_class' => 'result_class');
164        __PACKAGE__->result_class('MyClass');
165
166        $self->result_class->method();
167

INTERNAL METHODS

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
172   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
177   make_group_accessor
178        __PACKAGE__->make_group_accessor('simple', 'hair_length', 'hair_length');
179        __PACKAGE__->make_group_accessor('simple', 'hc', 'hair_color');
180
181       Arguments: $group, $field, $accessor
182           Returns: \&accessor_coderef ?
183
184       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
188   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
192       Arguments: $group, $field, $accessor
193           Returns: \&accessor_coderef ?
194
195       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
199   make_group_wo_accessor
200        __PACKAGE__->make_group_wo_accessor('simple', 'lie', 'lie');
201        __PACKAGE__->make_group_wo_accessor('simple', 'subj', 'subject');
202
203       Arguments: $group, $field, $accessor
204           Returns: \&accessor_coderef ?
205
206       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

PERFORMANCE

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
217   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
227                             Rate CAG_INHP CAG_INH     CA  CAG_S    CAF  moOse   OTRW    CAL     mo  moUse HANDMADE    moo CAF_XS moUse_XS    XSA
228
229        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
231        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
233        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
235        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
237        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
239        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
241        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
243        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
245        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
247        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
249        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
251        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
253        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
255        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
257        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
259       Benchmarking program is available in the root of the repository
260       <http://search.cpan.org/dist/Class-Accessor-Grouped/>:
261
262   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
269       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

AUTHORS

279       Matt S. Trout <mst@shadowcatsystems.co.uk>
280
281       Christopher H. Laco <claco@chrislaco.com>
282

CONTRIBUTORS

284       Caelum: Rafael Kitover <rkitover@cpan.org>
285
286       frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
287
288       groditi: Guillermo Roditi <groditi@cpan.org>
289
290       Jason Plum <jason.plum@bmmsi.com>
291
292       ribasushi: Peter Rabbitson <ribasushi@cpan.org>
293
295       Copyright (c) 2006-2010 Matt S. Trout <mst@shadowcatsystems.co.uk>
296
297       This program is free software; you can redistribute it and/or modify it
298       under the same terms as perl itself.
299
300
301
302perl v5.32.0                      2020-07-28       Class::Accessor::Grouped(3)
Impressum