1Object::Accessor(3) User Contributed Perl Documentation Object::Accessor(3)
2
6 Object::Accessor
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 $clone = $obj->mk_clone; # create a clone of original
20 # object without data
21 $bool = $obj->mk_flush; # clean out all data
22 @list = $obj->ls_accessors; # retrieves a list of all
24 # accessors for this object
25 $bar = $obj->foo('bar'); # set 'foo' to 'bar'
27 $bar = $obj->foo(); # retrieve 'bar' again
28 $sub = $obj->can('foo'); # retrieve coderef for
30 # 'foo' accessor
31 $bar = $sub->('bar'); # set 'foo' via coderef
32 $bar = $sub->(); # retrieve 'bar' by coderef
33 ### using the object as base class
35 package My::Class;
36 use base 'Object::Accessor';
37 $obj = My::Class->new; # create base object
39 $bool = $obj->mk_accessors('foo'); # create accessors, etc...
40 ### make all attempted access to non-existant accessors fatal
42 ### (defaults to false)
43 $Object::Accessor::FATAL = 1;
44 ### enable debugging
46 $Object::Accessor::DEBUG = 1;
47 ### advanced usage -- callbacks
49 { my $obj = Object::Accessor->new('foo');
50 $obj->register_callback( sub { ... } );
51 $obj->foo( 1 ); # these calls invoke the callback you registered
53 $obj->foo() # which allows you to change the get/set
54 # behaviour and what is returned to the caller.
55 }
56 ### advanced usage -- lvalue attributes
58 { my $obj = Object::Accessor::Lvalue->new('foo');
59 print $obj->foo = 1; # will print 1
60 }
61 ### advanced usage -- scoped attribute values
63 { my $obj = Object::Accessor->new('foo');
64 $obj->foo( 1 );
66 print $obj->foo; # will print 1
67 ### bind the scope of the value of attribute 'foo'
69 ### to the scope of '$x' -- when $x goes out of
70 ### scope, 'foo's previous value will be restored
71 { $obj->foo( 2 => \my $x );
72 print $obj->foo, ' ', $x; # will print '2 2'
73 }
74 print $obj->foo; # will print 1
75 }
76
78 "Object::Accessor" provides an interface to create per object accessors
79 (as opposed to per "Class" accessors, as, for example, "Class::Acces‐
80 sor" provides).
81 You can choose to either subclass this module, and thus using its
83 accessors on your own module, or to store an "Object::Accessor" object
84 inside your own object, and access the accessors from there. See the
85 "SYNOPSIS" for examples.
86
88 $object = Object::Accessor->new( [ARGS] );
89 Creates a new (and empty) "Object::Accessor" object. This method is
91 inheritable.
92 Any arguments given to "new" are passed straight to "mk_accessors".
94 If you want to be able to assign to your accessors as if they were
96 "lvalue"s, you should create your object in the "Object::Accces‐
97 sor::Lvalue" namespace instead. See the section on "LVALUE ACCESSORS"
98 below.
99 $bool = $object->mk_accessors( @ACCESSORS ⎪ \%ACCESSOR_MAP );
101 Creates a list of accessors for this object (and "NOT" for other ones
103 in the same class!). Will not clobber existing data, so if an accessor
104 already exists, requesting to create again is effectively a "no-op".
105 When providing a "hashref" as argument, rather than a normal list, you
107 can specify a list of key/value pairs of accessors and their respective
108 input validators. The validators can be anything that "Params::Check"'s
109 "allow" function accepts. Please see its manpage for details.
110 For example:
112 $object->mk_accessors( {
114 foo => qr/^\d+$/, # digits only
115 bar => [0,1], # booleans
116 zot => \&my_sub # a custom verification sub
117 } );
118 Returns true on success, false on failure.
120 Accessors that are called on an object, that do not exist return
122 "undef" by default, but you can make this a fatal error by setting the
123 global variable $FATAL to true. See the section on "GLOBAL VARIABLES"
124 for details.
125 Note that you can bind the values of attributes to a scope. This allows
127 you to "temporarily" change a value of an attribute, and have it's
128 original value restored up on the end of it's bound variable's scope;
129 For example, in this snippet of code, the attribute "foo" will tempo‐
131 rarily be set to 2, until the end of the scope of $x, at which point
132 the original value of 1 will be restored.
133 my $obj = Object::Accessor->new;
135 $obj->mk_accessors('foo');
137 $obj->foo( 1 );
138 print $obj->foo; # will print 1
139 ### bind the scope of the value of attribute 'foo'
141 ### to the scope of '$x' -- when $x goes out of
142 ### scope, 'foo' previous value will be restored
143 { $obj->foo( 2 => \my $x );
144 print $obj->foo, ' ', $x; # will print '2 2'
145 }
146 print $obj->foo; # will print 1
147 Note that all accessors are read/write for everyone. See the "TODO"
149 section for details.
150 @list = $self->ls_accessors;
152 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
160 "Params::Check"'s "allow()" handler. If there was no allow handler
161 specified, an allow handler that always returns true will be returned.
162 $clone = $self->mk_clone;
164 Makes a clone of the current object, which will have the exact same
166 accessors as the current object, but without the data stored in them.
167 $bool = $self->mk_flush;
169 Flushes all the data from the current object; all accessors will be set
171 back to their default state of "undef".
172 Returns true on success and false on failure.
174 $bool = $self->mk_verify;
176 Checks if all values in the current object are in accordance with their
178 own allow handler. Specifically useful to check if an empty initialised
179 object has been filled with values satisfying their own allow criteria.
180 $bool = $self->register_callback( sub { ... } );
182 This method allows you to register a callback, that is invoked every
184 time an accessor is called. This allows you to munge input data, access
185 external data stores, etc.
186 You are free to return whatever you wish. On a "set" call, the data is
188 even stored in the object.
189 Below is an example of the use of a callback.
191 $object->some_method( "some_value" );
193 my $callback = sub {
195 my $self = shift; # the object
196 my $meth = shift; # "some_method"
197 my $val = shift; # ["some_value"]
198 # could be undef -- check 'exists';
199 # if scalar @$val is empty, it was a 'get'
200 # your code here
202 return $new_val; # the value you want to be set/returned
204 }
205 To access the values stored in the object, circumventing the callback
207 structure, you should use the "___get" and "___set" methods documented
208 further down.
209 $bool = $self->can( METHOD_NAME )
211 This method overrides "UNIVERAL::can" in order to provide coderefs to
213 accessors which are loaded on demand. It will behave just like "UNIVER‐
214 SAL::can" where it can -- returning a class method if it exists, or a
215 closure pointing to a valid accessor of this particular object.
216 You can use it as follows:
218 $sub = $object->can('some_accessor'); # retrieve the coderef
220 $sub->('foo'); # 'some_accessor' now set
221 # to 'foo' for $object
222 $foo = $sub->(); # retrieve the contents
223 # of 'some_accessor'
224 See the "SYNOPSIS" for more examples.
226 $val = $self->___get( METHOD_NAME );
228 Method to directly access the value of the given accessor in the
230 object. It circumvents all calls to allow checks, callbakcs, etc.
231 Use only if you "Know What You Are Doing"! General usage for this func‐
233 tionality would be in your own custom callbacks.
234 $bool = $self->___set( METHOD_NAME => VALUE );
236 Method to directly set the value of the given accessor in the object.
238 It circumvents all calls to allow checks, callbakcs, etc.
239 Use only if you "Know What You Are Doing"! General usage for this func‐
241 tionality would be in your own custom callbacks.
242
244 "Object::Accessor" supports "lvalue" attributes as well. To enable
245 these, you should create your objects in the designated namespace,
246 "Object::Accessor::Lvalue". For example:
247 my $obj = Object::Accessor::Lvalue->new('foo');
249 $obj->foo += 1;
250 print $obj->foo;
251 will actually print 1 and work as expected. Since this is an optional
253 feature, that's not desirable in all cases, we require you to explic‐
254 itly use the "Object::Accessor::Lvalue" class.
255 Doing the same on the standard "Object">Accessor> class would generate
257 the following code & errors:
258 my $obj = Object::Accessor->new('foo');
260 $obj->foo += 1;
261 Can't modify non-lvalue subroutine call
263 Note that "lvalue" support on "AUTOLOAD" routines is a "perl 5.8.x"
265 feature. See perldoc perl58delta for details.
266 CAVEATS
268 * Allow handlers
270 Due to the nature of "lvalue subs", we never get access to the
271 value you are assigning, so we can not check it againt your allow
272 handler. Allow handlers are therefor unsupported under "lvalue"
273 conditions.
274 See "perldoc perlsub" for details.
276 * Callbacks
278 Due to the nature of "lvalue subs", we never get access to the
279 value you are assigning, so we can not check provide this value to
280 your callback. Furthermore, we can not distinguish between a "get"
281 and a "set" call. Callbacks are therefor unsupported under "lvalue"
282 conditions.
283 See "perldoc perlsub" for details.
285
287 $Object::Accessor::FATAL
288 Set this variable to true to make all attempted access to non-existant
290 accessors be fatal. This defaults to "false".
291 $Object::Accessor::DEBUG
293 Set this variable to enable debugging output. This defaults to
295 "false".
296
298 Create read-only accessors
299 Currently all accessors are read/write for everyone. Perhaps a future
301 release should make it possible to have read-only accessors as well.
302
304 If you use codereferences for your allow handlers, you will not be able
305 to freeze the data structures using "Storable".
306 Due to a bug in storable (until at least version 2.15), "qr//" compiled
308 regexes also don't de-serialize properly. Although this bug has been
309 reported, you should be aware of this issue when serializing your
310 objects.
311 You can track the bug here:
313 http://rt.cpan.org/Ticket/Display.html?id=1827
315
317 This module by Jos Boumans <kane@cpan.org>.
318
320 This module is copyright (c) 2004-2005 Jos Boumans <kane@cpan.org>.
321 All rights reserved.
322 This library is free software; you may redistribute and/or modify it
324 under the same terms as Perl itself.
325perl v5.8.8 2006-10-05 Object::Accessor(3)