1Class::MOP::Attribute(3U)ser Contributed Perl DocumentatiColnass::MOP::Attribute(3)
2
6 Class::MOP::Attribute - Attribute Meta Object
7
9 version 2.2014
10
12 Class::MOP::Attribute->new(
13 foo => (
14 accessor => 'foo', # dual purpose get/set accessor
15 predicate => 'has_foo', # predicate check for defined-ness
16 init_arg => '-foo', # class->new will look for a -foo key
17 default => 'BAR IS BAZ!' # if no -foo key is provided, use this
18 )
19 );
20 Class::MOP::Attribute->new(
22 bar => (
23 reader => 'bar', # getter
24 writer => 'set_bar', # setter
25 predicate => 'has_bar', # predicate check for defined-ness
26 init_arg => ':bar', # class->new will look for a :bar key
27 # no default value means it is undef
28 )
29 );
30
32 The Attribute Protocol is almost entirely an invention of "Class::MOP".
33 Perl 5 does not have a consistent notion of attributes. There are so
34 many ways in which this is done, and very few (if any) are easily
35 discoverable by this module.
36 With that said, this module attempts to inject some order into this
38 chaos, by introducing a consistent API which can be used to create
39 object attributes.
40
42 Creation
43 Class::MOP::Attribute->new($name, ?%options)
44 An attribute must (at the very least), have a $name. All other
45 %options are added as key-value pairs.
46 • init_arg
48 This is a string value representing the expected key in an
50 initialization hash. For instance, if we have an "init_arg"
51 value of "-foo", then the following code will Just Work.
52 MyClass->meta->new_object( -foo => 'Hello There' );
54 If an init_arg is not assigned, it will automatically use
56 the attribute's name. If "init_arg" is explicitly set to
57 "undef", the attribute cannot be specified during
58 initialization.
59 • builder
61 This provides the name of a method that will be called to
63 initialize the attribute. This method will be called on the
64 object after it is constructed. It is expected to return a
65 valid value for the attribute.
66 • default
68 This can be used to provide an explicit default for
70 initializing the attribute. If the default you provide is a
71 subroutine reference, then this reference will be called as
72 a method on the object.
73 If the value is a simple scalar (string or number), then it
75 can be just passed as is. However, if you wish to
76 initialize it with a HASH or ARRAY ref, then you need to
77 wrap that inside a subroutine reference:
78 Class::MOP::Attribute->new(
80 'foo' => (
81 default => sub { [] },
82 )
83 );
84 # or ...
86 Class::MOP::Attribute->new(
88 'foo' => (
89 default => sub { {} },
90 )
91 );
92 If you wish to initialize an attribute with a subroutine
94 reference itself, then you need to wrap that in a
95 subroutine as well:
96 Class::MOP::Attribute->new(
98 'foo' => (
99 default => sub {
100 sub { print "Hello World" }
101 },
102 )
103 );
104 And lastly, if the value of your attribute is dependent
106 upon some other aspect of the instance structure, then you
107 can take advantage of the fact that when the "default"
108 value is called as a method:
109 Class::MOP::Attribute->new(
111 'object_identity' => (
112 default => sub { Scalar::Util::refaddr( $_[0] ) },
113 )
114 );
115 Note that there is no guarantee that attributes are
117 initialized in any particular order, so you cannot rely on
118 the value of some other attribute when generating the
119 default.
120 • initializer
122 This option can be either a method name or a subroutine
124 reference. This method will be called when setting the
125 attribute's value in the constructor. Unlike "default" and
126 "builder", the initializer is only called when a value is
127 provided to the constructor. The initializer allows you to
128 munge this value during object construction.
129 The initializer is called as a method with three arguments.
131 The first is the value that was passed to the constructor.
132 The second is a subroutine reference that can be called to
133 actually set the attribute's value, and the last is the
134 associated "Class::MOP::Attribute" object.
135 This contrived example shows an initializer that sets the
137 attribute to twice the given value.
138 Class::MOP::Attribute->new(
140 'doubled' => (
141 initializer => sub {
142 my ( $self, $value, $set, $attr ) = @_;
143 $set->( $value * 2 );
144 },
145 )
146 );
147 Since an initializer can be a method name, you can easily
149 make attribute initialization use the writer:
150 Class::MOP::Attribute->new(
152 'some_attr' => (
153 writer => 'some_attr',
154 initializer => 'some_attr',
155 )
156 );
157 Your writer (actually, a wrapper around the writer, using
159 method modifications) will need to examine @_ and determine
160 under which context it is being called:
161 around 'some_attr' => sub {
163 my $orig = shift;
164 my $self = shift;
165 # $value is not defined if being called as a reader
166 # $setter and $attr are only defined if being called as an initializer
167 my ($value, $setter, $attr) = @_;
168 # the reader behaves normally
170 return $self->$orig if not @_;
171 # mutate $value as desired
173 # $value = <something($value);
174 # if called as an initializer, set the value and we're done
176 return $setter->($row) if $setter;
177 # otherwise, call the real writer with the new value
179 $self->$orig($row);
180 };
181 The "accessor", "reader", "writer", "predicate" and "clearer"
183 options all accept the same parameters. You can provide the name of
184 the method, in which case an appropriate default method will be
185 generated for you. Or instead you can also provide hash reference
186 containing exactly one key (the method name) and one value. The
187 value should be a subroutine reference, which will be installed as
188 the method itself.
189 • accessor
191 An "accessor" is a standard Perl-style read/write accessor.
193 It will return the value of the attribute, and if a value
194 is passed as an argument, it will assign that value to the
195 attribute.
196 Note that "undef" is a legitimate value, so this will work:
198 $object->set_something(undef);
200 • reader
202 This is a basic read-only accessor. It returns the value of
204 the attribute.
205 • writer
207 This is a basic write accessor, it accepts a single
209 argument, and assigns that value to the attribute.
210 Note that "undef" is a legitimate value, so this will work:
212 $object->set_something(undef);
214 • predicate
216 The predicate method returns a boolean indicating whether
218 or not the attribute has been explicitly set.
219 Note that the predicate returns true even if the attribute
221 was set to a false value (0 or "undef").
222 • clearer
224 This method will uninitialize the attribute. After an
226 attribute is cleared, its "predicate" will return false.
227 • definition_context
229 Mostly, this exists as a hook for the benefit of Moose.
231 This option should be a hash reference containing several
233 keys which will be used when inlining the attribute's
234 accessors. The keys should include "line", the line number
235 where the attribute was created, and either "file" or
236 "description".
237 This information will ultimately be used when eval'ing
239 inlined accessor code so that error messages report a
240 useful line and file name.
241 $attr->clone(%options)
243 This clones the attribute. Any options you provide will override
244 the settings of the original attribute. You can change the name of
245 the new attribute by passing a "name" key in %options.
246 Informational
248 These are all basic read-only accessors for the values passed into the
249 constructor.
250 $attr->name
252 Returns the attribute's name.
253 $attr->accessor
255 $attr->reader
256 $attr->writer
257 $attr->predicate
258 $attr->clearer
259 The "accessor", "reader", "writer", "predicate", and "clearer"
260 methods all return exactly what was passed to the constructor, so
261 it can be either a string containing a method name, or a hash
262 reference.
263 $attr->initializer
265 Returns the initializer as passed to the constructor, so this may
266 be either a method name or a subroutine reference.
267 $attr->init_arg
269 $attr->is_default_a_coderef
270 $attr->builder
271 $attr->default($instance)
272 The $instance argument is optional. If you don't pass it, the
273 return value for this method is exactly what was passed to the
274 constructor, either a simple scalar or a subroutine reference.
275 If you do pass an $instance and the default is a subroutine
277 reference, then the reference is called as a method on the
278 $instance and the generated value is returned.
279 $attr->slots
281 Return a list of slots required by the attribute. This is usually
282 just one, the name of the attribute.
283 A slot is the name of the hash key used to store the attribute in
285 an object instance.
286 $attr->get_read_method
288 $attr->get_write_method
289 Returns the name of a method suitable for reading or writing the
290 value of the attribute in the associated class.
291 If an attribute is read- or write-only, then these methods can
293 return "undef" as appropriate.
294 $attr->has_read_method
296 $attr->has_write_method
297 This returns a boolean indicating whether the attribute has a named
298 read or write method.
299 $attr->get_read_method_ref
301 $attr->get_write_method_ref
302 Returns the subroutine reference of a method suitable for reading
303 or writing the attribute's value in the associated class. These
304 methods always return a subroutine reference, regardless of whether
305 or not the attribute is read- or write-only.
306 $attr->insertion_order
308 If this attribute has been inserted into a class, this returns a
309 zero based index regarding the order of insertion.
310 Informational predicates
312 These are all basic predicate methods for the values passed into "new".
313 $attr->has_accessor
315 $attr->has_reader
316 $attr->has_writer
317 $attr->has_predicate
318 $attr->has_clearer
319 $attr->has_initializer
320 $attr->has_init_arg
321 This will be false if the "init_arg" was set to "undef".
322 $attr->has_default
324 This will be false if the "default" was set to "undef", since
325 "undef" is the default "default" anyway.
326 $attr->has_builder
328 $attr->has_insertion_order
329 This will be false if this attribute has not be inserted into a
330 class
331 Value management
333 These methods are basically "back doors" to the instance, and can be
334 used to bypass the regular accessors, but still stay within the MOP.
335 These methods are not for general use, and should only be used if you
337 really know what you are doing.
338 $attr->initialize_instance_slot($meta_instance, $instance, $params)
340 This method is used internally to initialize the attribute's slot
341 in the object $instance.
342 The $params is a hash reference of the values passed to the object
344 constructor.
345 It's unlikely that you'll need to call this method yourself.
347 $attr->set_value($instance, $value)
349 Sets the value without going through the accessor. Note that this
350 works even with read-only attributes.
351 $attr->set_raw_value($instance, $value)
353 Sets the value with no side effects such as a trigger.
354 This doesn't actually apply to Class::MOP attributes, only to
356 subclasses.
357 $attr->set_initial_value($instance, $value)
359 Sets the value without going through the accessor. This method is
360 only called when the instance is first being initialized.
361 $attr->get_value($instance)
363 Returns the value without going through the accessor. Note that
364 this works even with write-only accessors.
365 $attr->get_raw_value($instance)
367 Returns the value without any side effects such as lazy attributes.
368 Doesn't actually apply to Class::MOP attributes, only to
370 subclasses.
371 $attr->has_value($instance)
373 Return a boolean indicating whether the attribute has been set in
374 $instance. This how the default "predicate" method works.
375 $attr->clear_value($instance)
377 This will clear the attribute's value in $instance. This is what
378 the default "clearer" calls.
379 Note that this works even if the attribute does not have any
381 associated read, write or clear methods.
382 Class association
384 These methods allow you to manage the attributes association with the
385 class that contains it. These methods should not be used lightly, nor
386 are they very magical, they are mostly used internally and by metaclass
387 instances.
388 $attr->associated_class
390 This returns the Class::MOP::Class with which this attribute is
391 associated, if any.
392 $attr->attach_to_class($metaclass)
394 This method stores a weakened reference to the $metaclass object
395 internally.
396 This method does not remove the attribute from its old class, nor
398 does it create any accessors in the new class.
399 It is probably best to use the Class::MOP::Class "add_attribute"
401 method instead.
402 $attr->detach_from_class
404 This method removes the associate metaclass object from the
405 attribute it has one.
406 This method does not remove the attribute itself from the class, or
408 remove its accessors.
409 It is probably best to use the Class::MOP::Class "remove_attribute"
411 method instead.
412 Attribute Accessor generation
414 $attr->accessor_metaclass
415 Accessor methods are generated using an accessor metaclass. By
416 default, this is Class::MOP::Method::Accessor. This method returns
417 the name of the accessor metaclass that this attribute uses.
418 $attr->associate_method($method)
420 This associates a Class::MOP::Method object with the attribute.
421 Typically, this is called internally when an attribute generates
422 its accessors.
423 $attr->associated_methods
425 This returns the list of methods which have been associated with
426 the attribute.
427 $attr->install_accessors
429 This method generates and installs code for the attribute's
430 accessors. It is typically called from the Class::MOP::Class
431 "add_attribute" method.
432 $attr->remove_accessors
434 This method removes all of the accessors associated with the
435 attribute.
436 This does not currently remove methods from the list returned by
438 "associated_methods".
439 $attr->inline_get
441 $attr->inline_set
442 $attr->inline_has
443 $attr->inline_clear
444 These methods return a code snippet suitable for inlining the
445 relevant operation. They expect strings containing variable names
446 to be used in the inlining, like '$self' or '$_[1]'.
447 Introspection
449 Class::MOP::Attribute->meta
450 This will return a Class::MOP::Class instance for this class.
451 It should also be noted that Class::MOP will actually bootstrap
453 this module by installing a number of attribute meta-objects into
454 its metaclass.
455
457 • Stevan Little <stevan@cpan.org>
458 • Dave Rolsky <autarch@urth.org>
460 • Jesse Luehrs <doy@cpan.org>
462 • Shawn M Moore <sartak@cpan.org>
464 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
466 • Karen Etheridge <ether@cpan.org>
468 • Florian Ragwitz <rafl@debian.org>
470 • Hans Dieter Pearcey <hdp@cpan.org>
472 • Chris Prather <chris@prather.org>
474 • Matt S Trout <mstrout@cpan.org>
476
478 This software is copyright (c) 2006 by Infinity Interactive, Inc.
479 This is free software; you can redistribute it and/or modify it under
481 the same terms as the Perl 5 programming language system itself.
482perl v5.32.1 2021-01-27 Class::MOP::Attribute(3)