remove pod_spelling.t
[p5sagit/Class-Accessor-Grouped.git] / lib / Class / Accessor / Grouped.pm
CommitLineData
963a69a5 1package Class::Accessor::Grouped;
2use strict;
3use warnings;
a0bce8bc 4use Carp ();
331e820d 5use Class::Inspector ();
a0bce8bc 6use Scalar::Util ();
8787799c 7use MRO::Compat;
1ee74bdd 8use Sub::Name ();
331e820d 9
af169484 10our $VERSION = '0.09003';
15cf8e32 11$VERSION = eval $VERSION;
963a69a5 12
a2537c55 13our $hasXS;
af169484 14
a2537c55 15sub _hasXS {
a2537c55 16 if (not defined $hasXS) {
17 $hasXS = 0;
18
8ef9b3ff 19 eval {
20 require Class::XSAccessor;
21 $hasXS = 1;
22 };
a2537c55 23 }
24
25 return $hasXS;
26}
27
963a69a5 28=head1 NAME
29
1ad8d8c6 30Class::Accessor::Grouped - Lets you build groups of accessors
963a69a5 31
32=head1 SYNOPSIS
33
34=head1 DESCRIPTION
35
36This class lets you build groups of accessors that will call different
37getters and setters.
38
39=head1 METHODS
40
41=head2 mk_group_accessors
42
43=over 4
44
45=item Arguments: $group, @fieldspec
46
47Returns: none
48
49=back
50
51Creates a set of accessors in a given group.
52
53$group is the name of the accessor group for the generated accessors; they
54will call get_$group($field) on get and set_$group($field, $value) on set.
55
22fa6720 56If you want to mimic Class::Accessor's mk_accessors $group has to be 'simple'
57to tell Class::Accessor::Grouped to use its own get_simple and set_simple
58methods.
59
963a69a5 60@fieldspec is a list of field/accessor names; if a fieldspec is a scalar
61this is used as both field and accessor name, if a listref it is expected to
62be of the form [ $accessor, $field ].
63
64=cut
65
66sub mk_group_accessors {
67 my ($self, $group, @fields) = @_;
68
69 $self->_mk_group_accessors('make_group_accessor', $group, @fields);
70 return;
71}
72
73
74{
75 no strict 'refs';
76 no warnings 'redefine';
77
78 sub _mk_group_accessors {
79 my($self, $maker, $group, @fields) = @_;
a0bce8bc 80 my $class = Scalar::Util::blessed $self || $self;
963a69a5 81
82 # So we don't have to do lots of lookups inside the loop.
83 $maker = $self->can($maker) unless ref $maker;
9540f4e4 84
85 my $hasXS = _hasXS();
963a69a5 86
87 foreach my $field (@fields) {
88 if( $field eq 'DESTROY' ) {
a0bce8bc 89 Carp::carp("Having a data accessor named DESTROY in ".
963a69a5 90 "'$class' is unwise.");
91 }
92
93 my $name = $field;
94
95 ($name, $field) = @$field if ref $field;
9540f4e4 96
963a69a5 97 my $alias = "_${name}_accessor";
1ee74bdd 98 my $full_name = join('::', $class, $name);
99 my $full_alias = join('::', $class, $alias);
9540f4e4 100 if ( $hasXS && $group eq 'simple' ) {
46f1ef81 101 require Class::XSAccessor;
96bd9337 102 Class::XSAccessor->import({
103 replace => 1,
104 class => $class,
105 accessors => {
106 $name => $field,
107 $alias => $field,
108 },
109 });
9540f4e4 110 }
111 else {
112 my $accessor = $self->$maker($group, $field);
113 my $alias_accessor = $self->$maker($group, $field);
114
115 *$full_name = Sub::Name::subname($full_name, $accessor);
116 #unless defined &{$class."\:\:$field"}
117
118 *$full_alias = Sub::Name::subname($full_alias, $alias_accessor);
119 #unless defined &{$class."\:\:$alias"}
120 }
963a69a5 121 }
122 }
123}
124
125=head2 mk_group_ro_accessors
126
127=over 4
128
129=item Arguments: $group, @fieldspec
130
131Returns: none
132
133=back
134
135Creates a set of read only accessors in a given group. Identical to
a557f8ad 136L</mk_group_accessors> but accessors will throw an error if passed a value
963a69a5 137rather than setting the value.
138
139=cut
140
141sub mk_group_ro_accessors {
142 my($self, $group, @fields) = @_;
143
144 $self->_mk_group_accessors('make_group_ro_accessor', $group, @fields);
145}
146
147=head2 mk_group_wo_accessors
148
149=over 4
150
151=item Arguments: $group, @fieldspec
152
153Returns: none
154
155=back
156
157Creates a set of write only accessors in a given group. Identical to
a557f8ad 158L</mk_group_accessors> but accessors will throw an error if not passed a
963a69a5 159value rather than getting the value.
160
161=cut
162
163sub mk_group_wo_accessors {
164 my($self, $group, @fields) = @_;
165
166 $self->_mk_group_accessors('make_group_wo_accessor', $group, @fields);
167}
168
169=head2 make_group_accessor
170
171=over 4
172
173=item Arguments: $group, $field
174
175Returns: $sub (\CODE)
176
177=back
178
179Returns a single accessor in a given group; called by mk_group_accessors
180for each entry in @fieldspec.
181
182=cut
183
184sub make_group_accessor {
185 my ($class, $group, $field) = @_;
186
187 my $set = "set_$group";
188 my $get = "get_$group";
189
a0bce8bc 190 # eval for faster fastiness
191 return eval "sub {
192 if(\@_ > 1) {
193 return shift->$set('$field', \@_);
963a69a5 194 }
195 else {
a0bce8bc 196 return shift->$get('$field');
963a69a5 197 }
a0bce8bc 198 };"
963a69a5 199}
200
201=head2 make_group_ro_accessor
202
203=over 4
204
205=item Arguments: $group, $field
206
207Returns: $sub (\CODE)
208
209=back
210
211Returns a single read-only accessor in a given group; called by
212mk_group_ro_accessors for each entry in @fieldspec.
213
214=cut
215
216sub make_group_ro_accessor {
217 my($class, $group, $field) = @_;
218
219 my $get = "get_$group";
220
a0bce8bc 221 return eval "sub {
222 if(\@_ > 1) {
223 my \$caller = caller;
224 Carp::croak(\"'\$caller' cannot alter the value of '$field' on \".
225 \"objects of class '$class'\");
963a69a5 226 }
227 else {
a0bce8bc 228 return shift->$get('$field');
963a69a5 229 }
a0bce8bc 230 };"
963a69a5 231}
232
233=head2 make_group_wo_accessor
234
235=over 4
236
237=item Arguments: $group, $field
238
239Returns: $sub (\CODE)
240
241=back
242
243Returns a single write-only accessor in a given group; called by
244mk_group_wo_accessors for each entry in @fieldspec.
245
246=cut
247
248sub make_group_wo_accessor {
249 my($class, $group, $field) = @_;
250
251 my $set = "set_$group";
252
a0bce8bc 253 return eval "sub {
254 unless (\@_ > 1) {
255 my \$caller = caller;
256 Carp::croak(\"'\$caller' cannot access the value of '$field' on \".
257 \"objects of class '$class'\");
963a69a5 258 }
259 else {
a0bce8bc 260 return shift->$set('$field', \@_);
963a69a5 261 }
a0bce8bc 262 };"
963a69a5 263}
264
265=head2 get_simple
266
267=over 4
268
269=item Arguments: $field
270
271Returns: $value
272
273=back
274
275Simple getter for hash-based objects which returns the value for the field
276name passed as an argument.
277
278=cut
279
280sub get_simple {
a0bce8bc 281 return $_[0]->{$_[1]};
963a69a5 282}
283
284=head2 set_simple
285
286=over 4
287
288=item Arguments: $field, $new_value
289
290Returns: $new_value
291
292=back
293
294Simple setter for hash-based objects which sets and then returns the value
295for the field name passed as an argument.
296
297=cut
298
299sub set_simple {
a0bce8bc 300 return $_[0]->{$_[1]} = $_[2];
963a69a5 301}
302
e6f2a0fd 303
304=head2 get_inherited
305
306=over 4
307
308=item Arguments: $field
309
310Returns: $value
311
312=back
313
331e820d 314Simple getter for Classes and hash-based objects which returns the value for
315the field name passed as an argument. This behaves much like
316L<Class::Data::Accessor> where the field can be set in a base class,
317inherited and changed in subclasses, and inherited and changed for object
318instances.
e6f2a0fd 319
320=cut
321
322sub get_inherited {
a49c32d9 323 my $class;
e6f2a0fd 324
62cf9924 325 if ( ($class = ref $_[0]) && Scalar::Util::blessed $_[0]) {
326 if (Scalar::Util::reftype $_[0] eq 'HASH') {
327 return $_[0]->{$_[1]} if exists $_[0]->{$_[1]};
328 }
329 else {
330 Carp::croak('Cannot get inherited value on an object instance that is not hash-based');
331 }
332 }
333 else {
a0bce8bc 334 $class = $_[0];
62cf9924 335 }
e6f2a0fd 336
337 no strict 'refs';
fe63d727 338 no warnings qw/uninitialized/;
62cf9924 339
340 my $cag_slot = '::__cag_'. $_[1];
341 return ${$class.$cag_slot} if defined(${$class.$cag_slot});
e6f2a0fd 342
4f8ce9da 343 # we need to be smarter about recalculation, as @ISA (thus supers) can very well change in-flight
62cf9924 344 my $cur_gen = mro::get_pkg_gen ($class);
345 if ( $cur_gen != ${$class.'::__cag_pkg_gen__'} ) {
346 @{$class.'::__cag_supers__'} = $_[0]->get_super_paths;
347 ${$class.'::__cag_pkg_gen__'} = $cur_gen;
348 }
a49c32d9 349
62cf9924 350 for (@{$class.'::__cag_supers__'}) {
351 return ${$_.$cag_slot} if defined(${$_.$cag_slot});
e6f2a0fd 352 };
c46050d3 353
9c3d5179 354 return undef;
e6f2a0fd 355}
356
357=head2 set_inherited
358
359=over 4
360
361=item Arguments: $field, $new_value
362
363Returns: $new_value
364
365=back
366
331e820d 367Simple setter for Classes and hash-based objects which sets and then returns
368the value for the field name passed as an argument. When called on a hash-based
369object it will set the appropriate hash key value. When called on a class, it
370will set a class level variable.
e6f2a0fd 371
331e820d 372B<Note:>: This method will die if you try to set an object variable on a non
373hash-based object.
e6f2a0fd 374
375=cut
376
377sub set_inherited {
a0bce8bc 378 if (Scalar::Util::blessed $_[0]) {
379 if (Scalar::Util::reftype $_[0] eq 'HASH') {
380 return $_[0]->{$_[1]} = $_[2];
e6f2a0fd 381 } else {
a0bce8bc 382 Carp::croak('Cannot set inherited value on an object instance that is not hash-based');
e6f2a0fd 383 };
384 } else {
385 no strict 'refs';
386
a0bce8bc 387 return ${$_[0].'::__cag_'.$_[1]} = $_[2];
e6f2a0fd 388 };
389}
390
331e820d 391=head2 get_component_class
392
393=over 4
394
395=item Arguments: $field
396
397Returns: $value
398
399=back
400
401Gets the value of the specified component class.
402
403 __PACKAGE__->mk_group_accessors('component_class' => 'result_class');
97d76fb4 404
331e820d 405 $self->result_class->method();
97d76fb4 406
331e820d 407 ## same as
408 $self->get_component_class('result_class')->method();
409
410=cut
411
412sub get_component_class {
a0bce8bc 413 return $_[0]->get_inherited($_[1]);
331e820d 414};
415
416=head2 set_component_class
417
418=over 4
419
420=item Arguments: $field, $class
421
422Returns: $new_value
423
424=back
425
426Inherited accessor that automatically loads the specified class before setting
427it. This method will die if the specified class could not be loaded.
428
429 __PACKAGE__->mk_group_accessors('component_class' => 'result_class');
430 __PACKAGE__->result_class('MyClass');
97d76fb4 431
331e820d 432 $self->result_class->method();
433
434=cut
435
436sub set_component_class {
a0bce8bc 437 if ($_[2]) {
bce7bdf8 438 local $^W = 0;
a0bce8bc 439 if (Class::Inspector->installed($_[2]) && !Class::Inspector->loaded($_[2])) {
440 eval "use $_[2]";
331e820d 441
a0bce8bc 442 Carp::croak("Could not load $_[1] '$_[2]': ", $@) if $@;
331e820d 443 };
444 };
445
a0bce8bc 446 return $_[0]->set_inherited($_[1], $_[2]);
331e820d 447};
448
a49c32d9 449=head2 get_super_paths
450
451Returns a list of 'parent' or 'super' class names that the current class inherited from.
452
453=cut
454
455sub get_super_paths {
62cf9924 456 return @{mro::get_linear_isa( ref($_[0]) || $_[0] )};
a49c32d9 457};
458
a2537c55 4591;
b9a69571 460
9d7d52da 461=head1 PERFORMANCE
15cf8e32 462
a2537c55 463You can speed up accessors of type 'simple' by installing L<Class::XSAccessor>.
963a69a5 464
465=head1 AUTHORS
466
467Matt S. Trout <mst@shadowcatsystems.co.uk>
97972dcb 468Christopher H. Laco <claco@chrislaco.com>
963a69a5 469
8ef9b3ff 470=head1 CONTRIBUTORS
dfb86526 471
8ef9b3ff 472groditi: Guillermo Roditi <groditi@cpan.org>
473ribasushi: Peter Rabbitson <ribasushi@cpan.org>
dfb86526 474
4fe25633 475=head1 COPYRIGHT & LICENSE
963a69a5 476
af169484 477Copyright (c) 2006-2010 Matt S. Trout <mst@shadowcatsystems.co.uk>
963a69a5 478
4fe25633 479This program is free software; you can redistribute it and/or modify
480it under the same terms as perl itself.
963a69a5 481
4fe25633 482=cut