1Moose::Meta::Attribute(U3s)er Contributed Perl DocumentatMiooonse::Meta::Attribute(3)
2
6 Moose::Meta::Attribute - The Moose attribute metaclass
7
9 version 2.2201
10
12 This class is a subclass of Class::MOP::Attribute that provides
13 additional Moose-specific functionality.
14 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
21 "Moose::Meta::Attribute" is a subclass of Class::MOP::Attribute.
22
24 Many of the documented below override methods in Class::MOP::Attribute
25 and add Moose specific features.
26 Creation
28 Moose::Meta::Attribute->new($name, %options)
29 This method overrides the Class::MOP::Attribute constructor.
30 Many of the options below are described in more detail in the
32 Moose::Manual::Attributes document.
33 It adds the following options to the constructor:
35 • is => 'ro', 'rw', 'bare'
37 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 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 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 • isa => $type
55 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 This option can also accept a Moose::Meta::TypeConstraint
61 object.
62 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 • does => $role
68 This is short-hand for saying that the attribute's type
70 must be an object which does the named role.
71 • coerce => $bool
73 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 You cannot make both this and the "weak_ref" option true.
80 • trigger => $sub
82 This option accepts a subroutine reference, which will be
84 called after the attribute is set.
85 • required => $bool
87 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 A required attribute must have a "default", "builder" or a
94 non-"undef" "init_arg"
95 • lazy => $bool
97 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 • weak_ref => $bool
103 If this is true, the attribute's value will be stored as a
105 weak reference.
106 • documentation
108 An arbitrary string that can be retrieved later by calling
110 "$attr->documentation".
111 • auto_deref => $bool
113 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 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 • lazy_build => $bool
124 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 Setting this to true makes the attribute lazy and provides
130 a number of default methods.
131 has 'size' => (
133 is => 'ro',
134 lazy_build => 1,
135 );
136 is equivalent to this:
138 has 'size' => (
140 is => 'ro',
141 lazy => 1,
142 builder => '_build_size',
143 clearer => 'clear_size',
144 predicate => 'has_size',
145 );
146 If your attribute name starts with an underscore ("_"),
148 then the clearer and predicate will as well:
149 has '_size' => (
151 is => 'ro',
152 lazy_build => 1,
153 );
154 becomes:
156 has '_size' => (
158 is => 'ro',
159 lazy => 1,
160 builder => '_build__size',
161 clearer => '_clear_size',
162 predicate => '_has_size',
163 );
164 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 • role_attribute => $role_attribute
170 If provided, this should be a Moose::Meta::Role::Attribute
172 object.
173 $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 The %options can only specify options handled by
180 Class::MOP::Attribute.
181 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 This overrides the Class::MOP::Attribute method to handle lazy
188 attributes, weak references, and type constraints.
189 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 Attribute (x) does not pass the type constraint (Int) with
198 'forty-two'
199 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 Any coercion to convert values is done before checking the type
205 constraint.
206 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 Attribute Accessor generation
215 $attr->install_accessors
216 This method overrides the parent to also install delegation
217 methods.
218 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 $attr->remove_accessors
225 This method overrides the parent to also remove delegation methods.
226 $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 $attr->install_delegation
233 This method adds its delegation methods to the attribute's
234 associated class, if it has any to add.
235 $attr->remove_delegation
237 This method remove its delegation methods from the attribute's
238 associated class.
239 $attr->accessor_metaclass
241 Returns the accessor metaclass name, which defaults to
242 Moose::Meta::Method::Accessor.
243 $attr->delegation_metaclass
245 Returns the delegation metaclass name, which defaults to
246 Moose::Meta::Method::Delegation.
247 Additional Moose features
249 These methods are not found in the superclass. They support features
250 provided by Moose.
251 $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 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 Moose::Meta::Class->interpolate_class_and_new($name, %options)
262 This is an alternate constructor that handles the "metaclass" and
263 "traits" options.
264 Effectively, this method is a factory that finds or creates the
266 appropriate class for the given "metaclass" and/or "traits".
267 Once it has the appropriate class, it will call "$class->new($name,
269 %options)" on that class.
270 $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 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 $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 This exists to allow a custom metaclass to change or add to the
285 list of options which can not be changed.
286 $attr->type_constraint
288 Returns the Moose::Meta::TypeConstraint object for this attribute,
289 if it has one.
290 $attr->has_type_constraint
292 Returns true if this attribute has a type constraint.
293 $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 $attr->handles
300 This returns the value of the "handles" option passed to the
301 constructor.
302 $attr->has_handles
304 Returns true if this attribute performs delegation.
305 $attr->is_weak_ref
307 Returns true if this attribute stores its value as a weak
308 reference.
309 $attr->is_required
311 Returns true if this attribute is required to have a value.
312 $attr->is_lazy
314 Returns true if this attribute is lazy.
315 $attr->is_lazy_build
317 Returns true if the "lazy_build" option was true when passed to the
318 constructor.
319 $attr->should_coerce
321 Returns true if the "coerce" option passed to the constructor was
322 true.
323 $attr->should_auto_deref
325 Returns true if the "auto_deref" option passed to the constructor
326 was true.
327 $attr->trigger
329 This is the subroutine reference that was in the "trigger" option
330 passed to the constructor, if any.
331 $attr->has_trigger
333 Returns true if this attribute has a trigger set.
334 $attr->documentation
336 Returns the value that was in the "documentation" option passed to
337 the constructor, if any.
338 $attr->has_documentation
340 Returns true if this attribute has any documentation.
341 $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 $attr->has_role_attribute
347 Returns true if this attribute has an associated role attribute.
348 $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 $attr->has_applied_traits
355 Returns true if this attribute has any traits applied.
356
358 See "BUGS" in Moose for details on reporting bugs.
359
361 • Stevan Little <stevan@cpan.org>
362 • Dave Rolsky <autarch@urth.org>
364 • Jesse Luehrs <doy@cpan.org>
366 • Shawn M Moore <sartak@cpan.org>
368 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
370 • Karen Etheridge <ether@cpan.org>
372 • Florian Ragwitz <rafl@debian.org>
374 • Hans Dieter Pearcey <hdp@cpan.org>
376 • Chris Prather <chris@prather.org>
378 • Matt S Trout <mstrout@cpan.org>
380
382 This software is copyright (c) 2006 by Infinity Interactive, Inc.
383 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.
386perl v5.34.0 2022-01-21 Moose::Meta::Attribute(3)