5 Moose::Manual::Attribute - Object attributes with Moose
9 Attributes are the most feature-rich part of Moose, and also one of
10 the most useful. It's easy to imagine a class without roles or method
11 modifiers, but almost every class has attributes.
13 Attributes are properties that every member of a class has. For
14 example, we might say that "every Person object has a first name and
15 last name. Attributes can be optional, so that we can say "some Person
16 objects have a social security number (and some don't)".
18 At its simplest, an attribute can be thought of slot in hash that can
19 be read and set. However, attributes, can also have things like
20 default values, laziness, type constraints, delegation and much more.
24 Use the C<has> function to declare an attribute:
30 has 'first_name' => ( is => 'rw' );
32 This says that all person objects have an optional "first_name"
33 attribute that can be both read and set on the object.
35 =head2 Read-write Vs Read-only
37 The code inside the parentheses defines the details of the
38 attribute. There are a lot of options you can put here, but in the
39 simplest form you just need to include C<is>, which can be either
40 C<rw> (read-write) or C<ro> (read-only).
42 (In fact, you could even omit C<is>, but that leaves you with an
43 attribute that has no accessors, which is pointless unless you're
44 doing some deep, dark magic).
46 =head2 Accessor Methods
48 Each attribute has one or more accessor methods. An accessor lets you
49 read and write the value of the attribute for an object.
51 By default, the accessor method has the same name as the attribute. If
52 you declared your attribute as C<ro> then your accessor will be
53 read-only. If you declared it read-write, you get a read-write
56 So with our Person example above, we now have a single C<first_name>
57 accessor that can set or return a person object's first name.
59 If you want, you can also explicitly specify the method names to be
60 used for getting and setting an attribute's value. This is
61 particularly handy when you'd like an attribute to be publically
62 readable, but only privately settable. For example:
66 writer => '_set_weight',
69 This might be useful if weight is calculated based on other methods,
70 for example every time the C<eat> method is called, we might adjust
71 weight. This lets us hide the implementation details of weight
72 changes, but still provide the weight value to users of the class.
74 Some people might prefer to have distinct methods for getting and
75 setting, even when setting is a public method. In I<Perl Best
76 Practices>, Damian Conway recommends that getter methods start with
77 "get_" and setter methods start with "set_".
79 We can do exactly that by providing names for both the C<reader> and
84 reader => 'get_weight',
85 writer => 'set_weight',
88 If you're thinking that doing this over and over would be insanely
89 tedious, you're right! Fortunately, Moose provides a powerful
90 extension system that lets you do things like override the default
91 accessor method conventions. See L<Moose::Manual::MooseX> for more
94 =head2 Predicate and Clearer Methods
96 Moose is able to explicitly distinguish between false or undefined
97 values, and an attribute which is not set. If you want to be able to
98 access and manipulate these states, you also need to define clearer
99 and predicate methods for your attributes.
101 A predicate method can be used to determine whether or not a given
102 attribute is currently set. Note that even if the attribute was
103 explicitly set to undef or some other false value, the predicate will
106 The clearer method unsets the attribute. This is I<not> the
107 same as setting the value to C<undef>, but you can only distinguish
108 between them if you define a predicate method!
110 Here's some code to illustrate the relationship between an accessor,
111 predicate, and clearer method.
119 clearer => 'clear_ssn',
120 predicate => 'has_ssn',
125 my $person = Person->new();
126 $person->has_ssn; # false
129 $person->ssn; # returns undef
130 $person->has_ssn; # true
133 $person->ssn; # returns undef
134 $person->has_ssn; # false
136 $person->ssn('123-45-6789');
137 $person->ssn; # returns '123-45-6789'
138 $person->has_ssn; # true
140 my $person2 = Person->new( ssn => '111-22-3333');
141 $person2->has_ssn; # true
143 Note that by default, Moose does not make a predicate or clearer for
144 you. You have to explicitly provide a method name for the ones you
147 =head2 Required or Not?
149 By default, all attributes are optional. That means that they do not
150 need to be provided at object construction time. If you want to make
151 an attribute required, simply set the required option to true:
158 There are a couple caveats worth mentioning in regards to what
159 required actually means.
161 Basically, all it says is that this attribute must be provided to the
162 constructor. It does not say anything about its value, so it could be
165 If you define a clearer method on a required attribute, the clearer
166 I<will> work. So even though something is defined as required, you can
167 remove it after object construction.
169 So if you do make an attribute required, that probably means that
170 providing a clearer doesn't make much sense. In some cases, it might
171 be handy to have a I<private> clearer and predicate for a required
174 =head2 Default and Builder Methods
176 Attributes can have default values, and there are several ways to
179 In the simplest form, you simply provide a non-reference scalar value
180 for the "default" option:
185 predicate => 'has_size',
188 If the size attribute is not provided to the constructor, then it ends
189 up being set to "medium":
191 my $person = Person->new();
192 $person->size; # medium
193 $person->has_size; # true
195 You can also provide a subroutine reference for default. This
196 reference will be called a method on the object.
201 sub { ('small', 'medium', 'large')[ int( rand 3 ) ] },
202 predicate => 'has_size',
205 This is dumb example, but it illustrates the point that the subroutine
206 will be called for every new object created.
208 Of course, if it's called during object construction, it may be before
209 other attributes have been set. If your default is dependent on other
210 parts of the object's state, you can make the default lazy, which is
211 covered in the next section.
213 If you want to use a reference of any sort as the default value, you
214 must return it from a subroutine. This is necessary because otherwise
215 Perl would instantiate the reference exactly once, and it would be
216 shared by all objects:
220 default => {}, # wrong!
223 If Moose allowed this then the default mapping attribute could easily
224 end up shared across many objects. Instead, wrap it in a subroutine
229 default => sub { {} }, # right!
232 This is a bit awkward, but it's just the way Perl works.
234 As an alternative to using a subroutine reference, you can instead
235 supply a builder method for your attribute:
239 builder => '_build_size',
240 predicate => 'has_size',
244 return ('small', 'medium', 'large')[ int( rand 3 ) ];
247 This has several advantages. First, it moves a chunk of code to its
248 own named method, which improves readability and code
249 organization. Second, the C<_build_size> method can be overridden in
252 We strongly recommend that you use a builder instead of a default for
253 anything beyond the most trivial default.
255 =head2 Laziness and lazy_build
257 Moose lets you defer attribute population by making an attribute lazy:
262 builder => '_build_size',
265 When the lazy option is true, the attribute is not populated until the
266 reader method is called, rather than at object construction
267 time. There are several reasons you might choose to do this.
269 First, if the default value for this attribute depends on some other
270 attributes, then the attribute I<must> be lazy. During object
271 construction, default subroutine references are not called in any
272 particular order, so you cannot count on other attribute being
273 populated at that time.
275 Second, there's often no reason to spend program time calculating a
276 default before its needed. Making an attribute lazy lets you defer the
277 cost until the attribute is needed. If the attribute is I<never>
278 needed, you save some CPU time.
280 We recommend that you make any attribute with a builder or non-trivial
281 default lazy as a matter of course.
283 To facilitate this, you can simply specify the C<lazy_build> attribute
284 option. This bundles up a number of options together:
291 This is the same as specifying all of these options:
296 builder => '_build_size',
297 clearer => 'clear_size',
298 predicate => 'has_size',
301 If your attribute name starts with an underscore (_), then the clearer
302 and predicate will as well:
314 builder => '_build__size',
315 clearer => '_clear_size',
316 predicate => '_has_size',
319 Note the doubled underscore in the builder name. The lazy_build simply
320 prepends the attribute name with "_build_" to come up with the builder
323 =head2 Private Attributes