1 package Class
::Accessor
;
4 $Class::Accessor
::VERSION
= '0.31';
8 Class::Accessor - Automated accessor generation
13 use base qw(Class::Accessor);
14 Employee->mk_accessors(qw(name role salary));
16 # Meanwhile, in a nearby piece of code!
17 # Class::Accessor provides new().
18 my $mp = Foo->new({ name => "Marty", role => "JAPH" });
20 my $job = $mp->role; # gets $mp->{role}
21 $mp->salary(400000); # sets $mp->{salary} = 400000 (I wish)
23 # like my @info = @{$mp}{qw(name role)}
24 my @info = $mp->get(qw(name role));
26 # $mp->{salary} = 400000
27 $mp->set('salary', 400000);
32 This module automagically generates accessors/mutators for your class.
34 Most of the time, writing accessors is an exercise in cutting and
35 pasting. You usually wind up with a series of methods like this:
40 $self->{name} = $_[0];
48 $self->{salary} = $_[0];
50 return $self->{salary};
55 One for each piece of data in your object. While some will be unique,
56 doing value checks and special storage tricks, most will simply be
57 exercises in repetition. Not only is it Bad Style to have a bunch of
58 repetitious code, but its also simply not lazy, which is the real
61 If you make your module a subclass of Class::Accessor and declare your
62 accessor fields with mk_accessors() then you'll find yourself with a
63 set of automatically generated accessors which can even be
66 The basic set up is very simple:
69 use base qw(Class::Accessor);
70 My::Class->mk_accessors( qw(foo bar car) );
72 Done. My::Class now has simple foo(), bar() and car() accessors
75 =head2 What Makes This Different?
77 What makes this module special compared to all the other method
78 generating modules (L<"SEE ALSO">)? By overriding the get() and set()
79 methods you can alter the behavior of the accessors class-wide. Also,
80 the accessors are implemented as closures which should cost a bit less
81 memory than most other solutions which generate a new method for each
90 my $obj = $other_obj->new;
92 my $obj = Class->new(\%fields);
93 my $obj = $other_obj->new(\%fields);
95 Class::Accessor provides a basic constructor. It generates a
96 hash-based object and can be called as either a class method or an
99 It takes an optional %fields hash which is used to initialize the
100 object (handy if you use read-only accessors). The fields of the hash
101 correspond to the names of your accessors, so...
104 use base qw(Class::Accessor);
105 Foo->mk_accessors('foo');
107 my $obj = Class->new({ foo => 42 });
108 print $obj->foo; # 42
110 however %fields can contain anything, new() will shove them all into
111 your object. Don't like it? Override it.
116 my($proto, $fields) = @_;
117 my($class) = ref $proto || $proto;
119 $fields = {} unless defined $fields;
121 # make a copy of $fields.
122 bless {%$fields}, $class;
127 Class->mk_accessors(@fields);
129 This creates accessor/mutator methods for each named field given in
130 @fields. Foreach field in @fields it will generate two accessors.
131 One called "field()" and the other called "_field_accessor()". For
134 # Generates foo(), _foo_accessor(), bar() and _bar_accessor().
135 Class->mk_accessors(qw(foo bar));
137 See L<CAVEATS AND TRICKS/"Overriding autogenerated accessors">
143 my($self, @fields) = @_;
145 $self->_mk_accessors('rw', @fields);
153 my($self, $access, @fields) = @_;
154 my $class = ref $self || $self;
155 my $ra = $access eq 'rw' || $access eq 'ro';
156 my $wa = $access eq 'rw' || $access eq 'wo';
158 foreach my $field (@fields) {
159 my $accessor_name = $self->accessor_name_for($field);
160 my $mutator_name = $self->mutator_name_for($field);
161 if( $accessor_name eq 'DESTROY' or $mutator_name eq 'DESTROY' ) {
162 $self->_carp("Having a data accessor named DESTROY in '$class' is unwise.");
164 if ($accessor_name eq $mutator_name) {
167 $accessor = $self->make_accessor($field);
169 $accessor = $self->make_ro_accessor($field);
171 $accessor = $self->make_wo_accessor($field);
173 unless (defined &{"${class}::$accessor_name"}) {
174 *{"${class}::$accessor_name"} = $accessor;
176 if ($accessor_name eq $field) {
178 my $alias = "_${field}_accessor";
179 *{"${class}::$alias"} = $accessor unless defined &{"${class}::$alias"};
182 if ($ra and not defined &{"${class}::$accessor_name"}) {
183 *{"${class}::$accessor_name"} = $self->make_ro_accessor($field);
185 if ($wa and not defined &{"${class}::$mutator_name"}) {
186 *{"${class}::$mutator_name"} = $self->make_wo_accessor($field);
192 sub follow_best_practice
{
194 my $class = ref $self || $self;
195 *{"${class}::accessor_name_for"} = \
&best_practice_accessor_name_for
;
196 *{"${class}::mutator_name_for"} = \
&best_practice_mutator_name_for
;
201 =head2 mk_ro_accessors
203 Class->mk_ro_accessors(@read_only_fields);
205 Same as mk_accessors() except it will generate read-only accessors
206 (ie. true accessors). If you attempt to set a value with these
207 accessors it will throw an exception. It only uses get() and not
211 use base qw(Class::Accessor);
212 Class->mk_ro_accessors(qw(foo bar));
214 # Let's assume we have an object $foo of class Foo...
215 print $foo->foo; # ok, prints whatever the value of $foo->{foo} is
216 $foo->foo(42); # BOOM! Naughty you.
221 sub mk_ro_accessors
{
222 my($self, @fields) = @_;
224 $self->_mk_accessors('ro', @fields);
227 =head2 mk_wo_accessors
229 Class->mk_wo_accessors(@write_only_fields);
231 Same as mk_accessors() except it will generate write-only accessors
232 (ie. mutators). If you attempt to read a value with these accessors
233 it will throw an exception. It only uses set() and not get().
235 B<NOTE> I'm not entirely sure why this is useful, but I'm sure someone
236 will need it. If you've found a use, let me know. Right now its here
237 for orthoginality and because its easy to implement.
240 use base qw(Class::Accessor);
241 Class->mk_wo_accessors(qw(foo bar));
243 # Let's assume we have an object $foo of class Foo...
244 $foo->foo(42); # OK. Sets $self->{foo} = 42
245 print $foo->foo; # BOOM! Can't read from this accessor.
249 sub mk_wo_accessors
{
250 my($self, @fields) = @_;
252 $self->_mk_accessors('wo', @fields);
257 An accessor generated by Class::Accessor looks something like
264 return $self->set('foo', @_);
267 return $self->get('foo');
271 Very simple. All it does is determine if you're wanting to set a
272 value or get a value and calls the appropriate method.
273 Class::Accessor provides default get() and set() methods which
274 your class can override. They're detailed later.
276 =head2 follow_best_practice
278 In Damian's Perl Best Practices book he recommends separate get and set methods
279 with the prefix set_ and get_ to make it explicit what you intend to do. If you
280 want to create those accessor methods instead of the default ones, call:
282 __PACKAGE__->follow_best_practice
284 =head2 accessor_name_for / mutator_name_for
286 You may have your own crazy ideas for the names of the accessors, so you can
287 make those happen by overriding C<accessor_name_for> and C<mutator_name_for> in
288 your subclass. (I copied that idea from Class::DBI.)
292 sub best_practice_accessor_name_for
{
293 my ($class, $field) = @_;
297 sub best_practice_mutator_name_for
{
298 my ($class, $field) = @_;
302 sub accessor_name_for
{
303 my ($class, $field) = @_;
307 sub mutator_name_for
{
308 my ($class, $field) = @_;
312 =head2 Modifying the behavior of the accessor
314 Rather than actually modifying the accessor itself, it is much more
315 sensible to simply override the two key methods which the accessor
316 calls. Namely set() and get().
318 If you -really- want to, you can override make_accessor().
322 $obj->set($key, $value);
323 $obj->set($key, @values);
325 set() defines how generally one stores data in the object.
327 override this method to change how data is stored by your accessors.
332 my($self, $key) = splice(@_, 0, 2);
335 $self->{$key} = $_[0];
338 $self->{$key} = [@_];
341 $self->_croak("Wrong number of arguments received");
347 $value = $obj->get($key);
348 @values = $obj->get(@keys);
350 get() defines how data is retreived from your objects.
352 override this method to change how it is retreived.
360 return $self->{$_[0]};
366 $self->_croak("Wrong number of arguments received");
372 $accessor = Class->make_accessor($field);
374 Generates a subroutine reference which acts as an accessor for the given
375 $field. It calls get() and set().
377 If you wish to change the behavior of your accessors, try overriding
378 get() and set() before you start mucking with make_accessor().
383 my ($class, $field) = @_;
385 # Build a closure around $field.
390 return $self->set($field, @_);
393 return $self->get($field);
398 =head2 make_ro_accessor
400 $read_only_accessor = Class->make_ro_accessor($field);
402 Generates a subroutine refrence which acts as a read-only accessor for
403 the given $field. It only calls get().
405 Override get() to change the behavior of your accessors.
409 sub make_ro_accessor
{
410 my($class, $field) = @_;
417 $self->_croak("'$caller' cannot alter the value of '$field' on objects of class '$class'");
420 return $self->get($field);
425 =head2 make_wo_accessor
427 $read_only_accessor = Class->make_wo_accessor($field);
429 Generates a subroutine refrence which acts as a write-only accessor
430 (mutator) for the given $field. It only calls set().
432 Override set() to change the behavior of your accessors.
436 sub make_wo_accessor
{
437 my($class, $field) = @_;
444 $self->_croak("'$caller' cannot access the value of '$field' on objects of class '$class'");
447 return $self->set($field, @_);
454 If something goes wrong Class::Accessor will warn or die by calling Carp::carp
455 or Carp::croak. If you don't like this you can override _carp() and _croak() in
456 your subclass and do whatever else you want.
463 my ($self, $msg) = @_;
464 Carp
::carp
($msg || $self);
469 my ($self, $msg) = @_;
470 Carp
::croak
($msg || $self);
476 Class::Accessor does not employ an autoloader, thus it is much faster
477 than you'd think. Its generated methods incur no special penalty over
478 ones you'd write yourself.
481 Rate Basic Average Fast Faster Direct
482 Basic 189150/s -- -42% -51% -55% -89%
483 Average 327679/s 73% -- -16% -22% -82%
484 Fast 389212/s 106% 19% -- -8% -78%
485 Faster 421646/s 123% 29% 8% -- -76%
486 Direct 1771243/s 836% 441% 355% 320% --
489 Rate Basic Average Fast Faster Direct
490 Basic 173769/s -- -34% -53% -59% -90%
491 Average 263046/s 51% -- -29% -38% -85%
492 Fast 371158/s 114% 41% -- -13% -78%
493 Faster 425821/s 145% 62% 15% -- -75%
494 Direct 1699081/s 878% 546% 358% 299% --
496 Class::Accessor::Fast is faster than methods written by an average programmer
497 (where "average" is based on Schwern's example code).
499 Class::Accessor is slower than average, but more flexible.
501 Class::Accessor::Faster is even faster than Class::Accessor::Fast. It uses an
502 array internally, not a hash. This could be a good or bad feature depending on
505 Direct hash access is, of course, much faster than all of these, but it
506 provides no encapsulation.
508 Of course, its not as simple as saying "Class::Accessor is slower than
509 average". These are benchmarks for a simple accessor. If your accessors do
510 any sort of complicated work (such as talking to a database or writing to a
511 file) the time spent doing that work will quickly swamp the time spend just
512 calling the accessor. In that case, Class::Accessor and the ones you write
513 will be roughly the same speed.
518 Here's an example of generating an accessor for every public field of
523 use base qw(Class::Accessor Class::Fields);
524 use fields qw(curiously strong mints);
525 Altoids->mk_accessors( Altoids->show_fields('Public') );
529 my $class = ref $proto || $proto;
530 return fields::new($class);
533 my Altoids $tin = Altoids->new;
535 $tin->curiously('Curiouser and curiouser');
536 print $tin->{curiously}; # prints 'Curiouser and curiouser'
539 # Subclassing works, too.
541 use base qw(Altoids);
543 my Mint::Snuff $pouch = Mint::Snuff->new;
544 $pouch->strong('Blow your head off!');
545 print $pouch->{strong}; # prints 'Blow your head off!'
548 Here's a simple example of altering the behavior of your accessors.
551 use base qw(Class::Accessor);
552 Foo->mk_accessor(qw(this that up down));
557 # Note every time someone gets some data.
558 print STDERR "Getting @_\n";
560 $self->SUPER::get(@_);
564 my ($self, $key) = splice(@_, 0, 2);
566 # Note every time someone sets some data.
567 print STDERR "Setting $key to @_\n";
569 $self->SUPER::set($key, @_);
573 =head1 CAVEATS AND TRICKS
575 Class::Accessor has to do some internal wackiness to get its
576 job done quickly and efficiently. Because of this, there's a few
577 tricks and traps one must know about.
579 Hey, nothing's perfect.
581 =head2 Don't make a field called DESTROY
583 This is bad. Since DESTROY is a magical method it would be bad for us
584 to define an accessor using that name. Class::Accessor will
585 carp if you try to use it with a field named "DESTROY".
587 =head2 Overriding autogenerated accessors
589 You may want to override the autogenerated accessor with your own, yet
590 have your custom accessor call the default one. For instance, maybe
591 you want to have an accessor which checks its input. Normally, one
592 would expect this to work:
595 use base qw(Class::Accessor);
596 Foo->mk_accessors(qw(email this that whatever));
598 # Only accept addresses which look valid.
604 require Email::Valid;
605 unless( Email::Valid->address($email) ) {
606 carp("$email doesn't look like a valid address.");
611 return $self->SUPER::email(@_);
614 There's a subtle problem in the last example, and its in this line:
616 return $self->SUPER::email(@_);
618 If we look at how Foo was defined, it called mk_accessors() which
619 stuck email() right into Foo's namespace. There *is* no
620 SUPER::email() to delegate to! Two ways around this... first is to
621 make a "pure" base class for Foo. This pure class will generate the
622 accessors and provide the necessary super class for Foo to use:
624 package Pure::Organic::Foo;
625 use base qw(Class::Accessor);
626 Pure::Organic::Foo->mk_accessors(qw(email this that whatever));
629 use base qw(Pure::Organic::Foo);
631 And now Foo::email() can override the generated
632 Pure::Organic::Foo::email() and use it as SUPER::email().
634 This is probably the most obvious solution to everyone but me.
635 Instead, what first made sense to me was for mk_accessors() to define
636 an alias of email(), _email_accessor(). Using this solution,
637 Foo::email() would be written with:
639 return $self->_email_accessor(@_);
641 instead of the expected SUPER::email().
646 Copyright 2007 Marty Pauley <marty+perl@kasei.com>
648 This program is free software; you can redistribute it and/or modify it under
649 the same terms as Perl itself. That means either (a) the GNU General Public
650 License or (b) the Artistic License.
652 =head2 ORIGINAL AUTHOR
654 Michael G Schwern <schwern@pobox.com>
658 Liz and RUZ for performance tweaks.
660 Tels, for his big feature request/bug report.
665 L<Class::Accessor::Fast>
667 These are some modules which do similar things in different ways
668 L<Class::Struct>, L<Class::Methodmaker>, L<Class::Generate>,
669 L<Class::Class>, L<Class::Contract>
671 L<Class::DBI> for an example of this module in use.