1 package Moose::Manual::Attributes;
3 # ABSTRACT: Object attributes with Moose
11 Moose attributes have many properties, and attributes are probably the
12 single most powerful and flexible part of Moose. You can create a
13 powerful class simply by declaring attributes. In fact, it's possible
14 to have classes that consist solely of attribute declarations.
16 An attribute is a property that every member of a class has. For
17 example, we might say that "every C<Person> object has a first name and
18 last name". Attributes can be optional, so that we can say "some C<Person>
19 objects have a social security number (and some don't)".
21 At its simplest, an attribute can be thought of as a named value (as
22 in a hash) that can be read and set. However, attributes can also have
23 defaults, type constraints, delegation and much more.
25 In other languages, attributes are also referred to as slots or
28 =head1 ATTRIBUTE OPTIONS
30 Use the C<has> function to declare an attribute:
36 has 'first_name' => ( is => 'rw' );
38 This says that all C<Person> objects have an optional read-write
39 "first_name" attribute.
41 =head2 Read-write vs. read-only
43 The options passed to C<has> define the properties of the attribute. There are
44 many options, but in the simplest form you just need to set C<is>, which can
45 be either C<ro> (read-only) or C<rw> (read-write). When an attribute is C<rw>,
46 you can change it by passing a value to its accessor. When an attribute is
47 C<ro>, you may only read the current value of the attribute.
49 In fact, you could even omit C<is>, but that gives you an attribute
50 that has no accessor. This can be useful with other attribute options,
51 such as C<handles>. However, if your attribute generates I<no>
52 accessors, Moose will issue a warning, because that usually means the
53 programmer forgot to say the attribute is read-only or read-write. If
54 you really mean to have no accessors, you can silence this warning by
55 setting C<is> to C<bare>.
57 =head2 Accessor methods
59 Each attribute has one or more accessor methods. An accessor lets you
60 read and write the value of that attribute for an object.
62 By default, the accessor method has the same name as the attribute. If
63 you declared your attribute as C<ro> then your accessor will be
64 read-only. If you declared it read-write, you get a read-write
67 Given our C<Person> example above, we now have a single C<first_name>
68 accessor that can read or write a C<Person> object's C<first_name>
71 If you want, you can also explicitly specify the method names to be
72 used for reading and writing an attribute's value. This is
73 particularly handy when you'd like an attribute to be publicly
74 readable, but only privately settable. For example:
78 writer => '_set_weight',
81 This might be useful if weight is calculated based on other methods.
82 For example, every time the C<eat> method is called, we might adjust
83 weight. This lets us hide the implementation details of weight
84 changes, but still provide the weight value to users of the class.
86 Some people might prefer to have distinct methods for reading and
87 writing. In I<Perl Best Practices>, Damian Conway recommends that
88 reader methods start with "get_" and writer methods start with "set_".
90 We can do exactly that by providing names for both the C<reader> and
95 reader => 'get_weight',
96 writer => 'set_weight',
99 If you're thinking that doing this over and over would be insanely
100 tedious, you're right! Fortunately, Moose provides a powerful
101 extension system that lets you override the default naming
102 conventions. See L<Moose::Manual::MooseX> for more details.
104 =head2 Predicate and clearer methods
106 Moose allows you to explicitly distinguish between a false or
107 undefined attribute value and an attribute which has not been set. If
108 you want to access this information, you must define clearer and
109 predicate methods for an attribute.
111 A predicate method tells you whether or not a given attribute is
112 currently set. Note that an attribute can be explicitly set to
113 C<undef> or some other false value, but the predicate will return
116 The clearer method unsets the attribute. This is I<not> the
117 same as setting the value to C<undef>, but you can only distinguish
118 between them if you define a predicate method!
120 Here's some code to illustrate the relationship between an accessor,
121 predicate, and clearer method.
129 clearer => 'clear_ssn',
130 predicate => 'has_ssn',
135 my $person = Person->new();
136 $person->has_ssn; # false
139 $person->ssn; # returns undef
140 $person->has_ssn; # true
143 $person->ssn; # returns undef
144 $person->has_ssn; # false
146 $person->ssn('123-45-6789');
147 $person->ssn; # returns '123-45-6789'
148 $person->has_ssn; # true
150 my $person2 = Person->new( ssn => '111-22-3333');
151 $person2->has_ssn; # true
153 By default, Moose does not make a predicate or clearer for you. You must
154 explicitly provide names for them, and then Moose will create the methods
157 =head2 Required or not?
159 By default, all attributes are optional, and do not need to be
160 provided at object construction time. If you want to make an attribute
161 required, simply set the C<required> option to true:
168 There are a couple caveats worth mentioning in regards to what
169 "required" actually means.
171 Basically, all it says is that this attribute (C<name>) must be provided to
172 the constructor, or be lazy with either a default or a builder. It does not
173 say anything about its value, so it could be C<undef>.
175 If you define a clearer method on a required attribute, the clearer
176 I<will> work, so even a required attribute can be unset after object
179 This means that if you do make an attribute required, providing a
180 clearer doesn't make much sense. In some cases, it might be handy to
181 have a I<private> C<clearer> and C<predicate> for a required
184 =head2 Default and builder methods
186 Attributes can have default values, and Moose provides two ways to
187 specify that default.
189 In the simplest form, you simply provide a non-reference scalar value
190 for the C<default> option:
195 predicate => 'has_size',
198 If the size attribute is not provided to the constructor, then it ends
199 up being set to C<medium>:
201 my $person = Person->new();
202 $person->size; # medium
203 $person->has_size; # true
205 You can also provide a subroutine reference for C<default>. This
206 reference will be called as a method on the object.
211 sub { ( 'small', 'medium', 'large' )[ int( rand 3 ) ] },
212 predicate => 'has_size',
215 This is a trivial example, but it illustrates the point that the subroutine
216 will be called for every new object created.
218 When you provide a C<default> subroutine reference, it is called as a
219 method on the object, with no additional parameters:
226 return $self->height > 200 ? 'large' : 'average';
230 When the C<default> is called during object construction, it may be
231 called before other attributes have been set. If your default is
232 dependent on other parts of the object's state, you can make the
233 attribute C<lazy>. Laziness is covered in the next section.
235 If you want to use a reference of any sort as the default value, you
236 must return it from a subroutine.
240 default => sub { {} },
243 This is necessary because otherwise Perl would instantiate the reference
244 exactly once, and it would be shared by all objects:
248 default => {}, # wrong!
251 Moose will throw an error if you pass a bare non-subroutine reference
254 If Moose allowed this then the default mapping attribute could easily
255 end up shared across many objects. Instead, wrap it in a subroutine
256 reference as we saw above.
258 This is a bit awkward, but it's just the way Perl works.
260 As an alternative to using a subroutine reference, you can supply a C<builder>
261 method for your attribute:
265 builder => '_build_size',
266 predicate => 'has_size',
270 return ( 'small', 'medium', 'large' )[ int( rand 3 ) ];
273 This has several advantages. First, it moves a chunk of code to its own named
274 method, which improves readability and code organization. Second, because this
275 is a I<named> method, it can be subclassed or provided by a role.
277 We strongly recommend that you use a C<builder> instead of a
278 C<default> for anything beyond the most trivial default.
280 A C<builder>, just like a C<default>, is called as a method on the
281 object with no additional parameters.
283 =head3 Builders allow subclassing
285 Because the C<builder> is called I<by name>, it goes through Perl's
286 method resolution. This means that builder methods are both
287 inheritable and overridable.
289 If we subclass our C<Person> class, we can override C<_build_size>:
296 sub _build_size { return 'small' }
298 =head3 Builders work well with roles
300 Because builders are called by name, they work well with roles. For
301 example, a role could provide an attribute but require that the
302 consuming class provide the C<builder>:
307 requires '_build_size';
312 builder => '_build_size',
320 sub _build_size { return 'small' }
322 Roles are covered in L<Moose::Manual::Roles>.
326 Moose lets you defer attribute population by making an attribute
332 builder => '_build_size',
335 When C<lazy> is true, the default is not generated until the reader
336 method is called, rather than at object construction time. There are
337 several reasons you might choose to do this.
339 First, if the default value for this attribute depends on some other
340 attributes, then the attribute I<must> be C<lazy>. During object
341 construction, defaults are not generated in a predictable order, so
342 you cannot count on some other attribute being populated when
343 generating a default.
345 Second, there's often no reason to calculate a default before it's
346 needed. Making an attribute C<lazy> lets you defer the cost until the
347 attribute is needed. If the attribute is I<never> needed, you save
350 We recommend that you make any attribute with a builder or non-trivial
351 default C<lazy> as a matter of course.
353 =head2 Constructor parameters (C<init_arg>)
355 By default, each attribute can be passed by name to the class's
356 constructor. On occasion, you may want to use a different name for
357 the constructor parameter. You may also want to make an attribute
358 unsettable via the constructor.
360 You can do either of these things with the C<init_arg> option:
367 Now we have an attribute named "bigness", but we pass C<size> to the
370 Even more useful is the ability to disable setting an attribute via
371 the constructor. This is particularly handy for private attributes:
373 has '_genetic_code' => (
376 builder => '_build_genetic_code',
380 By setting the C<init_arg> to C<undef>, we make it impossible to set
381 this attribute when creating a new object.
383 =head2 Weak references
385 Moose has built-in support for weak references. If you set the
386 C<weak_ref> option to a true value, then it will call
387 C<Scalar::Util::weaken> whenever the attribute is set:
394 $node->parent($parent_node);
396 This is very useful when you're building objects that may contain
401 A C<trigger> is a subroutine that is called whenever the attribute is
406 trigger => \&_size_set,
410 my ( $self, $size, $old_size ) = @_;
412 my $msg = $self->name;
415 $msg .= " - old size was $old_size";
418 $msg .= " - size is now $size";
422 The trigger is called I<after> an attribute's value is set. It is
423 called as a method on the object, and receives the new and old values as
424 its arguments. If the attribute had not previously been set at all,
425 then only the new value is passed. This lets you distinguish between
426 the case where the attribute had no value versus when the old value was C<undef>.
428 This differs from an C<after> method modifier in two ways. First, a
429 trigger is only called when the attribute is set, as opposed to
430 whenever the accessor method is called (for reading or
431 writing). Second, it is also called when an attribute's value is
432 passed to the constructor.
434 However, triggers are I<not> called when an attribute is populated
435 from a C<default> or C<builder>
437 =head2 Attribute types
439 Attributes can be restricted to only accept certain types:
441 has 'first_name' => (
446 This says that the C<first_name> attribute must be a string.
448 Moose also provides a shortcut for specifying that an attribute only
449 accepts objects that do a certain role:
453 does => 'MyApp::Weapon',
456 See the L<Moose::Manual::Types> documentation for a complete
457 discussion of Moose's type system.
461 An attribute can define methods which simply delegate to its value:
463 has 'hair_color' => (
465 isa => 'Graphics::Color::RGB',
466 handles => { hair_color_hex => 'as_hex_string' },
469 This adds a new method, C<hair_color_hex>. When someone calls
470 C<hair_color_hex>, internally, the object just calls C<<
471 $self->hair_color->as_hex_string >>.
473 See L<Moose::Manual::Delegation> for documentation on how to set up
476 =head2 Attribute traits and metaclasses
478 One of Moose's best features is that it can be extended in all sorts of ways
479 through the use of metaclass traits and custom metaclasses.
481 You can apply one or more traits to an attribute:
483 use MooseX::MetaDescription;
487 traits => ['MooseX::MetaDescription::Meta::Trait'],
489 html_widget => 'text_input',
490 serialize_as => 'element',
494 The advantage of traits is that you can mix more than one of them
495 together easily (in fact, a trait is just a role under the hood).
497 There are a number of MooseX modules on CPAN which provide useful
498 attribute metaclasses and traits. See L<Moose::Manual::MooseX> for
499 some examples. You can also write your own metaclasses and traits. See
500 the "Meta" and "Extending" recipes in L<Moose::Cookbook> for examples.
502 =head2 Native Delegations
504 Native delegations allow you to delegate to standard Perl data structures as
505 if they were objects.
507 For example, we can pretend that an array reference has methods like
508 C<push()>, C<shift()>, C<map()>, C<count()>, and more.
513 isa => 'ArrayRef[Str]',
514 default => sub { [] },
516 all_options => 'elements',
517 add_option => 'push',
518 map_options => 'map',
519 option_count => 'count',
520 sorted_options => 'sort',
524 See L<Moose::Manual::Delegation> for more details.
526 =head1 ATTRIBUTE INHERITANCE
528 By default, a child inherits all of its parent class(es)' attributes
529 as-is. However, you can change most aspects of the inherited attribute in the
530 child class. You cannot change any of its associated method names (reader,
531 writer, predicate, etc).
533 To override an attribute, you simply prepend its name with a plus sign
542 has '+first_name' => (
547 Now the C<first_name> attribute in C<LazyPerson> is lazy, and defaults
550 We recommend that you exercise caution when changing the type (C<isa>)
551 of an inherited attribute.
553 =head1 MULTIPLE ATTRIBUTE SHORTCUTS
555 If you have a number of attributes that differ only by name, you can declare
562 has [ 'x', 'y' ] => ( is => 'ro', isa => 'Int' );
564 Also, because C<has> is just a function call, you can call it in a loop:
566 for my $name ( qw( x y ) ) {
567 my $builder = '_build_' . $name;
568 has $name => ( is => 'ro', isa => 'Int', builder => $builder );
571 =head1 MORE ON ATTRIBUTES
573 Moose attributes are a big topic, and this document glosses over a few
574 aspects. We recommend that you read the L<Moose::Manual::Delegation>
575 and L<Moose::Manual::Types> documents to get a more complete
576 understanding of attribute features.
578 =head1 A FEW MORE OPTIONS
580 Moose has lots of attribute options. The ones listed below are
581 superseded by some more modern features, but are covered for the sake
584 =head2 The C<documentation> option
586 You can provide a piece of documentation as a string for an attribute:
588 has 'first_name' => (
590 documentation => q{The person's first (personal) name},
593 Moose does absolutely nothing with this information other than store
596 =head2 The C<auto_deref> option
598 If your attribute is an array reference or hash reference, the
599 C<auto_deref> option will make Moose dereference the value when it is
600 returned from the reader method:
602 my %map = $object->mapping;
604 This option only works if your attribute is explicitly typed as an
605 C<ArrayRef> or C<HashRef>.
607 However, we recommend that you use L<Moose::Meta::Attribute::Native> traits
608 for these types of attributes, which gives you much more control over how
609 they are accessed and manipulated.
613 Moose provides an attribute option called C<initializer>. This is called when
614 the attribute's value is being set in the constructor, and lets you change the
615 value before it is set.