NAME

MooseX::Extended::Manual::Construction - Objected construction for MooseX::Extended

VERSION

version 0.35

OBJECT CONSTRUCTION

The normal "new", "BUILD", and "BUILDARGS" functions work as expected. However, we apply MooseX::StrictConstructor to avoid this problem:

    my $soldier = Soldier->new(
        name   => $name,
        rank   => $rank,
        seriel => $serial, # should be serial
    );

By default, misspelled arguments to the Moose constructor are silently discarded, leading to hard-to-diagnose bugs. With MooseX::Extended, they're a fatal error.

If you need to pass arbitrary "sideband" data, explicitly declare it as such:

    param sideband => ( isa => HashRef, default => sub { {} } );

Naturally, because we bundle MooseX::Extended::Types, you can do much finer-grained data validation on that, if needed.

FUNCTIONS

The following two functions are exported into your namespace.

"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 );

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' );

"field"

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

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

The above "field" definition is equivalent to:

    has created => (
        is       => 'ro',
        isa      => PositiveInt,
        init_arg => undef,        # not allowed in the constructor
        default  => sub { time },
        lazy     => 1,
    );

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

    field some_data => ( is => 'rw', isa => NonEmptyStr );

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

WARNING: if you pass "field" an "init_arg" with a defined value, The code will "croak" unless that value begins with an underscore:

    field created => (
        isa      => PositiveInt,
        default  => sub {time},
        lazy     => 0,             # because it must fire at object creation
        init_arg => '_created',    # but let them override this in tests
    );

The above allows you to pass "_created => 42" in the constructor. This is useful when you wish to easily control this value for tests.

Otherwise, a "field" is just for internal instance data the class uses. It's not to be passed to the constructor. If you want that, just use "param".

Lazy Fields

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. Note that is does mean if you need a "field" to be initialized at construction time, you have to take care:

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

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

AUTHOR

Curtis "Ovid" Poe <curtis.poe@gmail.com>

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)