1Object::Accessor(3pm) Perl Programmers Reference Guide Object::Accessor(3pm)
2
6 Object::Accessor - interface to create per object accessors
7
9 ### using the object
10 $obj = Object::Accessor->new; # create object
11 $obj = Object::Accessor->new(@list); # create object with accessors
12 $obj = Object::Accessor->new(\%h); # create object with accessors
13 # and their allow handlers
14 $bool = $obj->mk_accessors('foo'); # create accessors
16 $bool = $obj->mk_accessors( # create accessors with input
17 {foo => ALLOW_HANDLER} ); # validation
18 $bool = $obj->mk_aliases( # create an alias to an existing
20 alias_name => 'method'); # method name
21 $clone = $obj->mk_clone; # create a clone of original
23 # object without data
24 $bool = $obj->mk_flush; # clean out all data
25 @list = $obj->ls_accessors; # retrieves a list of all
27 # accessors for this object
28 $bar = $obj->foo('bar'); # set 'foo' to 'bar'
30 $bar = $obj->foo(); # retrieve 'bar' again
31 $sub = $obj->can('foo'); # retrieve coderef for
33 # 'foo' accessor
34 $bar = $sub->('bar'); # set 'foo' via coderef
35 $bar = $sub->(); # retrieve 'bar' by coderef
36 ### using the object as base class
38 package My::Class;
39 use base 'Object::Accessor';
40 $obj = My::Class->new; # create base object
42 $bool = $obj->mk_accessors('foo'); # create accessors, etc...
43 ### make all attempted access to non-existent accessors fatal
45 ### (defaults to false)
46 $Object::Accessor::FATAL = 1;
47 ### enable debugging
49 $Object::Accessor::DEBUG = 1;
50 ### advanced usage -- callbacks
52 { my $obj = Object::Accessor->new('foo');
53 $obj->register_callback( sub { ... } );
54 $obj->foo( 1 ); # these calls invoke the callback you registered
56 $obj->foo() # which allows you to change the get/set
57 # behaviour and what is returned to the caller.
58 }
59 ### advanced usage -- lvalue attributes
61 { my $obj = Object::Accessor::Lvalue->new('foo');
62 print $obj->foo = 1; # will print 1
63 }
64 ### advanced usage -- scoped attribute values
66 { my $obj = Object::Accessor->new('foo');
67 $obj->foo( 1 );
69 print $obj->foo; # will print 1
70 ### bind the scope of the value of attribute 'foo'
72 ### to the scope of '$x' -- when $x goes out of
73 ### scope, 'foo's previous value will be restored
74 { $obj->foo( 2 => \my $x );
75 print $obj->foo, ' ', $x; # will print '2 2'
76 }
77 print $obj->foo; # will print 1
78 }
79
81 "Object::Accessor" provides an interface to create per object accessors
82 (as opposed to per "Class" accessors, as, for example,
83 "Class::Accessor" provides).
84 You can choose to either subclass this module, and thus using its
86 accessors on your own module, or to store an "Object::Accessor" object
87 inside your own object, and access the accessors from there. See the
88 "SYNOPSIS" for examples.
89
91 $object = Object::Accessor->new( [ARGS] );
92 Creates a new (and empty) "Object::Accessor" object. This method is
93 inheritable.
94 Any arguments given to "new" are passed straight to "mk_accessors".
96 If you want to be able to assign to your accessors as if they were
98 "lvalue"s, you should create your object in the
99 "Object::Accessor::Lvalue" namespace instead. See the section on
100 "LVALUE ACCESSORS" below.
101 $bool = $object->mk_accessors( @ACCESSORS | \%ACCESSOR_MAP );
103 Creates a list of accessors for this object (and "NOT" for other ones
104 in the same class!). Will not clobber existing data, so if an accessor
105 already exists, requesting to create again is effectively a "no-op".
106 When providing a "hashref" as argument, rather than a normal list, you
108 can specify a list of key/value pairs of accessors and their respective
109 input validators. The validators can be anything that "Params::Check"'s
110 "allow" function accepts. Please see its manpage for details.
111 For example:
113 $object->mk_accessors( {
115 foo => qr/^\d+$/, # digits only
116 bar => [0,1], # booleans
117 zot => \&my_sub # a custom verification sub
118 } );
119 Returns true on success, false on failure.
121 Accessors that are called on an object, that do not exist return
123 "undef" by default, but you can make this a fatal error by setting the
124 global variable $FATAL to true. See the section on "GLOBAL VARIABLES"
125 for details.
126 Note that you can bind the values of attributes to a scope. This allows
128 you to "temporarily" change a value of an attribute, and have it's
129 original value restored up on the end of it's bound variable's scope;
130 For example, in this snippet of code, the attribute "foo" will
132 temporarily be set to 2, until the end of the scope of $x, at which
133 point the original value of 1 will be restored.
134 my $obj = Object::Accessor->new;
136 $obj->mk_accessors('foo');
138 $obj->foo( 1 );
139 print $obj->foo; # will print 1
140 ### bind the scope of the value of attribute 'foo'
142 ### to the scope of '$x' -- when $x goes out of
143 ### scope, 'foo' previous value will be restored
144 { $obj->foo( 2 => \my $x );
145 print $obj->foo, ' ', $x; # will print '2 2'
146 }
147 print $obj->foo; # will print 1
148 Note that all accessors are read/write for everyone. See the "TODO"
150 section for details.
151 @list = $self->ls_accessors;
153 Returns a list of accessors that are supported by the current object.
154 The corresponding coderefs can be retrieved by passing this list one by
155 one to the "can" method.
156 $ref = $self->ls_allow(KEY)
158 Returns the allow handler for the given key, which can be used with
159 "Params::Check"'s "allow()" handler. If there was no allow handler
160 specified, an allow handler that always returns true will be returned.
161 $bool = $self->mk_aliases( alias => method, [alias2 => method2, ...] );
163 Creates an alias for a given method name. For all intents and purposes,
164 these two accessors are now identical for this object. This is akin to
165 doing the following on the symbol table level:
166 *alias = *method
168 This allows you to do the following:
170 $self->mk_accessors('foo');
172 $self->mk_aliases( bar => 'foo' );
173 $self->bar( 42 );
175 print $self->foo; # will print 42
176 $clone = $self->mk_clone;
178 Makes a clone of the current object, which will have the exact same
179 accessors as the current object, but without the data stored in them.
180 $bool = $self->mk_flush;
182 Flushes all the data from the current object; all accessors will be set
183 back to their default state of "undef".
184 Returns true on success and false on failure.
186 $bool = $self->mk_verify;
188 Checks if all values in the current object are in accordance with their
189 own allow handler. Specifically useful to check if an empty initialised
190 object has been filled with values satisfying their own allow criteria.
191 $bool = $self->register_callback( sub { ... } );
193 This method allows you to register a callback, that is invoked every
194 time an accessor is called. This allows you to munge input data, access
195 external data stores, etc.
196 You are free to return whatever you wish. On a "set" call, the data is
198 even stored in the object.
199 Below is an example of the use of a callback.
201 $object->some_method( "some_value" );
203 my $callback = sub {
205 my $self = shift; # the object
206 my $meth = shift; # "some_method"
207 my $val = shift; # ["some_value"]
208 # could be undef -- check 'exists';
209 # if scalar @$val is empty, it was a 'get'
210 # your code here
212 return $new_val; # the value you want to be set/returned
214 }
215 To access the values stored in the object, circumventing the callback
217 structure, you should use the "___get" and "___set" methods documented
218 further down.
219 $bool = $self->can( METHOD_NAME )
221 This method overrides "UNIVERAL::can" in order to provide coderefs to
222 accessors which are loaded on demand. It will behave just like
223 "UNIVERSAL::can" where it can -- returning a class method if it exists,
224 or a closure pointing to a valid accessor of this particular object.
225 You can use it as follows:
227 $sub = $object->can('some_accessor'); # retrieve the coderef
229 $sub->('foo'); # 'some_accessor' now set
230 # to 'foo' for $object
231 $foo = $sub->(); # retrieve the contents
232 # of 'some_accessor'
233 See the "SYNOPSIS" for more examples.
235 $val = $self->___get( METHOD_NAME );
237 Method to directly access the value of the given accessor in the
238 object. It circumvents all calls to allow checks, callbacks, etc.
239 Use only if you "Know What You Are Doing"! General usage for this
241 functionality would be in your own custom callbacks.
242 $bool = $self->___set( METHOD_NAME => VALUE );
244 Method to directly set the value of the given accessor in the object.
245 It circumvents all calls to allow checks, callbacks, etc.
246 Use only if you "Know What You Are Doing"! General usage for this
248 functionality would be in your own custom callbacks.
249 $bool = $self->___alias( ALIAS => METHOD );
251 Method to directly alias one accessor to another for this object. It
252 circumvents all sanity checks, etc.
253 Use only if you "Know What You Are Doing"!
255
257 "Object::Accessor" supports "lvalue" attributes as well. To enable
258 these, you should create your objects in the designated namespace,
259 "Object::Accessor::Lvalue". For example:
260 my $obj = Object::Accessor::Lvalue->new('foo');
262 $obj->foo += 1;
263 print $obj->foo;
264 will actually print 1 and work as expected. Since this is an optional
266 feature, that's not desirable in all cases, we require you to
267 explicitly use the "Object::Accessor::Lvalue" class.
268 Doing the same on the standard "Object">Accessor> class would generate
270 the following code & errors:
271 my $obj = Object::Accessor->new('foo');
273 $obj->foo += 1;
274 Can't modify non-lvalue subroutine call
276 Note that "lvalue" support on "AUTOLOAD" routines is a "perl 5.8.x"
278 feature. See perldoc perl58delta for details.
279 CAVEATS
281 · Allow handlers
282 Due to the nature of "lvalue subs", we never get access to the
284 value you are assigning, so we can not check it against your allow
285 handler. Allow handlers are therefor unsupported under "lvalue"
286 conditions.
287 See "perldoc perlsub" for details.
289 · Callbacks
291 Due to the nature of "lvalue subs", we never get access to the
293 value you are assigning, so we can not check provide this value to
294 your callback. Furthermore, we can not distinguish between a "get"
295 and a "set" call. Callbacks are therefor unsupported under "lvalue"
296 conditions.
297 See "perldoc perlsub" for details.
299
301 $Object::Accessor::FATAL
302 Set this variable to true to make all attempted access to non-existent
303 accessors be fatal. This defaults to "false".
304 $Object::Accessor::DEBUG
306 Set this variable to enable debugging output. This defaults to
307 "false".
308
310 Create read-only accessors
311 Currently all accessors are read/write for everyone. Perhaps a future
312 release should make it possible to have read-only accessors as well.
313
315 If you use codereferences for your allow handlers, you will not be able
316 to freeze the data structures using "Storable".
317 Due to a bug in storable (until at least version 2.15), "qr//" compiled
319 regexes also don't de-serialize properly. Although this bug has been
320 reported, you should be aware of this issue when serializing your
321 objects.
322 You can track the bug here:
324 http://rt.cpan.org/Ticket/Display.html?id=1827
326
328 Please report bugs or other issues to
329 <bug-object-accessor@rt.cpan.org>.
330
332 This module by Jos Boumans <kane@cpan.org>.
333
335 This library is free software; you may redistribute and/or modify it
336 under the same terms as Perl itself.
337perl v5.16.3 2013-03-04 Object::Accessor(3pm)