accessors(3pm)

1accessors(3)          User Contributed Perl Documentation         accessors(3)
2
3
4

NAME

6       accessors - create accessor methods in caller's package.
7

SYNOPSIS

9         package Foo;
10         use accessors qw( foo bar baz );
11
12         my $obj = bless {}, 'Foo';
13
14         # generates chaining accessors
15         # that you can set like this:
16         $obj->foo( 'hello ' )
17             ->bar( 'world' )
18             ->baz( "!\n" );
19
20         # you get the values by passing no params:
21         print $obj->foo, $obj->bar, $obj->baz;
22

DESCRIPTION

24       The accessors pragma lets you create simple accessors at compile-time.
25
26       This saves you from writing them by hand, which tends to result in cut-
27       n-paste errors and a mess of duplicated code.  It can also help you
28       reduce the ammount of unwanted direct-variable access that may creep
29       into your codebase when you're feeling lazy.  accessors was designed
30       with laziness in mind.
31
32       Method-chaining accessors are generated by default.  Note that you can
33       still use accessors::chained directly for reasons of backwards
34       compatability.
35
36       See accessors::classic for accessors that always return the current
37       value if you don't like method chaining.
38

GENERATED METHODS

40       accessors will generate methods that return the current object on set:
41
42         sub foo {
43             my $self = shift;
44             if (@_) { $self->{-foo} = shift; return $self; }
45             else    { return $self->{-foo}; }
46         }
47
48       This way they can be chained together.
49
50   Why prepend the dash?
51       The dash ("-") is prepended to the property name for a few reasons:
52
53       •   interoperability with Error.
54
55       •   to make it difficult to accidentally access the property directly
56           ala:
57
58             use accessors qw( foo );
59             $obj->{foo};  # prevents this by mistake
60             $obj->foo;    # when you probably meant this
61
62           (this might sound woolly, but it's easy enough to do).
63
64       •   syntactic sugar (this is woolly :).
65
66       You shouldn't care too much about how the property is stored anyway -
67       if you do, you're likely trying to do something special (and should
68       really consider writing the accessors out long hand), or it's simply a
69       matter of preference in which case you can use accessors::classic, or
70       sub-class this module.
71

PERFORMANCE

73       There is little-to-no performace hit when using generated accessors; in
74       fact there is usually a performance gain.
75
76       •   typically 10-30% faster than hard-coded accessors (like the above
77           example).
78
79       •   typically 1-15% slower than optimized accessors (less readable).
80
81       •   typically a small performance hit at startup (accessors are created
82           at compile-time).
83
84       •   uses the same anonymous sub to reduce memory consumption (sometimes
85           by 80%).
86
87       See the benchmark tests included with this distribution for more
88       details.
89

MOTIVATION

91       The main difference between the accessors pragma and other accessor
92       generators is simplicity.
93
94       •   interface
95
96           use accessors qw( ... ) is as easy as it gets.
97
98       •   a pragma
99
100           it fits in nicely with the base pragma:
101
102             use base      qw( Some::Class );
103             use accessors qw( foo bar baz );
104
105           and accessors get created at compile-time.
106
107       •   no bells and whistles
108
109           The module is extensible instead.
110

SUB-CLASSING

112       If you prefer a different style of accessor or you need to do something
113       more complicated, there's nothing to stop you from sub-classing.  It
114       should be pretty easy.  Look through accessors::classic, accessors::ro,
115       and accessors::rw to see how it's done.
116

CAVEATS

118       Classes using blessed scalarrefs, arrayrefs, etc. are not supported for
119       sake of simplicity.  Only hashrefs are supported.
120

THANKS

122       Thanks to Michael G. Schwern for indirectly inspiring this module, and
123       for his feedback & suggestions.
124
125       Also to Paul Makepeace and David Wright for showing me faster
126       accessors, to chocolateboy for his contributions, the CPAN Testers for
127       their bug reports, and to James Duncan and people on London.pm for
128       their feedback.
129

AUTHOR

131       Steve Purkis <spurkis@cpan.org>
132