1Moose::Meta::Attribute(U3s)er Contributed Perl DocumentatMiooonse::Meta::Attribute(3)
2
6 Moose::Meta::Attribute - The Moose attribute metaclass
7
9 This class is a subclass of Class::MOP::Attribute that provides
10 additional Moose-specific functionality.
11 To really understand this class, you will need to start with the
13 Class::MOP::Attribute documentation. This class can be understood as a
14 set of additional features on top of the basic feature provided by that
15 parent class.
16
18 "Moose::Meta::Attribute" is a subclass of Class::MOP::Attribute.
19
21 Many of the documented below override methods in Class::MOP::Attribute
22 and add Moose specific features.
23 Creation
25 Moose::Meta::Attribute->new(%options)
26 This method overrides the Class::MOP::Attribute constructor.
27 Many of the options below are described in more detail in the
29 Moose::Manual::Attributes document.
30 It adds the following options to the constructor:
32 · is => 'ro', 'rw', 'bare'
34 This provides a shorthand for specifying the "reader",
36 "writer", or "accessor" names. If the attribute is read-
37 only ('ro') then it will have a "reader" method with the
38 same attribute as the name.
39 If it is read-write ('rw') then it will have an "accessor"
41 method with the same name. If you provide an explicit
42 "writer" for a read-write attribute, then you will have a
43 "reader" with the same name as the attribute, and a
44 "writer" with the name you provided.
45 Use 'bare' when you are deliberately not installing any
47 methods (accessor, reader, etc.) associated with this
48 attribute; otherwise, Moose will issue a deprecation
49 warning when this attribute is added to a metaclass.
50 · isa => $type
52 This option accepts a type. The type can be a string, which
54 should be a type name. If the type name is unknown, it is
55 assumed to be a class name.
56 This option can also accept a Moose::Meta::TypeConstraint
58 object.
59 If you also provide a "does" option, then your "isa" option
61 must be a class name, and that class must do the role
62 specified with "does".
63 · does => $role
65 This is short-hand for saying that the attribute's type
67 must be an object which does the named role.
68 · coerce => $bool
70 This option is only valid for objects with a type
72 constraint ("isa"). If this is true, then coercions will be
73 applied whenever this attribute is set.
74 You can make both this and the "weak_ref" option true.
76 · trigger => $sub
78 This option accepts a subroutine reference, which will be
80 called after the attribute is set.
81 · required => $bool
83 An attribute which is required must be provided to the
85 constructor. An attribute which is required can also have a
86 "default" or "builder", which will satisfy its required-
87 ness.
88 A required attribute must have a "default", "builder" or a
90 non-"undef" "init_arg"
91 · lazy => $bool
93 A lazy attribute must have a "default" or "builder". When
95 an attribute is lazy, the default value will not be
96 calculated until the attribute is read.
97 · weak_ref => $bool
99 If this is true, the attribute's value will be stored as a
101 weak reference.
102 · auto_deref => $bool
104 If this is true, then the reader will dereference the value
106 when it is called. The attribute must have a type
107 constraint which defines the attribute as an array or hash
108 reference.
109 · lazy_build => $bool
111 Setting this to true makes the attribute lazy and provides
113 a number of default methods.
114 has 'size' => (
116 is => 'ro',
117 lazy_build => 1,
118 );
119 is equivalent to this:
121 has 'size' => (
123 is => 'ro',
124 lazy => 1,
125 builder => '_build_size',
126 clearer => 'clear_size',
127 predicate => 'has_size',
128 );
129 · documentation
131 An arbitrary string that can be retrieved later by calling
133 "$attr->documentation".
134 $attr->clone(%options)
136 This creates a new attribute based on attribute being cloned. You
137 must supply a "name" option to provide a new name for the
138 attribute.
139 The %options can only specify options handled by
141 Class::MOP::Attribute.
142 Value management
144 $attr->initialize_instance_slot($meta_instance, $instance, $params)
145 This method is used internally to initialize the attribute's slot
146 in the object $instance.
147 This overrides the Class::MOP::Attribute method to handle lazy
149 attributes, weak references, and type constraints.
150 get_value
152 set_value
153 eval { $point->meta->get_attribute('x')->set_value($point, 'forty-two') };
154 if($@) {
155 print "Oops: $@\n";
156 }
157 Attribute (x) does not pass the type constraint (Int) with
159 'forty-two'
160 Before setting the value, a check is made on the type constraint of
162 the attribute, if it has one, to see if the value passes it. If the
163 value fails to pass, the set operation dies with a "throw_error".
164 Any coercion to convert values is done before checking the type
166 constraint.
167 To check a value against a type constraint before setting it, fetch
169 the attribute instance using "find_attribute_by_name" in
170 Class::MOP::Class, fetch the type_constraint from the attribute
171 using "type_constraint" in Moose::Meta::Attribute and call "check"
172 in Moose::Meta::TypeConstraint. See
173 Moose::Cookbook::Basics::Recipe4 for an example.
174 Attribute Accessor generation
176 $attr->install_accessors
177 This method overrides the parent to also install delegation
178 methods.
179 If, after installing all methods, the attribute object has no
181 associated methods, it throws an error unless "is => 'bare'" was
182 passed to the attribute constructor. (Trying to add an attribute
183 that has no associated methods is almost always an error.)
184 $attr->remove_accessors
186 This method overrides the parent to also remove delegation methods.
187 $attr->install_delegation
189 This method adds its delegation methods to the attribute's
190 associated class, if it has any to add.
191 $attr->remove_delegation
193 This method remove its delegation methods from the attribute's
194 associated class.
195 $attr->accessor_metaclass
197 Returns the accessor metaclass name, which defaults to
198 Moose::Meta::Method::Accessor.
199 $attr->delegation_metaclass
201 Returns the delegation metaclass name, which defaults to
202 Moose::Meta::Method::Delegation.
203 Additional Moose features
205 These methods are not found in the superclass. They support features
206 provided by Moose.
207 $attr->does($role)
209 This indicates whether the attribute itself does the given role.
210 The role can be given as a full class name, or as a resolvable
211 trait name.
212 Note that this checks the attribute itself, not its type
214 constraint, so it is checking the attribute's metaclass and any
215 traits applied to the attribute.
216 Moose::Meta::Class->interpolate_class_and_new($name, %options)
218 This is an alternate constructor that handles the "metaclass" and
219 "traits" options.
220 Effectively, this method is a factory that finds or creates the
222 appropriate class for the given "metaclass" and/or "traits".
223 Once it has the appropriate class, it will call "$class->new($name,
225 %options)" on that class.
226 $attr->clone_and_inherit_options(%options)
228 This method supports the "has '+foo'" feature. It does various bits
229 of processing on the supplied %options before ultimately calling
230 the "clone" method.
231 One of its main tasks is to make sure that the %options provided
233 does not include the options returned by the
234 "illegal_options_for_inheritance" method.
235 $attr->illegal_options_for_inheritance
237 This returns a blacklist of options that can not be overridden in a
238 subclass's attribute definition.
239 This exists to allow a custom metaclass to change or add to the
241 list of options which can not be changed.
242 $attr->type_constraint
244 Returns the Moose::Meta::TypeConstraint object for this attribute,
245 if it has one.
246 $attr->has_type_constraint
248 Returns true if this attribute has a type constraint.
249 $attr->verify_against_type_constraint($value)
251 Given a value, this method returns true if the value is valid for
252 the attribute's type constraint. If the value is not valid, it
253 throws an error.
254 $attr->handles
256 This returns the value of the "handles" option passed to the
257 constructor.
258 $attr->has_handles
260 Returns true if this attribute performs delegation.
261 $attr->is_weak_ref
263 Returns true if this attribute stores its value as a weak
264 reference.
265 $attr->is_required
267 Returns true if this attribute is required to have a value.
268 $attr->is_lazy
270 Returns true if this attribute is lazy.
271 $attr->is_lazy_build
273 Returns true if the "lazy_build" option was true when passed to the
274 constructor.
275 $attr->should_coerce
277 Returns true if the "coerce" option passed to the constructor was
278 true.
279 $attr->should_auto_deref
281 Returns true if the "auto_deref" option passed to the constructor
282 was true.
283 $attr->trigger
285 This is the subroutine reference that was in the "trigger" option
286 passed to the constructor, if any.
287 $attr->has_trigger
289 Returns true if this attribute has a trigger set.
290 $attr->documentation
292 Returns the value that was in the "documentation" option passed to
293 the constructor, if any.
294 $attr->has_documentation
296 Returns true if this attribute has any documentation.
297 $attr->applied_traits
299 This returns an array reference of all the traits which were
300 applied to this attribute. If none were applied, this returns
301 "undef".
302 $attr->has_applied_traits
304 Returns true if this attribute has any traits applied.
305
307 See "BUGS" in Moose for details on reporting bugs.
308
310 Stevan Little <stevan@iinteractive.com>
311 Yuval Kogman <nothingmuch@woobling.com>
313
315 Copyright 2006-2010 by Infinity Interactive, Inc.
316 <http://www.iinteractive.com>
318 This library is free software; you can redistribute it and/or modify it
320 under the same terms as Perl itself.
321perl v5.12.2 2010-08-28 Moose::Meta::Attribute(3)