Some Notes On History

This author does not recommend you use "lazy_build", unless you know exactly what you're doing (probably) and that it's a good idea (probably not).

Nonetheless, this "lazy_build" option is why we set certain options the way we do below; while "lazy_build" in its entirety is not optimal, it had the right idea: regular, predictable accessor names for regular, predictable attribute options.

As an example, just looking at the below it doesn't seem logical that:

    has _foo => (is => 'ro', clearer => 1);

...becomes:

    has _foo => (is => 'ro', clearer => '_clear_foo');

After reading the lazy_build attribute option, however, we see that the choice had already been made for us.

is => 'rwp'

    is     => 'ro'
    writer => "_set_$name"

rwp can be read as "read + write private".

is => 'lazy'

    is       => 'ro'
    builder  => "_build_$name"
    lazy     => 1

NOTE: Since 0.009 we no longer set "init_arg => undef" if no "init_arg" is explicitly provided. This is a change made in parallel with Moo, based on a large number of people surprised that lazy also made one's "init_def" undefined.

is => 'lazy', default => ...

    is       => 'ro'
    lazy     => 1
    default  => ... # as provided

That is, if you specify "is => 'lazy'" and also provide a "default", then we won't try to set a builder, as well.

builder => 1

    builder => "_build_$name"

builder => sub { ... }

e.g., in your class (or role),

    has foo => (is => 'ro', builder => sub { 'bar!' });

...is effectively the same as...

    has foo => (is => 'ro', builder => '_build_foo');
    sub _build_foo { 'bar!' }

The behaviour of this option in roles changed in 0.030, and the builder methods will be installed in the role itself. This means you can alias/exclude/etc builder methods in roles, just as you can with any other method.

clearer => 1

    clearer => "clear_$name"

or, if your attribute name begins with an underscore:

    clearer => "_clear$name"

(that is, an attribute named "_foo" would get "_clear_foo")

predicate => 1

    predicate => "has_$name"

or, if your attribute name begins with an underscore:

    predicate => "_has$name"

(that is, an attribute named "_foo" would get "_has_foo")

init_arg => 1 / -1

Specifying "init_arg => 1" will cause the following options to be set:

    # attribute: "name"
    init_arg => 'name'

    # or, attribute: "_name"
    init_arg => '_name'

...while "init_arg => -1" will cause the following options to be set:

    # attribute: "name"
    init_arg => '_name'

    # or, attribute: "_name"
    init_arg => 'name'

trigger => 1

e.g., for an attribute named "foo" this would be equivalent to:

    trigger => sub { shift->_trigger_foo(@_) }

For an attribute named "_foo":

    trigger => sub { shift->_trigger__foo(@_) }

This naming scheme, in which the trigger is always private, is the same as the builder naming scheme (just with a different prefix).

handles => { foo => sub { ... }, ... }

e.g., the following example creates an attribute named "bar" with a standard reader accessor named "bar" and two custom accessors named "foo" and "foo_too".

    has bar => (

        is      => 'ro',
        isa     => 'Int',
        handles => {

            foo => sub {
                my $self = shift @_;

                return $_->get_value($self) + 1;
            },

            foo_too => sub {
                my $self = shift @_;

                return $self->bar + 1;
            },

            # ...as you'd expect.
            bar => 'bar',
        },
    );

...and later,

Note that in this example both foo() and foo_too() do effectively the same thing: return the attribute's current value plus 1. However, foo() accesses the attribute value directly through the metaclass, the pros and cons of which this author leaves as an exercise for the reader to determine.

You may choose to use the installed accessors to get at the attribute's value, or use the direct metaclass access, your choice.

isa => sub { ... }

    has foo => (
        is  => 'rw',
        # $_ == $_[0] == the value to be validated
        isa => sub { die unless $_[0] == 1 },
    );

    # passes constraint
    $thing->foo(1);

    # fails constraint
    $thing->foo(5);

Given a coderef, create a type constraint for the attribute. This constraint will fail if the coderef dies, and pass otherwise.

Astute users will note that this is the same way Moo constraints work; we use MooseX::Meta::TypeConstraint::Mooish to implement the constraint.

isa_instance_of => ...

    has foo => (is => 'ro', isa_instance_of => 'SomeThing');

...is effectively the same as:

    use Moose::TypeConstraints 'class_type';
    has foo => (
        is  => 'ro',
        isa => class_type('SomeThing'),
    );

...but a touch less awkward.

isa => ..., constraint => sub { ... }

For example, only integers greater than 10 will pass this attribute's type constraint:

    # value must be an integer greater than 10 to pass the constraint
    has thinger => (
        isa        => 'Int',
        constraint => sub { $_ > 10 },
        # ...
    );

Note that if you supply a constraint, you must also provide an "isa".

isa => ..., constraint => sub { ... }, coerce => 1

For example, let's say that you're using the "File" type constraint from MooseX::Types::Path::Class, and you want an additional constraint that the file must exist:

    has thinger => (
        is         => 'ro',
        isa        => File,
        constraint => sub { !! $_->stat },
        coerce     => 1,
    );

"thinger" will correctly coerce the string "/etc/passwd" to a "Path::Class:File", and will only accept the coerced result as a value if the file exists.

coerce => [ Type => sub { ...coerce... }, ... ]

    has bar => (
        is     => 'ro',
        isa    => 'Str',
        coerce => [
            Int    => sub { "$_"                       },
            Object => sub { 'An instance of ' . ref $_ },
        ],
    );

MooseX::SemiAffordanceAccessor

• "is => 'rwp'"

  This:

      has  foo => (is => 'rwp');
      has _bar => (is => 'rwp');
      

  ...is now effectively equivalent to:

      has foo  => (is => 'ro', writer => '_set_foo');
      has _bar => (is => 'ro', writer => '_set_bar')
      

• "-writer_prefix" is ignored

  ...as MooseX::SemiAffordanceAccessor has its own specific ideas as to how writers should look.