1Moose::Meta::Attribute(U3s)er Contributed Perl DocumentatMiooonse::Meta::Attribute(3)
2
3
4

NAME

6       Moose::Meta::Attribute - The Moose attribute metaclass
7

VERSION

9       version 2.2014
10

DESCRIPTION

12       This class is a subclass of Class::MOP::Attribute that provides
13       additional Moose-specific functionality.
14
15       To really understand this class, you will need to start with the
16       Class::MOP::Attribute documentation. This class can be understood as a
17       set of additional features on top of the basic feature provided by that
18       parent class.
19

INHERITANCE

21       "Moose::Meta::Attribute" is a subclass of Class::MOP::Attribute.
22

METHODS

24       Many of the documented below override methods in Class::MOP::Attribute
25       and add Moose specific features.
26
27   Creation
28       Moose::Meta::Attribute->new($name, %options)
29           This method overrides the Class::MOP::Attribute constructor.
30
31           Many of the options below are described in more detail in the
32           Moose::Manual::Attributes document.
33
34           It adds the following options to the constructor:
35
36           •       is => 'ro', 'rw', 'bare'
37
38                   This provides a shorthand for specifying the "reader",
39                   "writer", or "accessor" names. If the attribute is read-
40                   only ('ro') then it will have a "reader" method with the
41                   same attribute as the name.
42
43                   If it is read-write ('rw') then it will have an "accessor"
44                   method with the same name. If you provide an explicit
45                   "writer" for a read-write attribute, then you will have a
46                   "reader" with the same name as the attribute, and a
47                   "writer" with the name you provided.
48
49                   Use 'bare' when you are deliberately not installing any
50                   methods (accessor, reader, etc.) associated with this
51                   attribute; otherwise, Moose will issue a warning when this
52                   attribute is added to a metaclass.
53
54           •       isa => $type
55
56                   This option accepts a type. The type can be a string, which
57                   should be a type name. If the type name is unknown, it is
58                   assumed to be a class name.
59
60                   This option can also accept a Moose::Meta::TypeConstraint
61                   object.
62
63                   If you also provide a "does" option, then your "isa" option
64                   must be a class name, and that class must do the role
65                   specified with "does".
66
67           •       does => $role
68
69                   This is short-hand for saying that the attribute's type
70                   must be an object which does the named role.
71
72           •       coerce => $bool
73
74                   This option is only valid for objects with a type
75                   constraint ("isa") that defined a coercion. If this is
76                   true, then coercions will be applied whenever this
77                   attribute is set.
78
79                   You cannot make both this and the "weak_ref" option true.
80
81           •       trigger => $sub
82
83                   This option accepts a subroutine reference, which will be
84                   called after the attribute is set.
85
86           •       required => $bool
87
88                   An attribute which is required must be provided to the
89                   constructor. An attribute which is required can also have a
90                   "default" or "builder", which will satisfy its required-
91                   ness.
92
93                   A required attribute must have a "default", "builder" or a
94                   non-"undef" "init_arg"
95
96           •       lazy => $bool
97
98                   A lazy attribute must have a "default" or "builder". When
99                   an attribute is lazy, the default value will not be
100                   calculated until the attribute is read.
101
102           •       weak_ref => $bool
103
104                   If this is true, the attribute's value will be stored as a
105                   weak reference.
106
107           •       documentation
108
109                   An arbitrary string that can be retrieved later by calling
110                   "$attr->documentation".
111
112           •       auto_deref => $bool
113
114                   Note that in cases where you want this feature you are
115                   often better served by using a
116                   Moose::Meta::Attribute::Native trait instead.
117
118                   If this is true, then the reader will dereference the value
119                   when it is called. The attribute must have a type
120                   constraint which defines the attribute as an array or hash
121                   reference.
122
123           •       lazy_build => $bool
124
125                   Note that use of this feature is strongly discouraged. Some
126                   documentation used to encourage use of this feature as a
127                   best practice, but we have changed our minds.
128
129                   Setting this to true makes the attribute lazy and provides
130                   a number of default methods.
131
132                     has 'size' => (
133                         is         => 'ro',
134                         lazy_build => 1,
135                     );
136
137                   is equivalent to this:
138
139                     has 'size' => (
140                         is        => 'ro',
141                         lazy      => 1,
142                         builder   => '_build_size',
143                         clearer   => 'clear_size',
144                         predicate => 'has_size',
145                     );
146
147                   If your attribute name starts with an underscore ("_"),
148                   then the clearer and predicate will as well:
149
150                     has '_size' => (
151                         is         => 'ro',
152                         lazy_build => 1,
153                     );
154
155                   becomes:
156
157                     has '_size' => (
158                         is        => 'ro',
159                         lazy      => 1,
160                         builder   => '_build__size',
161                         clearer   => '_clear_size',
162                         predicate => '_has_size',
163                     );
164
165                   Note the doubled underscore in the builder name.
166                   Internally, Moose simply prepends the attribute name with
167                   "_build_" to come up with the builder name.
168
169           •       role_attribute => $role_attribute
170
171                   If provided, this should be a Moose::Meta::Role::Attribute
172                   object.
173
174       $attr->clone(%options)
175           This creates a new attribute based on attribute being cloned. You
176           must supply a "name" option to provide a new name for the
177           attribute.
178
179           The %options can only specify options handled by
180           Class::MOP::Attribute.
181
182   Value management
183       $attr->initialize_instance_slot($meta_instance, $instance, $params)
184           This method is used internally to initialize the attribute's slot
185           in the object $instance.
186
187           This overrides the Class::MOP::Attribute method to handle lazy
188           attributes, weak references, and type constraints.
189
190       get_value
191       set_value
192             eval { $point->meta->get_attribute('x')->set_value($point, 'forty-two') };
193             if($@) {
194               print "Oops: $@\n";
195             }
196
197           Attribute (x) does not pass the type constraint (Int) with
198           'forty-two'
199
200           Before setting the value, a check is made on the type constraint of
201           the attribute, if it has one, to see if the value passes it. If the
202           value fails to pass, the set operation dies.
203
204           Any coercion to convert values is done before checking the type
205           constraint.
206
207           To check a value against a type constraint before setting it, fetch
208           the attribute instance using "find_attribute_by_name" in
209           Class::MOP::Class, fetch the type_constraint from the attribute
210           using "type_constraint" in Moose::Meta::Attribute and call "check"
211           in Moose::Meta::TypeConstraint. See
212           Moose::Cookbook::Basics::Company_Subtypes for an example.
213
214   Attribute Accessor generation
215       $attr->install_accessors
216           This method overrides the parent to also install delegation
217           methods.
218
219           If, after installing all methods, the attribute object has no
220           associated methods, it throws an error unless "is => 'bare'" was
221           passed to the attribute constructor.  (Trying to add an attribute
222           that has no associated methods is almost always an error.)
223
224       $attr->remove_accessors
225           This method overrides the parent to also remove delegation methods.
226
227       $attr->inline_set($instance_var, $value_var)
228           This method return a code snippet suitable for inlining the
229           relevant operation. It expect strings containing variable names to
230           be used in the inlining, like '$self' or '$_[1]'.
231
232       $attr->install_delegation
233           This method adds its delegation methods to the attribute's
234           associated class, if it has any to add.
235
236       $attr->remove_delegation
237           This method remove its delegation methods from the attribute's
238           associated class.
239
240       $attr->accessor_metaclass
241           Returns the accessor metaclass name, which defaults to
242           Moose::Meta::Method::Accessor.
243
244       $attr->delegation_metaclass
245           Returns the delegation metaclass name, which defaults to
246           Moose::Meta::Method::Delegation.
247
248   Additional Moose features
249       These methods are not found in the superclass. They support features
250       provided by Moose.
251
252       $attr->does($role)
253           This indicates whether the attribute itself does the given role.
254           The role can be given as a full class name, or as a resolvable
255           trait name.
256
257           Note that this checks the attribute itself, not its type
258           constraint, so it is checking the attribute's metaclass and any
259           traits applied to the attribute.
260
261       Moose::Meta::Class->interpolate_class_and_new($name, %options)
262           This is an alternate constructor that handles the "metaclass" and
263           "traits" options.
264
265           Effectively, this method is a factory that finds or creates the
266           appropriate class for the given "metaclass" and/or "traits".
267
268           Once it has the appropriate class, it will call "$class->new($name,
269           %options)" on that class.
270
271       $attr->clone_and_inherit_options(%options)
272           This method supports the "has '+foo'" feature. It does various bits
273           of processing on the supplied %options before ultimately calling
274           the "clone" method.
275
276           One of its main tasks is to make sure that the %options provided
277           does not include the options returned by the
278           "illegal_options_for_inheritance" method.
279
280       $attr->illegal_options_for_inheritance
281           This returns a blacklist of options that can not be overridden in a
282           subclass's attribute definition.
283
284           This exists to allow a custom metaclass to change or add to the
285           list of options which can not be changed.
286
287       $attr->type_constraint
288           Returns the Moose::Meta::TypeConstraint object for this attribute,
289           if it has one.
290
291       $attr->has_type_constraint
292           Returns true if this attribute has a type constraint.
293
294       $attr->verify_against_type_constraint($value)
295           Given a value, this method returns true if the value is valid for
296           the attribute's type constraint. If the value is not valid, it
297           throws an error.
298
299       $attr->handles
300           This returns the value of the "handles" option passed to the
301           constructor.
302
303       $attr->has_handles
304           Returns true if this attribute performs delegation.
305
306       $attr->is_weak_ref
307           Returns true if this attribute stores its value as a weak
308           reference.
309
310       $attr->is_required
311           Returns true if this attribute is required to have a value.
312
313       $attr->is_lazy
314           Returns true if this attribute is lazy.
315
316       $attr->is_lazy_build
317           Returns true if the "lazy_build" option was true when passed to the
318           constructor.
319
320       $attr->should_coerce
321           Returns true if the "coerce" option passed to the constructor was
322           true.
323
324       $attr->should_auto_deref
325           Returns true if the "auto_deref" option passed to the constructor
326           was true.
327
328       $attr->trigger
329           This is the subroutine reference that was in the "trigger" option
330           passed to the constructor, if any.
331
332       $attr->has_trigger
333           Returns true if this attribute has a trigger set.
334
335       $attr->documentation
336           Returns the value that was in the "documentation" option passed to
337           the constructor, if any.
338
339       $attr->has_documentation
340           Returns true if this attribute has any documentation.
341
342       $attr->role_attribute
343           Returns the Moose::Meta::Role::Attribute object from which this
344           attribute was created, if any. This may return "undef".
345
346       $attr->has_role_attribute
347           Returns true if this attribute has an associated role attribute.
348
349       $attr->applied_traits
350           This returns an array reference of all the traits which were
351           applied to this attribute. If none were applied, this returns
352           "undef".
353
354       $attr->has_applied_traits
355           Returns true if this attribute has any traits applied.
356

BUGS

358       See "BUGS" in Moose for details on reporting bugs.
359

AUTHORS

361       •   Stevan Little <stevan@cpan.org>
362
363       •   Dave Rolsky <autarch@urth.org>
364
365       •   Jesse Luehrs <doy@cpan.org>
366
367       •   Shawn M Moore <sartak@cpan.org>
368
369       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
370
371       •   Karen Etheridge <ether@cpan.org>
372
373       •   Florian Ragwitz <rafl@debian.org>
374
375       •   Hans Dieter Pearcey <hdp@cpan.org>
376
377       •   Chris Prather <chris@prather.org>
378
379       •   Matt S Trout <mstrout@cpan.org>
380
382       This software is copyright (c) 2006 by Infinity Interactive, Inc.
383
384       This is free software; you can redistribute it and/or modify it under
385       the same terms as the Perl 5 programming language system itself.
386
387
388
389perl v5.32.1                      2021-01-27         Moose::Meta::Attribute(3)
Impressum