1Class::MOP::Attribute(3U)ser Contributed Perl DocumentatiColnass::MOP::Attribute(3)
2
6 Class::MOP::Attribute - Attribute Meta Object
7
9 Class::MOP::Attribute->new(
10 foo => (
11 accessor => 'foo', # dual purpose get/set accessor
12 predicate => 'has_foo', # predicate check for defined-ness
13 init_arg => '-foo', # class->new will look for a -foo key
14 default => 'BAR IS BAZ!' # if no -foo key is provided, use this
15 )
16 );
17 Class::MOP::Attribute->new(
19 bar => (
20 reader => 'bar', # getter
21 writer => 'set_bar', # setter
22 predicate => 'has_bar', # predicate check for defined-ness
23 init_arg => ':bar', # class->new will look for a :bar key
24 # no default value means it is undef
25 )
26 );
27
29 The Attribute Protocol is almost entirely an invention of "Class::MOP".
30 Perl 5 does not have a consistent notion of attributes. There are so
31 many ways in which this is done, and very few (if any) are easily
32 discoverable by this module.
33 With that said, this module attempts to inject some order into this
35 chaos, by introducing a consistent API which can be used to create
36 object attributes.
37
39 Creation
40 Class::MOP::Attribute->new($name, ?%options)
41 An attribute must (at the very least), have a $name. All other
42 %options are added as key-value pairs.
43 · init_arg
45 This is a string value representing the expected key in an
47 initialization hash. For instance, if we have an "init_arg"
48 value of "-foo", then the following code will Just Work.
49 MyClass->meta->new_object( -foo => 'Hello There' );
51 If an init_arg is not assigned, it will automatically use
53 the attribute's name. If "init_arg" is explicitly set to
54 "undef", the attribute cannot be specified during
55 initialization.
56 · builder
58 This provides the name of a method that will be called to
60 initialize the attribute. This method will be called on the
61 object after it is constructed. It is expected to return a
62 valid value for the attribute.
63 · default
65 This can be used to provide an explicit default for
67 initializing the attribute. If the default you provide is a
68 subroutine reference, then this reference will be called as
69 a method on the object.
70 If the value is a simple scalar (string or number), then it
72 can be just passed as is. However, if you wish to
73 initialize it with a HASH or ARRAY ref, then you need to
74 wrap that inside a subroutine reference:
75 Class::MOP::Attribute->new(
77 'foo' => (
78 default => sub { [] },
79 )
80 );
81 # or ...
83 Class::MOP::Attribute->new(
85 'foo' => (
86 default => sub { {} },
87 )
88 );
89 If you wish to initialize an attribute with a subroutine
91 reference itself, then you need to wrap that in a
92 subroutine as well:
93 Class::MOP::Attribute->new(
95 'foo' => (
96 default => sub {
97 sub { print "Hello World" }
98 },
99 )
100 );
101 And lastly, if the value of your attribute is dependent
103 upon some other aspect of the instance structure, then you
104 can take advantage of the fact that when the "default"
105 value is called as a method:
106 Class::MOP::Attribute->new(
108 'object_identity' => (
109 default => sub { Scalar::Util::refaddr( $_[0] ) },
110 )
111 );
112 Note that there is no guarantee that attributes are
114 initialized in any particular order, so you cannot rely on
115 the value of some other attribute when generating the
116 default.
117 · initializer
119 This option can be either a method name or a subroutine
121 reference. This method will be called when setting the
122 attribute's value in the constructor. Unlike "default" and
123 "builder", the initializer is only called when a value is
124 provided to the constructor. The initializer allows you to
125 munge this value during object construction.
126 The initializer is called as a method with three arguments.
128 The first is the value that was passed to the constructor.
129 The second is a subroutine reference that can be called to
130 actually set the attribute's value, and the last is the
131 associated "Class::MOP::Attribute" object.
132 This contrived example shows an initializer that sets the
134 attribute to twice the given value.
135 Class::MOP::Attribute->new(
137 'doubled' => (
138 initializer => sub {
139 my ( $self, $value, $set, $attr ) = @_;
140 $set->( $value * 2 );
141 },
142 )
143 );
144 Since an initializer can be a method name, you can easily
146 make attribute initialization use the writer:
147 Class::MOP::Attribute->new(
149 'some_attr' => (
150 writer => 'some_attr',
151 initializer => 'some_attr',
152 )
153 );
154 Your writer will need to examine @_ and determine under
156 which context it is being called.
157 The "accessor", "reader", "writer", "predicate" and "clearer"
159 options all accept the same parameters. You can provide the name of
160 the method, in which case an appropriate default method will be
161 generated for you. Or instead you can also provide hash reference
162 containing exactly one key (the method name) and one value. The
163 value should be a subroutine reference, which will be installed as
164 the method itself.
165 · accessor
167 An "accessor" is a standard Perl-style read/write accessor.
169 It will return the value of the attribute, and if a value
170 is passed as an argument, it will assign that value to the
171 attribute.
172 Note that "undef" is a legitimate value, so this will work:
174 $object->set_something(undef);
176 · reader
178 This is a basic read-only accessor. It returns the value of
180 the attribute.
181 · writer
183 This is a basic write accessor, it accepts a single
185 argument, and assigns that value to the attribute.
186 Note that "undef" is a legitimate value, so this will work:
188 $object->set_something(undef);
190 · predicate
192 The predicate method returns a boolean indicating whether
194 or not the attribute has been explicitly set.
195 Note that the predicate returns true even if the attribute
197 was set to a false value (0 or "undef").
198 · clearer
200 This method will uninitialize the attribute. After an
202 attribute is cleared, its "predicate" will return false.
203 · definition_context
205 Mostly, this exists as a hook for the benefit of Moose.
207 This option should be a hash reference containing several
209 keys which will be used when inlining the attribute's
210 accessors. The keys should include "line", the line number
211 where the attribute was created, and either "file" or
212 "description".
213 This information will ultimately be used when eval'ing
215 inlined accessor code so that error messages report a
216 useful line and file name.
217 $attr->clone(%options)
219 This clones the attribute. Any options you provide will override
220 the settings of the original attribute. You can change the name of
221 the new attribute by passing a "name" key in %options.
222 Informational
224 These are all basic read-only accessors for the values passed into the
225 constructor.
226 $attr->name
228 Returns the attribute's name.
229 $attr->accessor
231 $attr->reader
232 $attr->writer
233 $attr->predicate
234 $attr->clearer
235 The "accessor", "reader", "writer", "predicate", and "clearer"
236 methods all return exactly what was passed to the constructor, so
237 it can be either a string containing a method name, or a hash
238 reference.
239 $attr->initializer
241 Returns the initializer as passed to the constructor, so this may
242 be either a method name or a subroutine reference.
243 $attr->init_arg
245 $attr->is_default_a_coderef
246 $attr->default($instance)
247 The $instance argument is optional. If you don't pass it, the
248 return value for this method is exactly what was passed to the
249 constructor, either a simple scalar or a subroutine reference.
250 If you do pass an $instance and the default is a subroutine
252 reference, then the reference is called as a method on the
253 $instance and the generated value is returned.
254 $attr->slots
256 Return a list of slots required by the attribute. This is usually
257 just one, the name of the attribute.
258 A slot is the name of the hash key used to store the attribute in
260 an object instance.
261 $attr->get_read_method
263 $attr->get_write_method
264 Returns the name of a method suitable for reading or writing the
265 value of the attribute in the associated class.
266 If an attribute is read- or write-only, then these methods can
268 return "undef" as appropriate.
269 $attr->has_read_method
271 $attr->has_write_method
272 This returns a boolean indicating whether the attribute has a named
273 read or write method.
274 $attr->get_read_method_ref
276 $attr->get_write_method_ref
277 Returns the subroutine reference of a method suitable for reading
278 or writing the attribute's value in the associated class. These
279 methods always return a subroutine reference, regardless of whether
280 or not the attribute is read- or write-only.
281 $attr->insertion_order
283 If this attribute has been inserted into a class, this returns a
284 zero based index regarding the order of insertion.
285 Informational predicates
287 These are all basic predicate methods for the values passed into "new".
288 $attr->has_accessor
290 $attr->has_reader
291 $attr->has_writer
292 $attr->has_predicate
293 $attr->has_clearer
294 $attr->has_initializer
295 $attr->has_init_arg
296 This will be false if the "init_arg" was set to "undef".
297 $attr->has_default
299 This will be false if the "default" was set to "undef", since
300 "undef" is the default "default" anyway.
301 $attr->has_builder
303 $attr->has_insertion_order
304 This will be false if this attribute has not be inserted into a
305 class
306 Value management
308 These methods are basically "back doors" to the instance, and can be
309 used to bypass the regular accessors, but still stay within the MOP.
310 These methods are not for general use, and should only be used if you
312 really know what you are doing.
313 $attr->initialize_instance_slot($meta_instance, $instance, $params)
315 This method is used internally to initialize the attribute's slot
316 in the object $instance.
317 The $params is a hash reference of the values passed to the object
319 constructor.
320 It's unlikely that you'll need to call this method yourself.
322 $attr->set_value($instance, $value)
324 Sets the value without going through the accessor. Note that this
325 works even with read-only attributes.
326 $attr->set_raw_value($instance, $value)
328 Sets the value with no side effects such as a trigger.
329 This doesn't actually apply to Class::MOP attributes, only to
331 subclasses.
332 $attr->set_initial_value($instance, $value)
334 Sets the value without going through the accessor. This method is
335 only called when the instance is first being initialized.
336 $attr->get_value($instance)
338 Returns the value without going through the accessor. Note that
339 this works even with write-only accessors.
340 $attr->get_raw_value($instance)
342 Returns the value without any side effects such as lazy attributes.
343 Doesn't actually apply to Class::MOP attributes, only to
345 subclasses.
346 $attr->has_value($instance)
348 Return a boolean indicating whether the attribute has been set in
349 $instance. This how the default "predicate" method works.
350 $attr->clear_value($instance)
352 This will clear the attribute's value in $instance. This is what
353 the default "clearer" calls.
354 Note that this works even if the attribute does not have any
356 associated read, write or clear methods.
357 Class association
359 These methods allow you to manage the attributes association with the
360 class that contains it. These methods should not be used lightly, nor
361 are they very magical, they are mostly used internally and by metaclass
362 instances.
363 $attr->associated_class
365 This returns the "Class::MOP::Class" with which this attribute is
366 associated, if any.
367 $attr->attach_to_class($metaclass)
369 This method stores a weakened reference to the $metaclass object
370 internally.
371 This method does not remove the attribute from its old class, nor
373 does it create any accessors in the new class.
374 It is probably best to use the Class::MOP::Class "add_attribute"
376 method instead.
377 $attr->detach_from_class
379 This method removes the associate metaclass object from the
380 attribute it has one.
381 This method does not remove the attribute itself from the class, or
383 remove its accessors.
384 It is probably best to use the Class::MOP::Class "remove_attribute"
386 method instead.
387 Attribute Accessor generation
389 $attr->accessor_metaclass
390 Accessor methods are generated using an accessor metaclass. By
391 default, this is Class::MOP::Method::Accessor. This method returns
392 the name of the accessor metaclass that this attribute uses.
393 $attr->associate_method($method)
395 This associates a Class::MOP::Method object with the attribute.
396 Typically, this is called internally when an attribute generates
397 its accessors.
398 $attr->associated_methods
400 This returns the list of methods which have been associated with
401 the attribute.
402 $attr->install_accessors
404 This method generates and installs code the attributes various
405 accessors. It is typically called from the Class::MOP::Class
406 "add_attribute" method.
407 $attr->remove_accessors
409 This method removes all of the accessors associated with the
410 attribute.
411 This does not currently remove methods from the list returned by
413 "associated_methods".
414 Introspection
416 Class::MOP::Attribute->meta
417 This will return a Class::MOP::Class instance for this class.
418 It should also be noted that Class::MOP will actually bootstrap
420 this module by installing a number of attribute meta-objects into
421 its metaclass.
422
424 Stevan Little <stevan@iinteractive.com>
425
427 Copyright 2006-2010 by Infinity Interactive, Inc.
428 <http://www.iinteractive.com>
430 This library is free software; you can redistribute it and/or modify it
432 under the same terms as Perl itself.
433perl v5.12.2 2010-09-13 Class::MOP::Attribute(3)