1Class::MOP::Attribute(3U)ser Contributed Perl DocumentatiColnass::MOP::Attribute(3)
2
3
4

NAME

6       Class::MOP::Attribute - Attribute Meta Object
7

VERSION

9       version 2.2015
10

SYNOPSIS

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

DESCRIPTION

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

METHODS

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
47           •       init_arg
48
49                   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
53                     MyClass->meta->new_object( -foo => 'Hello There' );
54
55                   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
60           •       builder
61
62                   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
67           •       default
68
69                   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
74                   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
79                     Class::MOP::Attribute->new(
80                         'foo' => (
81                             default => sub { [] },
82                         )
83                     );
84
85                     # or ...
86
87                     Class::MOP::Attribute->new(
88                         'foo' => (
89                             default => sub { {} },
90                         )
91                     );
92
93                   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
97                     Class::MOP::Attribute->new(
98                         'foo' => (
99                             default => sub {
100                                 sub { print "Hello World" }
101                             },
102                         )
103                     );
104
105                   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
110                     Class::MOP::Attribute->new(
111                         'object_identity' => (
112                             default => sub { Scalar::Util::refaddr( $_[0] ) },
113                         )
114                     );
115
116                   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
121           •       initializer
122
123                   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
130                   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
136                   This contrived example shows an initializer that sets the
137                   attribute to twice the given value.
138
139                     Class::MOP::Attribute->new(
140                         'doubled' => (
141                             initializer => sub {
142                                 my ( $self, $value, $set, $attr ) = @_;
143                                 $set->( $value * 2 );
144                             },
145                         )
146                     );
147
148                   Since an initializer can be a method name, you can easily
149                   make attribute initialization use the writer:
150
151                     Class::MOP::Attribute->new(
152                         'some_attr' => (
153                             writer      => 'some_attr',
154                             initializer => 'some_attr',
155                         )
156                     );
157
158                   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
162                     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
169                         # the reader behaves normally
170                         return $self->$orig if not @_;
171
172                         # mutate $value as desired
173                         # $value = <something($value);
174
175                         # if called as an initializer, set the value and we're done
176                         return $setter->($row) if $setter;
177
178                         # otherwise, call the real writer with the new value
179                         $self->$orig($row);
180                     };
181
182           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
190           •       accessor
191
192                   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
197                   Note that "undef" is a legitimate value, so this will work:
198
199                     $object->set_something(undef);
200
201           •       reader
202
203                   This is a basic read-only accessor. It returns the value of
204                   the attribute.
205
206           •       writer
207
208                   This is a basic write accessor, it accepts a single
209                   argument, and assigns that value to the attribute.
210
211                   Note that "undef" is a legitimate value, so this will work:
212
213                     $object->set_something(undef);
214
215           •       predicate
216
217                   The predicate method returns a boolean indicating whether
218                   or not the attribute has been explicitly set.
219
220                   Note that the predicate returns true even if the attribute
221                   was set to a false value (0 or "undef").
222
223           •       clearer
224
225                   This method will uninitialize the attribute. After an
226                   attribute is cleared, its "predicate" will return false.
227
228           •       definition_context
229
230                   Mostly, this exists as a hook for the benefit of Moose.
231
232                   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
238                   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
242       $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
247   Informational
248       These are all basic read-only accessors for the values passed into the
249       constructor.
250
251       $attr->name
252           Returns the attribute's name.
253
254       $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
264       $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
268       $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
276           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
280       $attr->slots
281           Return a list of slots required by the attribute. This is usually
282           just one, the name of the attribute.
283
284           A slot is the name of the hash key used to store the attribute in
285           an object instance.
286
287       $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
292           If an attribute is read- or write-only, then these methods can
293           return "undef" as appropriate.
294
295       $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
300       $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
307       $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
311   Informational predicates
312       These are all basic predicate methods for the values passed into "new".
313
314       $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
323       $attr->has_default
324           This will be false if the "default" was set to "undef", since
325           "undef" is the default "default" anyway.
326
327       $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
332   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
336       These methods are not for general use, and should only be used if you
337       really know what you are doing.
338
339       $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
343           The $params is a hash reference of the values passed to the object
344           constructor.
345
346           It's unlikely that you'll need to call this method yourself.
347
348       $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
352       $attr->set_raw_value($instance, $value)
353           Sets the value with no side effects such as a trigger.
354
355           This doesn't actually apply to Class::MOP attributes, only to
356           subclasses.
357
358       $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
362       $attr->get_value($instance)
363           Returns the value without going through the accessor. Note that
364           this works even with write-only accessors.
365
366       $attr->get_raw_value($instance)
367           Returns the value without any side effects such as lazy attributes.
368
369           Doesn't actually apply to Class::MOP attributes, only to
370           subclasses.
371
372       $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
376       $attr->clear_value($instance)
377           This will clear the attribute's value in $instance. This is what
378           the default "clearer" calls.
379
380           Note that this works even if the attribute does not have any
381           associated read, write or clear methods.
382
383   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
389       $attr->associated_class
390           This returns the Class::MOP::Class with which this attribute is
391           associated, if any.
392
393       $attr->attach_to_class($metaclass)
394           This method stores a weakened reference to the $metaclass object
395           internally.
396
397           This method does not remove the attribute from its old class, nor
398           does it create any accessors in the new class.
399
400           It is probably best to use the Class::MOP::Class "add_attribute"
401           method instead.
402
403       $attr->detach_from_class
404           This method removes the associate metaclass object from the
405           attribute it has one.
406
407           This method does not remove the attribute itself from the class, or
408           remove its accessors.
409
410           It is probably best to use the Class::MOP::Class "remove_attribute"
411           method instead.
412
413   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
419       $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
424       $attr->associated_methods
425           This returns the list of methods which have been associated with
426           the attribute.
427
428       $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
433       $attr->remove_accessors
434           This method removes all of the accessors associated with the
435           attribute.
436
437           This does not currently remove methods from the list returned by
438           "associated_methods".
439
440       $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
448   Introspection
449       Class::MOP::Attribute->meta
450           This will return a Class::MOP::Class instance for this class.
451
452           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

AUTHORS

457       •   Stevan Little <stevan@cpan.org>
458
459       •   Dave Rolsky <autarch@urth.org>
460
461       •   Jesse Luehrs <doy@cpan.org>
462
463       •   Shawn M Moore <sartak@cpan.org>
464
465       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
466
467       •   Karen Etheridge <ether@cpan.org>
468
469       •   Florian Ragwitz <rafl@debian.org>
470
471       •   Hans Dieter Pearcey <hdp@cpan.org>
472
473       •   Chris Prather <chris@prather.org>
474
475       •   Matt S Trout <mstrout@cpan.org>
476
478       This software is copyright (c) 2006 by Infinity Interactive, Inc.
479
480       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.
482
483
484
485perl v5.34.0                      2021-07-22          Class::MOP::Attribute(3)
Impressum