1Object::Accessor(3pm)  Perl Programmers Reference Guide  Object::Accessor(3pm)
2
3
4

NAME

6       Object::Accessor
7

SYNOPSIS

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
15           $bool   = $obj->mk_accessors('foo'); # create accessors
16           $bool   = $obj->mk_accessors(        # create accessors with input
17                      {foo => ALLOW_HANDLER} ); # validation
18
19           $bool   = $obj->mk_aliases(          # create an alias to an existing
20                       alias_name => 'method'); # method name
21
22           $clone  = $obj->mk_clone;            # create a clone of original
23                                                # object without data
24           $bool   = $obj->mk_flush;            # clean out all data
25
26           @list   = $obj->ls_accessors;        # retrieves a list of all
27                                                # accessors for this object
28
29           $bar    = $obj->foo('bar');          # set 'foo' to 'bar'
30           $bar    = $obj->foo();               # retrieve 'bar' again
31
32           $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
37           ### using the object as base class
38           package My::Class;
39           use base 'Object::Accessor';
40
41           $obj    = My::Class->new;               # create base object
42           $bool   = $obj->mk_accessors('foo');    # create accessors, etc...
43
44           ### make all attempted access to non-existant accessors fatal
45           ### (defaults to false)
46           $Object::Accessor::FATAL = 1;
47
48           ### enable debugging
49           $Object::Accessor::DEBUG = 1;
50
51           ### advanced usage -- callbacks
52           {   my $obj = Object::Accessor->new('foo');
53               $obj->register_callback( sub { ... } );
54
55               $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
60           ### advanced usage -- lvalue attributes
61           {   my $obj = Object::Accessor::Lvalue->new('foo');
62               print $obj->foo = 1;            # will print 1
63           }
64
65           ### advanced usage -- scoped attribute values
66           {   my $obj = Object::Accessor->new('foo');
67
68               $obj->foo( 1 );
69               print $obj->foo;                # will print 1
70
71               ### 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

DESCRIPTION

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
85       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

METHODS

91   $object = Object::Accessor->new( [ARGS] );
92       Creates a new (and empty) "Object::Accessor" object. This method is
93       inheritable.
94
95       Any arguments given to "new" are passed straight to "mk_accessors".
96
97       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::Acccessor::Lvalue" namespace instead. See the section on
100       "LVALUE ACCESSORS" below.
101
102   $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
107       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
112       For example:
113
114           $object->mk_accessors( {
115               foo     => qr/^\d+$/,       # digits only
116               bar     => [0,1],           # booleans
117               zot     => \&my_sub         # a custom verification sub
118           } );
119
120       Returns true on success, false on failure.
121
122       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
127       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
131       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
135           my $obj = Object::Accessor->new;
136
137           $obj->mk_accessors('foo');
138           $obj->foo( 1 );
139           print $obj->foo;                # will print 1
140
141           ### 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
149       Note that all accessors are read/write for everyone. See the "TODO"
150       section for details.
151
152   @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
157   $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
162   $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
167         *alias = *method
168
169       This allows you to do the following:
170
171         $self->mk_accessors('foo');
172         $self->mk_aliases( bar => 'foo' );
173
174         $self->bar( 42 );
175         print $self->foo;     # will print 42
176
177   $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
181   $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
185       Returns true on success and false on failure.
186
187   $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
192   $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
197       You are free to return whatever you wish. On a "set" call, the data is
198       even stored in the object.
199
200       Below is an example of the use of a callback.
201
202           $object->some_method( "some_value" );
203
204           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
211               # your code here
212
213               return $new_val;     # the value you want to be set/returned
214           }
215
216       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
220   $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
226       You can use it as follows:
227
228           $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
234       See the "SYNOPSIS" for more examples.
235
236   $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, callbakcs, etc.
239
240       Use only if you "Know What You Are Doing"! General usage for this
241       functionality would be in your own custom callbacks.
242
243   $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, callbakcs, etc.
246
247       Use only if you "Know What You Are Doing"! General usage for this
248       functionality would be in your own custom callbacks.
249
250   $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
254       Use only if you "Know What You Are Doing"!
255

LVALUE ACCESSORS

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
261           my $obj = Object::Accessor::Lvalue->new('foo');
262           $obj->foo += 1;
263           print $obj->foo;
264
265       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
269       Doing the same on the standard "Object">Accessor> class would generate
270       the following code & errors:
271
272           my $obj = Object::Accessor->new('foo');
273           $obj->foo += 1;
274
275           Can't modify non-lvalue subroutine call
276
277       Note that "lvalue" support on "AUTOLOAD" routines is a "perl 5.8.x"
278       feature. See perldoc perl58delta for details.
279
280   CAVEATS
281       ·   Allow handlers
282
283           Due to the nature of "lvalue subs", we never get access to the
284           value you are assigning, so we can not check it againt your allow
285           handler. Allow handlers are therefor unsupported under "lvalue"
286           conditions.
287
288           See "perldoc perlsub" for details.
289
290       ·   Callbacks
291
292           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
298           See "perldoc perlsub" for details.
299

GLOBAL VARIABLES

301   $Object::Accessor::FATAL
302       Set this variable to true to make all attempted access to non-existant
303       accessors be fatal.  This defaults to "false".
304
305   $Object::Accessor::DEBUG
306       Set this variable to enable debugging output.  This defaults to
307       "false".
308

TODO

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

CAVEATS

315       If you use codereferences for your allow handlers, you will not be able
316       to freeze the data structures using "Storable".
317
318       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
323       You can track the bug here:
324
325           http://rt.cpan.org/Ticket/Display.html?id=1827
326

BUG REPORTS

328       Please report bugs or other issues to
329       <bug-object-accessor@rt.cpan.org>.
330

AUTHOR

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.
337
338
339
340perl v5.10.1                      2009-02-12             Object::Accessor(3pm)
Impressum