What's the Point.pm?

Let's take a look at a simple "Point" class in Moose. We want it to have x/y coordinates, and the creation time as "seconds from epoch". We'd also like to be able to "invert" points.

    package My::Point {
        use Moose;
        has 'x'       => ( is => 'rw', isa => 'Num', writer  => 'set_x' );
        has 'y'       => ( is => 'rw', isa => 'Num', writer  => 'set_y' );
        has 'created' => ( is => 'ro', isa => 'Int', default => sub {time} );
        sub invert {
            my $self = shift;
            my ( $x, $y ) = ( $self->x, $self->y );
            $self->set_x($y);
            $self->set_y($x);
        }
    }
    1;

To the casual eye, that looks fine, but there are already many issues with the above.

• The class is not immutable

  You almost always want to end your Moose classes with "__PACKAGE__->meta->make_immutable". Doing this causes Moose to close the class definition for modifications (if that doesn't make sense, don't worry about it), and speeds up the code considerably.

• Dirty namespace

  Currently, "My::Point->can('has')" returns true, even though "has" should not be a method. This, along with a bunch of other functions exported into your class by Moose, can mislead your code and confuse your method resolution order. For this reason, it's generally recommended that you use "namespace::autoclean" or "namespace::clean". To remove those functions from your class.

• Unknown constructor arguments

      my $point = My::Point->new( X => 3, y => 4 );
      

  In the above, the first named argument should be "x", not "X". Moose simply throws away unknown constructor arguments. One way to handle this might be to set your fields as "required":

      has 'x' => ( is => 'rw', isa => 'Num', writer  => 'set_x', required => 1 );
      has 'x' => ( is => 'rw', isa => 'Num', writer  => 'set_y', required => 1 );
      

  That causes "My::Point->new( X => 3, y => 4 )" to throw an exception, but not this: "My::Point->new( x => 3, y => 4, z => 5 )". For this trivial example, it's probably not a big deal, but for a large codebase, where many Moose classes might have a huge variety of confusing arguments, it's easy to make mistakes.

  For this, we recommend MooseX::StrictConstructor. Unknown arguments are fatal.

• Innappropriate constructor arguments

      my $point = My::Point->new( x => 3, y => 4, created => 42 );
      

  The above works, but the author of the class almost certainly didn't intend for you to be passing "created" to the constructor, but to the programmer reading the code, that's not always clear:

      has 'created' => ( is => 'ro', isa => 'Int', default => sub {time} );
      

  The fix for this is to add "init_arg => undef" to the attribute definition and hope the maintenance programmer notices this:

      has 'created' => ( is => 'ro', isa => 'Int', init_arg => undef, default => sub {time} );
      

• Misspelled types

  What if "created" was defined like this?

      has 'created' => ( is => 'ro', isa => 'int', default => sub {time} );
      

  The type constraint is named "Int", not "int". You won't find out about that little issue until runtime. There are a number of ways of dealing with this, but we recommend the Type::Tiny family of type constraints. Misspelling a type name becomes a compile-time failure:

      use Types::Standard 'Int';
      has 'created' => ( is => 'ro', isa => Int, default => sub {time} );
      

• No signatures

  Let's look at our method:

          sub invert {
              my $self = shift;
              my ( $x, $y ) = ( $self->x, $self->y );
              $self->set_x($y);
              $self->set_y($x);
          }
      

  What if someone were to write "$point->invert( 4, 7 )"? That wouldn't make any sense, but it also wouldn't throw an exception or even a warning, despite it obviously not being what the programmer wanted. The simplest solution is to just use signatures:

      use feature 'signatures';
      no warnings 'experimental::signatures'; # 5.34 and below
      sub invert ($self) { ... }
      

Fixing our Moose class

Taking all of the above into consideration, we might rewrite our Moose class as follows:

    package My::Point {
        use Moose;
        use MooseX::StrictConstructor;
        use Types::Standard qw(Num Int);
        use feature 'signatures';
        no warnings 'experimental::signatures';
        use namespace::autoclean;
        has 'x'       => ( is => 'rw', isa => Num, writer  => 'set_x' );
        has 'y'       => ( is => 'rw', isa => Num, writer  => 'set_y' );
        has 'created' => ( is => 'ro', isa => Int, init_arg => undef, default => sub {time} );
        sub invert ($self) {
            my ( $x, $y ) = ( $self->x, $self->y );
            $self->set_x($y);
            $self->set_y($x);
        }
        __PACKAGE__->meta->make_immutable;
    }
    1;

That's a lot of boilerplate for a simple x/y point class! Out of the box (but almost completely customisable), MooseX::Extended provides the above for you.

    package My::Point {
        use MooseX::Extended types => [qw/Num Int/];
        param [ 'x', 'y' ] => ( is => 'rw', isa => Num, writer => 1 );
        field 'created'    => ( isa => Int, lazy => 0, default => sub {time} );
        sub invert ($self) {
            my ( $x, $y ) = ( $self->x, $self->y );
            $self->set_x($y);
            $self->set_y($x);
        }
    }

