I think I've covered all the things that need covering. Still need to

[gitmo/Moose.git] / lib / Moose / Manual / Attributes.pod

=pod

=head1 NAME

Moose::Manual::Attribute - Object attributes with Moose

=head1 INTRODUCTION

Attributes are the most feature-rich part of Moose, and also one of
the most useful. It's easy to imagine a class without roles or method
modifiers, but almost every class has attributes.

Attributes are properties that every member of a class has. For
example, we might say that "every Person object has a first name and
last name. Attributes can be optional, so that we can say "some Person
objects have a social security number (and some don't)".

At its simplest, an attribute can be thought of slot in hash that can
be read and set. However, attributes, can also have things like
default values, laziness, type constraints, delegation and much more.

=head1 ATTRIBUTE OPTIONS

Use the C<has> function to declare an attribute:

  package Person;

  use Moose;

  has 'first_name' => ( is => 'rw' );

This says that all person objects have an optional "first_name"
attribute that can be both read and set on the object.

=head2 Read-write Vs Read-only

The code inside the parentheses defines the details of the
attribute. There are a lot of options you can put here, but in the
simplest form you just need to include C<is>, which can be either
C<rw> (read-write) or C<ro> (read-only).

(In fact, you could even omit C<is>, but that leaves you with an
attribute that has no accessors, which is pointless unless you're
doing some deep, dark magic).

=head2 Accessor Methods

Each attribute has one or more accessor methods. An accessor lets you
read and write the value of the attribute for an object.

By default, the accessor method has the same name as the attribute. If
you declared your attribute as C<ro> then your accessor will be
read-only. If you declared it read-write, you get a read-write
accessor. Simple.

So with our Person example above, we now have a single C<first_name>
accessor that can set or return a person object's first name.

If you want, you can also explicitly specify the method names to be
used for reading and writing an attribute's value. This is
particularly handy when you'd like an attribute to be publically
readable, but only privately settable. For example:

  has 'weight' =>
      ( is     => 'rw',
        writer => '_set_weight',
      );

This might be useful if weight is calculated based on other methods,
for example every time the C<eat> method is called, we might adjust
weight. This lets us hide the implementation details of weight
changes, but still provide the weight value to users of the class.

Some people might prefer to have distinct methods for reading and
writing, even when writing is a public method. In I<Perl Best
Practices>, Damian Conway recommends that reader methods start with
"get_" and writer methods start with "set_".

We can do exactly that by providing names for both the C<reader> and
C<writer> methods:

  has 'weight' =>
      ( is     => 'rw',
        reader => 'get_weight',
        writer => 'set_weight',
      );

If you're thinking that doing this over and over would be insanely
tedious, you're right! Fortunately, Moose provides a powerful
extension system that lets you do things like override the default
accessor method conventions. See L<Moose::Manual::MooseX> for more
details.

=head2 Predicate and Clearer Methods

Moose is able to explicitly distinguish between false or undefined
values, and an attribute which is not set. If you want to be able to
access and manipulate these states, you also need to define clearer
and predicate methods for your attributes.

A predicate method can be used to determine whether or not a given
attribute is currently set. Note that even if the attribute was
explicitly set to undef or some other false value, the predicate will
return true.

The clearer method unsets the attribute. This is I<not> the
same as setting the value to C<undef>, but you can only distinguish
between them if you define a predicate method!

Here's some code to illustrate the relationship between an accessor,
predicate, and clearer method.

  package Person;

  use Moose;

  has 'ssn' =>
      ( is        => 'rw',
        clearer   => 'clear_ssn',
        predicate => 'has_ssn',
      );

  ...

  my $person = Person->new();
  $person->has_ssn; # false

  $person->ssn(undef);
  $person->ssn; # returns undef
  $person->has_ssn; # true

  $person->clear_ssn;
  $person->ssn; # returns undef
  $person->has_ssn; # false

  $person->ssn('123-45-6789');
  $person->ssn; # returns '123-45-6789'
  $person->has_ssn; # true

  my $person2 = Person->new( ssn => '111-22-3333');
  $person2->has_ssn; # true

Note that by default, Moose does not make a predicate or clearer for
you. You have to explicitly provide a method name for the ones you
want.

=head2 Required or Not?

By default, all attributes are optional. That means that they do not
need to be provided at object construction time. If you want to make
an attribute required, simply set the C<required> option to true:

  has 'name' =>
      ( is       => 'rw',
        required => 1,
      );

There are a couple caveats worth mentioning in regards to what
required actually means.

Basically, all it says is that this attribute must be provided to the
constructor. It does not say anything about its value, so it could be
C<undef>.

If you define a clearer method on a required attribute, the clearer
I<will> work. So even though something is defined as required, you can
remove it after object construction.

So if you do make an attribute required, that probably means that
providing a clearer doesn't make much sense. In some cases, it might
be handy to have a I<private> C<clearer> and C<predicate> for a
required attribute.

=head2 Default and Builder Methods

Attributes can have default values, and there are several ways to
specify this.

In the simplest form, you simply provide a non-reference scalar value
for the C<default> option:

  has 'size' =>
      ( is        => 'rw',
        default   => 'medium',
        predicate => 'has_size',
      );

If the size attribute is not provided to the constructor, then it ends
up being set to "medium":

  my $person = Person->new();
  $person->size; # medium
  $person->has_size; # true

You can also provide a subroutine reference for C<default>. This
reference will be called a method on the object.

  has 'size' =>
      ( is        => 'rw',
        default   =>
            sub { ('small', 'medium', 'large')[ int( rand 3 ) ] },
        predicate => 'has_size',
      );

This is dumb example, but it illustrates the point that the subroutine
will be called for every new object created.

Of course, if it's called during object construction, it may be before
other attributes have been set. If your default is dependent on other
parts of the object's state, you can make the default c<lazy>, which
is covered in the next section.

If you want to use a reference of any sort as the default value, you
must return it from a subroutine. This is necessary because otherwise
Perl would instantiate the reference exactly once, and it would be
shared by all objects:

  has 'mapping' =>
      ( is      => 'rw',
        default => {}, # wrong!
      );

If Moose allowed this then the default mapping attribute could easily
end up shared across many objects. Instead, wrap it in a subroutine
reference:

  has 'mapping' =>
      ( is      => 'rw',
        default => sub { {} }, # right!
      );

This is a bit awkward, but it's just the way Perl works.

As an alternative to using a subroutine reference, you can instead
supply a C<builder> method for your attribute:

  has 'size' =>
      ( is        => 'rw',
        builder   => '_build_size',
        predicate => 'has_size',
      );

  sub _build_size {
      return ('small', 'medium', 'large')[ int( rand 3 ) ];
  }

This has several advantages. First, it moves a chunk of code to its
own named method, which improves readability and code
organization. Second, the C<_build_size> method can be overridden in
subclasses.

We strongly recommend that you use a C<builder> instead of a
C<default> for anything beyond the most trivial default.

=head2 Laziness and lazy_build

Moose lets you defer attribute population by making an attribute
C<lazy>:

  has 'size' =>
      ( is        => 'rw',
        lazy      => 1,
        builder   => '_build_size',
      );

When the C<lazy> option is true, the attribute is not populated until
the reader method is called, rather than at object construction
time. There are several reasons you might choose to do this.

First, if the default value for this attribute depends on some other
attributes, then the attribute I<must> be C<lazy>. During object
construction, default subroutine references are not called in any
particular order, so you cannot count on other attribute being
populated at that time.

Second, there's often no reason to spend program time calculating a
default before its needed. Making an attribute C<lazy> lets you defer
the cost until the attribute is needed. If the attribute is I<never>
needed, you save some CPU time.

We recommend that you make any attribute with a builder or non-trivial
default C<lazy> as a matter of course.

To facilitate this, you can simply specify the C<lazy_build> attribute
option. This bundles up a number of options together:

  has 'size' =>
      ( is         => 'rw',
        lazy_build => 1,
      );

This is the same as specifying all of these options:

  has 'size' =>
      ( is        => 'rw',
        lazy      => 1,
        builder   => '_build_size',
        clearer   => 'clear_size',
        predicate => 'has_size',
      );

If your attribute name starts with an underscore (_), then the clearer
and predicate will as well:

  has '_size' =>
      ( is         => 'rw',
        lazy_build => 1,
      );

becomes:

  has '_size' =>
      ( is        => 'rw',
        lazy      => 1,
        builder   => '_build__size',
        clearer   => '_clear_size',
        predicate => '_has_size',
      );

Note the doubled underscore in the builder name. Internally, Moose
simply prepends the attribute name with "_build_" to come up with the
builder name.

If you don't like the names that C<lazy_build> generates, you can
always provide your own:

  has 'size' =>
      ( is         => 'rw',
        lazy_build => 1,
        clearer    => '_has_size',
      );

Options that you explicitly provide are always used in favor of
Moose's internal defaults.

=head2 Weak References

Moose has built-in support for weak references. If you set the
C<weak_ref> to a true value for the attribute, then it will call
C<Scalar::Util::weaken> whenever the attribute is set:

  has 'parent' =>
      ( is       => 'rw',
        weak_ref => 1,
      );

  $node->parent($parent_node);

This is very useful when you're building objects that may contain
circular references.

=head2 Triggers

You can provide a C<trigger> option as a subroutine reference which
will be called whenever the attribute is set:

  has 'size' =>
      ( is      => 'rw',
        trigger => \&_size_set,
      );

  sub _size_set {
      my ( $self, $size, $meta_attr ) = @_;

      print $self->name, " size is now $size\n";
  }

The trigger is called as a method, and receives the new value as well
as the L<Moose::Meta::Attribute> object for the attribute.

=head2 Attribute Types

Attributes can be restriced to only accept certain types:

  has 'first_name' =>
      ( is  => 'rw',
        isa => 'Str',
      );

This says that the first_name attribute must be a string.

Moose also provides a shortcut for specifying that an attribute only
accepts objects that do a certain role:

  has 'weapon' =>
     ( is   => 'rw',
       does => 'MyApp::Weapon',
     );

See the L<Moose::Manual::Types> documentation for a complete
discussion of Moose's type system.

=head2 Delegation

Attributes can define delegations to their values:

  has 'hair_color' =>
      ( is      => 'rw',
        isa     => 'Graphics::Color::RGB',
        handles => { hair_color_hex => 'as_hex_string' },
      );

This adds a new method, C<hair_color_hex>. Internally, this just calls
C<< $self->hair_color->as_hex_string >>.

See L<Moose::Manual::Delegation> for more details on how to set up
delegation methods.

=head2 Metaclass and traits

One of Moose's best features is that it can be extended in all sorts
of ways through the use of new metaclasses and metaclass traits.

When declaring an attribute, you can declare a metaclass or a set of
traits for the attribute:

  use MooseX::AttributeHelpers;

  has 'mapping' =>
      ( metaclass => 'Collection::Hash',
        is        => 'ro',
        default   => sub { {} },
      );

In this case, the metaclass C<Collection::Hash> really refers to
C<MooseX::AttributeHelpers::Collection::Hash>.

You can also apply one or more traits to an attribute:


  use MooseX::MetaDescription;

  has 'size' =>
      ( is          => 'rw',
        traits      => [ 'MooseX::MetaDescription::Meta::Trait' ],
        description => { html_widget  => 'text_input',
                         serialize_as => 'element',
                       },
      );

The advantage of traits is that you can mix more than one of them
together easily (in fact, a trait is just a role under the hood).

There are a number of MooseX modules on CPAN which provide useful
attribute metaclasses and traits. See L<Moose::Manual::MooseX> for
some examples. You can also write your own metaclasses and traits. See
the "Meta" and "Extending" recipes in L<Moose::Cookbook> for examples.

=head2 Attribute Inheritance

By default, a child inherits all of its parent class(es)' attributes
as-is. You can explicitly change some aspects of the inherited
attribute in the child class.

The options that can be overridden in a subclass are:

=over 4

=item * default

=item * coerce

=item * required

=item * documentation

=item * lazy

=item * isa

=item * handles

=item * builder

=item * metaclass

=item * traits

=back

To override an attribute, you simply prepend its name with a plus sign
(+):

  package LazyPerson;

  use Moose;

  extends 'Person';

  has '+first_name' =>
      ( lazy    => 1,
        default => 'Bill',
      );

Now the C<first_name> attribute in C<LazyPerson> is lazy, and defaults
to C<'Bill'>.

We recommend that you exercise caution when changing the type (C<isa>)
of an inherited attribute. It's best to only make the new type a
subtype of the one accepted by the parent.

=head2 The C<documentation> option

You can provide a piece of documentation as a string for an attribute:

  has 'first_name' =>
      ( is            => 'rw',
        documentation => q{The person's first (personal) name},
      );

Moose does absolutely nothing with this information other than store
it.

As an alternative, you might want to look at the
C<MooseX::MetaDescription> module, which lets you attach a
"description" to each attribute. This description is a hashref that
can include meta-information intended for use in other code, as well
as documentation information.

=head2 The C<auto_deref> Option

If your attribute is an array reference or hash reference, the
C<auto_deref> option will make Moose de-reference the value when it is
returned from the reader method:

  my %map = $object->mapping;

This option only works if your attribute is explicitly typed as an
ArrayRef or HashRef.

However, we recommend that you use C<MooseX::AttributeHelpers> for
these types of attributes, which gives you much more control over how
they are accessed and manipulated.

=head2 Initializer

Moose provides an attribute option called C<initializer>. This is
similar to C<builder>, except that it is I<only> called during object
construction.

This option is inherited from C<Class::MOP>, but we recommend that you
use a C<builder> (which is Moose-only) instead.

=head1 MORE ON ATTRIBUTES

Moose attributes are a big topic, and this document glosses over a few
topics. We recommend that you read the L<Moose::Manual::Delegation>
and L<Moose::Manual::Types> documents to get a more complete
understanding of attribute features.