README
1NAME
2 accessors - create accessor methods in caller's package.
3
4SYNOPSIS
5 package Foo;
6 use accessors qw( foo bar baz );
7
8 my $obj = bless {}, 'Foo';
9
10 # generates chaining accessors
11 # that you can set like this:
12 $obj->foo( 'hello ' )
13 ->bar( 'world' )
14 ->baz( "!\n" );
15
16 # you get the values by passing no params:
17 print $obj->foo, $obj->bar, $obj->baz;
18
19DESCRIPTION
20 The accessors pragma lets you create simple accessors at compile-time.
21
22 This saves you from writing them by hand, which tends to result in
23 *cut-n-paste* errors and a mess of duplicated code. It can also help you
24 reduce the ammount of unwanted *direct-variable access* that may creep
25 into your codebase when you're feeling lazy. accessors was designed with
26 laziness in mind.
27
28 Method-chaining accessors are generated by default. Note that you can
29 still use accessors::chained directly for reasons of backwards
30 compatability.
31
32 See accessors::classic for accessors that always return the current
33 value if you don't like method chaining.
34
35GENERATED METHODS
36 accessors will generate methods that return the current object on set:
37
38 sub foo {
39 my $self = shift;
40 if (@_) { $self->{-foo} = shift; return $self; }
41 else { return $self->{-foo}; }
42 }
43
44 This way they can be *chained* together.
45
46 Why prepend the dash?
47 The dash ("-") is prepended to the property name for a few reasons:
48
49 * interoperability with Error.
50
51 * to make it difficult to accidentally access the property directly
52 ala:
53
54 use accessors qw( foo );
55 $obj->{foo}; # prevents this by mistake
56 $obj->foo; # when you probably meant this
57
58 (this might sound woolly, but it's easy enough to do).
59
60 * syntactic sugar (this *is* woolly :).
61
62 You shouldn't care too much about how the property is stored anyway - if
63 you do, you're likely trying to do something special (and should really
64 consider writing the accessors out long hand), or it's simply a matter
65 of preference in which case you can use accessors::classic, or sub-class
66 this module.
67
68PERFORMANCE
69 There is little-to-no performace hit when using generated accessors; in
70 fact there is usually a performance gain.
71
72 * typically *10-30% faster* than hard-coded accessors (like the above
73 example).
74
75 * typically *1-15% slower* than *optimized* accessors (less readable).
76
77 * typically a *small* performance hit at startup (accessors are
78 created at compile-time).
79
80 * uses the same anonymous sub to reduce memory consumption (sometimes
81 by 80%).
82
83 See the benchmark tests included with this distribution for more
84 details.
85
86MOTIVATION
87 The main difference between the accessors pragma and other accessor
88 generators is simplicity.
89
90 * interface
91 use accessors qw( ... ) is as easy as it gets.
92
93 * a pragma
94 it fits in nicely with the base pragma:
95
96 use base qw( Some::Class );
97 use accessors qw( foo bar baz );
98
99 and accessors get created at compile-time.
100
101 * no bells and whistles
102 The module is extensible instead.
103
104SUB-CLASSING
105 If you prefer a different style of accessor or you need to do something
106 more complicated, there's nothing to stop you from sub-classing. It
107 should be pretty easy. Look through accessors::classic, accessors::ro,
108 and accessors::rw to see how it's done.
109
110CAVEATS
111 Classes using blessed scalarrefs, arrayrefs, etc. are not supported for
112 sake of simplicity. Only hashrefs are supported.
113
114THANKS
115 Thanks to Michael G. Schwern for indirectly inspiring this module, and
116 for his feedback & suggestions.
117
118 Also to Paul Makepeace and David Wright for showing me faster accessors,
119 to chocolateboy for his contributions, the CPAN Testers for their bug
120 reports, and to James Duncan and people on London.pm for their feedback.
121
122AUTHOR
123 Steve Purkis <spurkis@cpan.org>
124
125SEE ALSO
126 accessors::classic, accessors::chained
127
128 Similar and related modules:
129
130 base, fields, Class::Accessor, Class::Struct, Class::Methodmaker,
131 Class::Generate, Class::Class, Class::Tangram, Object::Tiny
132
133