No need use those various modules. No need to declare the class immutable or end it with a true value (MooseX::Extended does these for you). Instead of remembering a bunch of boilerplate, you can focus on writing your code.

"param"

    param name => ( isa => NonEmptyStr );

A similar function to Moose's "has". A "param" is required. You may pass it to the constructor, or use a "default" or "builder" to supply this value.

The above "param" definition is equivalent to:

    has name => (
        is       => 'ro',
        isa      => NonEmptyStr,
        required => 1,
    );

If you want a parameter that has no "default" or "builder" and can optionally be passed to the constructor, just use "required => 0".

    param title => ( isa => Str, required => 0 );

Note that "param", like "field", defaults to read-only, "is => 'ro'". You can override this:

    param name => ( is => 'rw',  isa => NonEmptyStr );
    # or
    param name => ( is => 'rwp', isa => NonEmptyStr ); # adds _set_name

Otherwise, it behaves like "has". You can pass in any arguments that "has" accepts.

    # we'll make it private, but allow it to be passed to the constructor
    # as `name`
    param _name   => ( isa => NonEmptyStr, init_arg => 'name' );

The "param"'s "is" option accepts "rwp", like Moo. It will create a writer in the name "_set_${attribute_name|".

"field"

    field cache => (
        isa     => InstanceOf ['Hash::Ordered'],
        default => sub { Hash::Ordered->new },
    );

A similar function to Moose's "has". A "field" is not intended to be passed to the constructor, but you can still use "default" or "builder", as normal.

The above "field" definition is equivalent to:

    has cache => (
        is       => 'ro',
        isa      => InstanceOf['Hash::Ordered'],
        init_arg => undef,        # not allowed in the constructor
        default  => sub { Hash::Ordered->new },
        lazy     => 1,
    );

Note that "field", like "param", defaults to read-only, "is => 'ro'". You can override this:

    field some_data => ( is => 'rw',  isa => NonEmptyStr );
    #
    field some_data => ( is => 'rwp', isa => NonEmptyStr ); # adds _set_some_data

Otherwise, it behaves like "has". You can pass in any arguments that "has" accepts.

The "field"'s "is" option accepts "rwp", like Moo. It will create a writer in the name "_set_${attribute_name|".

If you pass "field" an "init_arg" with a defined value, the code will usually throw a Moose::Exception::InvalidAttributeDefinition exception. However, if the init_arg begins with an underscore, it's allowed. This is designed to allow developers writing tests to supply their own values more easily.

    field cache => (
        isa      => InstanceOf ['Hash::Ordered'],
        default  => sub { Hash::Ordered->new },
        init_arg => '_cache',
    );

With the above, you can pass "_cache => $my_testing_cache" in the constructor.

A "field" is automatically lazy if it has a "builder" or "default". This is because there's no guarantee the code will call them, but this makes it very easy for a "field" to rely on a "param" value being present. It's a common problem in Moose that attribute initialization order is alphabetical order and if you define an attribute whose "default" or "builder" relies on another attribute, you have to remember to name them correctly or declare the field as lazy.

Note that is does mean if you need a "field" to be initialized at construction time, you have to take care to declare that it's not lazy:

    field created => ( isa => PositiveInt, lazy => 0, default => sub {time} );

In our opinion, this tiny little nit is a fair trade-off for this issue:

    package Person {
        use Moose;
        has name  => ( is => 'ro', required => 1 );
        has title => ( is => 'ro', required => 0 );
        has full_name => (
            is      => 'ro',
            default => sub {
                my $self  = shift;
                my $title = $self->title;
                my $name  = $self->name;
                return defined $title ? "$title $name" : $name;
            },
        );
    }
    my $person = Person->new( title => 'Doctor', name => 'Who' );
    say $person->title;
    say $person->full_name;

The code looks fine, but it doesn't work. In the above, "$person->full_name" is always undefined because attributes are processed in alphabetical order, so the "full_name" default code is run before "name" or "title" is set. Oops! Adding "lazy => 1" to the "full_name" attribute definition is required to make it work.

Here's the same code for "MooseX::Extended". It works correctly:

    package Person {
        use MooseX::Extended;
        param 'name';
        param 'title' => ( required => 0 );
        field full_name => (
            default => sub {
                my $self  = shift;
                my $title = $self->title;
                my $name  = $self->name;
                return defined $title ? "$title $name" : $name;
            },
        );
    }

Note that "param" is not lazy by default, but you can add "lazy => 1" if you need to.

NOTE: We were sorely tempted to change attribute field definition order from alphabetical to declaration order, as that would also solve the above issue (and might allow for deterministic destruction), but we decided to play it safe.

Attribute shortcuts

When using "field" or "param" (but not "has"), we have some attribute shortcuts:

    param name => (
        isa       => NonEmptyStr,
        writer    => 1,   # set_name
        reader    => 1,   # get_name
        predicate => 1,   # has_name
        clearer   => 1,   # clear_name
        builder   => 1,   # _build_name
    );
    sub _build_name ($self) {
        ...
    }

These should be self-explanatory, but see MooseX::Extended::Manual::Shortcuts for a full explanation.