Writing a Moose class is mostly a matter of declaring attributes and methods. For example, let’s say you wanted to create a drawing program. You might start with a simple x and y coordinate system.

package Point;
use Moose;
has 'x' => ( is => 'ro', isa => 'Num', required => 1 );
has 'y' => ( is => 'ro', isa => 'Num', required => 1 );
1;

And that’s all you need! Here’s an example of how to use it:

my $point = Point->new( { x => 3.2, y => −7 } );
printf "x: %f y: %f\n" => $point->x, $point->y;

And that prints out:

x: 3.200000 y: −7.000000

Now maybe you want a line. A line is defined by its two endpoints.

package Line;
use Moose;
has 'point1' => ( is => 'ro', isa => 'Point', required => 1 );
has 'point2' => ( is => 'ro', isa => 'Point', required => 1 );
sub length {
    my $self = shift;
    return sqrt(
        ($self->point1->x - $self->point2->x)**2
        +
        ($self->point1->y - $self->point2->y)**2
    );
}
1;

And to use it:

my $line = Line->new({
   point1 => Point->new({ x => 1, y => −1 }),
   point2 => Point->new({ x => 4, y => −5 }),
});
print $line->length;

And that prints 5 as the length of that line.

my $line = Line->new(
   point1 => Point->new( x => 1, y => −1 ),
   point2 => Point->new( x => 4, y => −5 ),
);
print $line->length;

Amongst other things, you’ll note that we did not use strict or warnings. Why not? Because when you use Moose, it automatically uses strict and warnings for you.

You also didn’t even have to declare a new() constructor. Moose will provide that for you, allowing you to assign values to the declared attributes. Much easier, right? And if you tried to do this:

Point->new({ x => 'Foo', y => 3 });

You get a long stack trace starting with the message:

Attribute (x) does not pass the type constraint because:
  Validation failed for 'Num' with value Foo at ...

Needless to say, this is much easier than working with Perl’s standard bare bones OO. The CPAN page Moose::Manual::Unsweetened shows how much easier with a Moose vs Perl 5 OO example.

An attribute is a piece of data, such as quantity or color, associated with an object. They’re described in full in perldoc Moose::Manual::Attributes. The simplest attribute looks like this:

has 'name' => ( is => 'ro' );

The is => 'ro' means that the attribute is read-only. You can set it when you create the object but you cannot change it later. If you want it to be read-write, declare it with 'rw'.

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

Usually you want to specify what types the attribute can accept. For example, a name attribute should probably be a string:

has 'name' => ( is => 'ro', isa => 'Str' );

The isa => 'Str' says “this attribute isa string”. You can see the full list of built-in types with perldoc Moose::Util::TypeConstraints.

Any
 Item
     Bool
     Maybe[`a]
     Undef
     Defined
         Value
             Str
                 Num
                     Int
                 ClassName
                 RoleName
         Ref
             ScalarRef[`a]
             ArrayRef[`a]
             HashRef[`a]
             CodeRef
             RegexpRef
             GlobRef
             FileHandle
             Object

Most of those types should be self-explanatory, except for a few items we haven’t gone in-depth about.

Any means “anything” (duh). An Item is the same as Any. You could think of it as the difference between “something” and “anything”. In other words, it will not be of much practical difference in your work.

A Str is a string, a Num is any number, an Int is an integer, and so on. A Bool may be undef, the empty string, 0 or 1.

A Value is “anything which is defined and not a reference”. This can include something called a glob (instead of a GlobRef, as listed in the Ref types).

The [`a] is a type parameter. For any types, you can follow them with the type parameter, replacing the `a with a given type. For example:

has 'temperatures' => (
    is       => 'rw',
    isa      => 'ArrayRef[Num]',
    required => 1,
);

And that will allow you to create a temperatures attribute that, if present, must be an array reference containing only numbers. You could use that to create an average_temperature() method. We used required => 1 to ensure that the temperatures attribute must be supplied.

use List::Util 'sum';
sub average_temperature {
    my $self = shift;
    my $temperatures = $self->temperatures;
    my $num_temperatures = @$temperatures
      or return; # an empty temperatures arrayref
    return sum(@$temperatures) / $num_temperatures;
}

In fact, you can force the $temperatures array reference to have at least once value:

use Moose;
use Moose::Util::TypeConstraints; # for subtype, as, where
has 'temperatures' => (
    is       => 'rw',
    isa      => subtype( as 'ArrayRef[Num]', where { @$_ > 0 } ),
    required => 1,
);

Then, if you try to pass an empty array reference, Moose will throw an exception. That’s a bit obscure right now, but we’ll cover that when we get to type constraints later in this chapter (and inline subtypes like that are generally not recommended in case other modules need that subtype).

A Maybe[`a] value will allow you to have either undef or a specific value in an attribute. So Maybe[Int] will allow either undef or Int.

If you don’t like your setter and getter to be a single method, then separate them:

has 'name' => (
    is     => 'rw',
    isa    => 'Str',
    writer => 'set_name',
    reader => 'get_name',
);

Or you could use the MooseX::FollowPBP and all attributes will be named get_* and set_* for you (but you won’t get set_* unless you use is => 'rw').

use Moose;
use MooseX::FollowPBP; # get_name and set_name will now be created
has 'name' => (
    is  => 'rw',
    isa => 'Str',
);

You can also use isa to declare that the attribute is a specific type of object:

has 'birthdate' => (
    is  => 'ro',
    isa => 'DateTime',
);

And now if you pass something that is not a DateTime object to birthdate, Moose will throw an exception.

You can also assign defaults to attributes. With the following, if you don’t supply a mininum_age to the constructor, it will default to 18.

has 'mininum_age' => (
    is      => 'ro',
    isa     => 'Int',
    default => 18,
);

If your default is a reference, you must wrap it in sub {} to ensure a new reference is returned every time.

has 'mininum_age' => (
    is      => 'ro',
    isa     => 'DateTime::Duration',
    default => sub { DateTime::Duration->new( years => 18 ) },
);

Moose will throw an exception if you do not wrap that referenec in a subroutine reference because it is assumed that you do not want every class changing the same reference.

There’s a lot more power in attributes, so read Moose::Manual::Attributes to see what other nifty things you can do.

As explained, Moose provides a new() constructor for you. If you need to alter its behavior, do not override new(). Instead, you use BUILDARGS to modify arguments before new() is called, and BUILD is used after the constructor is called when you need further validation of the state of the object. We’ll cover BUILDARGS first. It has a bit of an unusual syntax.

my $point = Point->new( x => 3, y => 2 );

package Point;
use Moose;
has 'x' => ( is => 'ro', isa => 'Num', required => 1 );
has 'y' => ( is => 'ro', isa => 'Num', required => 1 );
around 'BUILDARGS' => sub {
    my $orig  = shift;
    my $class = shift;
    if ( @_ == 2 ) {
        my ( $x, $y ) = @_; # Point->new( x, y );
        return $class->$orig( x => $x, y => $y );
    }
    else {
        # Point->new(@list_or_hashref);
        return $class->$orig(@_);
    }
};   # Needs a trailing semicolon
1;

my $point = Point->new( 3, 2 );
# or, the same thing
my $point = Point->new( x => 3, y => 2 );

package Line;
use Moose;
use Carp 'croak';
has 'point1' => ( is => 'ro', isa => 'Point', required => 1 );
has 'point2' => ( is => 'ro', isa => 'Point', required => 1 );
sub BUILD {
    my $self = shift;
    if (   $self->point1->x == $self->point2->x
        && $self->point1->y == $self->point2->y )
    {
        croak("Line points must not be the same");
    }
}
sub length {
    my $self = shift;
    return sqrt(
        ($self->point1->x - $self->point2->x)**2
        +
        ($self->point1->y - $self->point2->y)**2
    );
}
1;

around 'BUILDARGS' => sub {
    my $orig  = shift;
    my $class = shift;
    if ( @_ == 2 ) {
        my ( $point1, $point2 ) = @_;
        return $class->$orig(
            point1 => $point1,
            point2 => $point2,
        );
    }
    else {
        return $class->$orig(@_);
    }
};   # Don't forget that trailing semicolon!

my $line = Line->new(
    Point->new( 1, −1 ),
    Point->new( 4, −5 ),
);

my $line = Line->new(
   point1 => Point->new( x => 1, y => −1 ),
   point2 => Point->new( x => 4, y => −5 ),
);

Inheritance in Moose is very easy. With Perl’s basic OO behavior, TV::Episode::Broadcast would inherit from TV::Episode via one of these techniques:

use base 'TV::Episode';
# or
use parent 'TV::Episode';
# or
use TV::Episode;
our @ISA = 'TV::Episode';

In Moose, every Moose object inherits from Moose::Object. So you can’t use those techniques directly or else you lose your inheritance from Moose::Object. Instead, you use the extends function:

package TV::Episode::Broadcast;
use Moose;
extends 'TV::Episode';

That does assumes your parent class is a Moose class. If you’re using Moose, that’s usually the case, but sometimes you’ll need to inherit from a class not built with Moose. See MooseX::NonMoose for that. If TV::Episode::Broadcast is written with Moose and TV::Episode is not a Moose class:

package TV::Episode::Broadcast;
use Moose;
use MooseX::NonMoose;
extends 'TV::Episode';

That will take care of lots of fiddly bits for you and everything should work fine.

When you use Moose, Moose exports a lot of helper functions into your class, such as:

You’ve seen a couple of them, such as has and around. Later, when someone is using your class, if they write:

$moose_object->can('around');

That will return a true value because subroutines and methods are treated the same way by Perl. You probably don’t want this behavior and there’s no need to leave all of those helper functions lying around. To deal with this, use namespace::autoclean (available on the CPAN).

package TV::Episode::Broadcast;
use Moose;
use namespace::autoclean;
# more code here
1;

That will automatically remove all of those helper functions for you.

Also, just before that trailing 1, you want to make your class immutable. A standard skeleton of a good Moose class looks like this:

package My::Class::Name;
use Moose;
use namespace::autoclean;

# your code here

__PACKAGE__->meta->make_immutable;

1;

The __PACKAGE__->meta->make_immutable doesn’t change the behavior, but it does a few internal things that make your code run a bit faster. The tradeoff is that you can’t use metaprogramming (that’s what the __PACKAGE__->meta is often used for) to change your class later, but if you know what that is, you know when to not make your class immutable.

When using Moose, the mro (Method Resolution Order) pragma is in effect. Not only does this use breadth-first C3 method resolution order that was described in Chapter 12, Object Oriented Perl, it also substitutes the SUPER::some_method call with next::method (and $object->can($some_method) becomes $object->next::can($somet_method)). If you do not use multiple inheritance — and its use is discouraged — you will likely see no difference in behavior aside from the syntax.

For example, you may recall the as_string() method from TV::Episode::Broadcast:

sub as_string {
    my $self    = shift;
    my $episode = $self->SUPER::as_string;
    my $date    = $self->broadcast_date;
    $episode .= sprintf "%-14s - %4d-%2d-%2d\n" => 'Broadcast date',
      $date->year,
      $date->month,
      $date->day;
    return $episode;
}

That overrides the TV::Episode::as_string() method. When you convert it to Moose, you make the following change:

# my $episode = $self->SUPER::as_string;
    my $episode = $self->next::method;

Note that there is no need to embed the method name in the call to the parent method. This can avoid annoying bugs if you try to rename a method.

As a lovely bit of syntactic sugar, you can also override Moose methods with the override function:

package TV::Episode::Broadcast;
use Moose;
extends 'TV::Episode';
# lots of code
override 'as_string' => sub {
    my $self    = shift;
    my $episode = super();
    my $date    = $self->broadcast_date;
    $episode .= sprintf "%-14s - %4d-%2d-%2d\n" => 'Broadcast date',
      $date->year,
      $date->month,
      $date->day;
    return $episode;
}

This has two very strong advantages. First, it’s excellent documentation to a maintenance programmer that this method overrides a parent method. Second, the call to super() passes the same arguments to the parent method (if any) that were passed to the child’s as_string() method, ensuring that you do not accidentally change the interface. Any arguments to super() are ignored and you cannot change @_.

Try it out Write a Person class.

In the first exercise of Chapter 12, Object Oriented Perl, we had you create a Person class. It had two attributes, a name and a birthdate, plus an age() method for returning the Person’s age in years. Writing this in Moose is much simpler.

1. Type in the following program and save it as lib/Person.pm.

   package Person;
   use Moose;
   use namespace::autoclean;
   use DateTime;
   has 'name' => (
       is       => 'ro',
       isa      => 'Str',
       required => 1,
   );
   has 'birthdate' => (
       is       => 'ro',
       isa      => 'DateTime',
       required => 1,
   );
   sub age {
       my $self = shift;
       my $duration = DateTime->now - $self->birthdate;
       return $duration->years;
   }
   __PACKAGE__->meta->make_immutable;
   1;

2. Write the following code and save it as person.pl.

   use lib 'lib';
   use strict;
   use warnings;
   use DateTime;
   use Person;
   my $person = Person->new({
       name      => 'Bertrand Russell',
       birthdate => DateTime->new(
           year  => 1872,
           month => 5,
           day   => 18,
       ),
   });
   print $person->name, ' is ', $person->age, ' years old';

   Note

   lib/Person.pm and person.pl available for download at Wrox.com.

3. Run the program with perl person.pl. You should see the following output:

   Bertrand Russell is 139 years old

How it works

There’s actually not much to say here. Moose is so simple to use that the above code should be pretty self-explanatory. However, if you did the exercises for Chapter 12, Object Oriented Perl, you probably wound up with something like this:

package Person;
use strict;
use warnings;
use DateTime;
use Carp 'croak';
sub new {
    my ( $class, $args ) = @_;
    my $self = bless {} => $class;
    $self->_initialize($args);
    return $self;
}
sub _initialize {
    my ( $self, $args ) = @_;
    my %args      = %$args;
    my $name      = delete $args{name};
    my $birthdate = delete $args{birthdate};
    # must have at least one non-whitespace character
    unless ( $name && $name =~ /\S/ ) {
        croak "Person name must be supplied";
    }
    # trap the error if it's not an object
    unless ( eval { $birthdate->isa('DateTime') } ) {
        croak "Person birthdate must be a DateTime object";
    }
    $self->{name}      = $name;
    $self->{birthdate} = $birthdate;
}
sub name      { $_[0]->{name} }
sub birthdate { $_[0]->{birthdate} }
sub age {
    my $self = shift;
    my $duration = DateTime->now - $self->birthdate;
    return $duration->years;
}
1;

That’s much longer and harder to read. Further, the more attributes you have, the shorter the Moose code tends to be in comparison to the standard OO code. That’s why you’ll often see many programmers creating their objects like this:

sub new {
    my ( $class, $arg_for ) = @_;
    return bless {
        name      => $arg_for->{name},
        birthdate => $arg_for->{birthdate},
    }, $class;
}

That works if and only if the person using your class never messes up and passes in the wrong data. With Moose, you have a simple, declarative interface and it’s much easier to use.

When you declare an attribute, you can also declare what type it is:

package Hand;
use Moose;
has 'fingers' => (
    is       => 'ro',
    isa      => 'Int',
    required => 1,
);

Now presumably, your Hand can’t have less than zero fingers. You could write a BUILD method and validate that your object has zero or more fingers, but you really don’t want to do that for every class where you need to assert a non-negative integer. So you can use Moose::Util::TypeConstraints to create a custom type.

package Hand;
use Moose;
use Moose::Util::TypeConstraints;
use namespace::autoclean;
subtype 'NonNegativeInteger'
    => as      'Int'
    => where   { $_ >= 0 }
    => message { "A Hand must have 0 or more fingers, not $_" };
has 'fingers' => (
    is       => 'ro',
    isa      => 'NonNegativeInteger',
    required => 1,
);
__PACKAGE__->meta->make_immutable;
1;

With that subtype, when you try to create an object with fewer than 0 fingers:

Hand->new( fingers => −3 );

You get a very useful error message (with a stack trace that I’ve omitted).

Attribute (fingers) does not pass the type constraint because:
  A Hand must have 0 or more fingers, not −3 at ...

To create your own subtypes, you use the Moose::Util::TypeConstraints module to add a few new helper functions to your code.

A subtype is a more specific version of an existing type. In this case, it’s a more specific version of an Int (integer). That’s what the as => 'Int' is for.

subtype 'NonNegativeInteger'
    => as      'Int'
    => where   { $_ >= 0 }
    => message { "You must provide an integrer > 0, not $_" };

The where { ... } is a code block that is executed with $_ set to the supplied value of the attribute. If it returns false, the type check fails and the optional message { ... } is displayed. If you don’t supply the message, the error can be rather confusing:

Attribute (fingers) does not pass the type constraint because:
  Validation failed for '__ANON__' with the value −3 ...

However, what you really want to do is create your own type library so that you can share these types across your various classes. It’s recommended that you do two things:

Let’s say that you work for a company named “My Company”. Customers must be 18 years old or older, so we’ll create a subtype to handle that. Here’s one way to create the type package:

package My::Company::Moose::Types;
use Moose::Util::TypeConstraints;
use DateTime;
subtype 'MyCompany:NonNegativeInteger'
    => as      'Int'
    => where   { $_ >= 0 }
    => message { "You must provide a non-negative integer, not $_" };
subtype 'MyCompany:18orOlder'
    => as      'DateTime'
    => where   { ( DateTime->now - $_ )->years >= 18 }
    => message {
        my $age = ( DateTime->now - $_ )->years;
        "DateTime supplied must be 18 years old or older, not $age years"
    };
1;

Now let’s create a little test program for it

{
    # remember that the package declaration is lexically scoped!
    package Person;
    use Moose;
    use DateTime;
    use My::Company::Moose::Types;
    has 'name' => (
        is       => 'ro',
        isa      => 'Str',
        required => 1,
    );
    has 'age' => (
        is       => 'ro',
        isa      => 'MyCompany:18orOlder',
        required => 1,
    );
}
my $youngster = Person->new(
    name => 'Youngster',
    age  => DateTime->new(
        year  => 2000,
        month => 1,
        day   => 1,
    ),
);

When you run that, it will generate an error similar to the following (at the time the author wrote this):

Attribute (age) does not pass the type constraint because:
   DateTime supplied must be 18 years old or older, not 12 years at ...

my $age = ( DateTime->now - $_ )->years;

my $duration = DateTime->now - $_;
my $age      = $duration->years;

One interesting feature of Moose is the concept of method modifiers. These are subroutines that you can attach to existing Moose subroutines to add to or alter behavior. You have already seen the around and override modifiers. There are also before, after, augment and inner modifiers.

before 'buy_item' => sub {
    my ( $self, $item ) = @_;
    if (   $item->is_age_restricted
        && $self->age < $self->locale->minimum_age_to_purchase($item) )
    {
        my $name      = $self->name;
        my $item_name = $item->name;
        croak "$name is not old enough to buy $item";
    }
};

after 'buy_item' => sub {
    my ( $self, $item ) = @_;
    if ( $item->is_age_restricted ) {
        $self->log_purchase($item);
    }
};

my @employees = $company->get_employees;
my $month     = $company->get_fiscal_month;
my $payroll   = 0;
foreach my $employee (@employees) {
    $payroll += $employee->salary($month);
}

package Employee;
use Moose;
# lots of code omitted
sub salary {
    my ( $self, $fiscal_month ) = @_;
    unless ( $fiscal_month->isa('Fiscal::Month') ) {
        croak "Argument to salary() must be a Fiscal::Month object";
    }
    my $salary = inner(); # this calls the child version of salary()
    if ( ref $salary or $salary < 0 ) {
        croak "Salary must be a non-negative number: $salary";
    }
    return $salary;
}

package Employee::Manager.
use Moose;
extends 'Employee';
# lots of code omitted
augment 'salary' => sub {
    my $self = shift;
    # lots of code
    return $salary;
};

sub salary {
    my ( $self, $fiscal_month ) = @_;
    unless ( $fiscal_month->isa('Fiscal::Month') ) {
        croak "Argument to salary() must be a Fiscal::Month object";
    }
    my $salary = $self->_salary($fiscal_month); # inner()
    if ( ref $salary or $salary < 0 ) {
        croak "Salary must be a non-negative number: $salary";
    }
    return $salary;
}

A role provides additional methods for a class, along with methods it requires to implement those methods. There are several implementations in Perl, but the most common is Moose::Role.

Generally speaking, this set of methods should be something that the class should provide, but is not inherent to the class’s expert knowledge. For example, with a Person class, they may have a name, a birthdate and be able to “talk”. But should a person intrinsically know how to serialize themselves with an as_json() method? Probably not, but you’ll notice that the TV::Episode classes and subclasses all had the ability to serialize themselves with an as_string() method. In fact, many completely unrelated classes might have an as_json() method, so it’s a perfect candidate to put into a role.

For the examples that require the JSON module, you will need to install it from the CPAN.

package Role::Serializable::JSON;
use Moose::Role;
use JSON 'encode_json';
# you can list multiple methods here
requires qw(
  serializable_attributes
);
sub as_json {
    my $self = shift;
    my %object = map { $_ => $self->$_ } $self->serializable_attributes;
    return encode_json( \%object );
}

'Role::Serializable::JSON' requires the method
'serializable_attributes' to be implemented by
'Some::Class::Name'

package Soldier;
use Moose;
use namespace::autoclean;
with "Role::Serializable::JSON";
has 'name' => ( is => 'ro', isa => 'Str', required => 1 );
has 'rank' => ( is => 'ro', isa => 'Str', required => 1 );
sub serializable_attributes {
    return qw( name rank );
}
__PACKAGE__->meta->make_immutable;
1;

my $soldier = Soldier->new(
    {
        name => "Schultz",
        rank => "Sergeant",
    }
);
print $soldier->as_json;

{"name":"Schultz","rank":"Sergeant"}

sub as_json {
    my $self       = shift;
    my @attributes = map { $_->name }
      $self->meta->get_all_attributes;
    my %object     = map { $_ => $self->$_ } @attributes;
    return encode_json( \%object );
}

print $soldier->does('Role::Serializable::JSON') ? 'Yes' : 'No';

package PracticalJoke;
use strict;
use warnings;
use base qw(Bomb Spouse);
sub new {
    ...
}
sub explode {
    my $self = shift;
    $self->Spouse::explode();
}

{
    package Bomb;
    use Moose::Role;
    sub fuse    { print "Bomb explode\n" }
    sub explode { print "Bomb fuse\n" }
}
{
    package Spouse;
    use Moose::Role;
    sub fuse    { print "Spouse explode\n" }
    sub explode { print "Spouse fuse\n" }
}
{
    package PracticalJoke;
    use Moose;
    with qw(Bomb Spouse);
}
my $joke = PracticalJoke->new();
$joke->explode();
$joke->fuse();

Due to method name conflicts in roles 'Bomb' and 'Spouse',
the methods 'explode' and 'fuse' must be implemented or
excluded by 'PracticalJoke' at ...

package PracticalJoke;
use Moose;
with 'Bomb'   => { excludes => 'explode' },
     'Spouse' => { excludes => 'fuse' };

Spouse explode
Bomb fuse

When learning Moose, you’ll sometimes find that you want to do things a bit differently. We’ve alluded to metaprogramming, but you’ll be happy to know that for many of the most common tasks, there are already modules on the CPAN that handle them for you. By convention, modules that are “unofficial” extensions to other modules have an X in the name, so the unofficial Moose extension modules are in the MooseX:: namespace. The ones that the core Moose team likes are described in Moose::Manual::MooseX. We’ll cover a few of the MooseX:: modules here. These modules are not included with Moose and must be installed separately.

if ( my $remaining = join ', ', keys %arg_for ) {
    croak("Unknown keys to $class\::new: $remaining");
}

package Person;
use Moose;
use MooseX::StrictConstructor;
has 'name'      => ( is => 'ro', isa => 'Str',      required => 1 );
has 'birthdate' => ( is => 'ro', isa => 'DateTime', required => 0 );

Person->new(name=>'foo', birtdhate => 1);

Found unknown attribute(s) passed to the constructor: birtdhate

sub reciprocal {
    my $number = shift;
    return 1/$number;
}

float reciprocal(int $number) {
    return 1/$number;
}

package Foo;
   use Moose;
   use MooseX::Method::Signatures;
   method morning (Str $name) {
       $self->say("Good morning ${name}!");
   }
   method hello (Str :$who, Int :$age where { $_ > 0 }) {
       $self->say("Hello ${who}, I am ${age} years old!");
   }
   method greet (Str $name, Bool :$excited = 0) {
       if ($excited) {
           $self->say("GREETINGS ${name}!");
       }
       else {
           $self->say("Hi ${name}!");
       }
   }
   $foo->morning('Resi');                    # This works.
   $foo->hello(who => 'world', age => 42);     # This too.
   $foo->greet('Resi', excited => 1);            # Yup.
   $foo->hello(who => 'world', age => 'fortytwo'); # Nope.
   $foo->hello(who => 'world', age => −23);      # Too bad.
   $foo->morning;                              # Won't work.
   $foo->greet;                              # Fail!

{
    package Soldier;
    use Moose;
    use MooseX::SemiAffordanceAccessor;
    has name => ( is => 'ro', isa => 'Str', required => 1 );
    has rank => ( is => 'rw', isa => 'Str', required => 1 );
}
my $soldier = Soldier->new(
    name => "Billy",
    rank => "Private",
);
$soldier->set_rank("Corporal");
$soldier->set_name("Barbara");

Can't locate object method "set_name" via package "Soldier" at ...

Let’s use Moose to rewrite our TV::Episode class from Chapter 12, Object Oriented Perl. It looked like this:

package TV::Episode;
use strict;
use warnings;
use Carp 'croak';
use Scalar::Util 'looks_like_number';
our $VERSION = '0.01';
my %IS_ALLOWED_GENRE = map { $_ => 1 } qw(
  comedy
  drama
  documentary
  awesome
);
sub new {
    my ( $class, $arg_for ) = @_;
    my $self = bless {} => $class;
    $self->_initialize($arg_for);
    return $self;
}
sub _initialize {
    my ( $self, %arg_for ) = @_;
    my %arg_for = %$arg_for;
    foreach my $property (qw/series director title/) {
        my $value = delete $arg_for{$property};
        # at least one non-space character
        unless ( defined $value && $value =~ /\S/ ) {
            croak("property '$property' must have at a value");
        }
        $self->{$property} = $value;
    }
    my $genre = delete $arg_for{genre};
    unless ( exists $IS_ALLOWED_GENRE{$genre} ) {
        croak("Genre 'genre' is not an allowed genre");
    }
    $self->{genre} = $genre;
    foreach my $property (qw/season episode_number/) {
        my $value = delete $arg_for{$property};
        unless ( looks_like_number($value) && $value > 0 ) {
            croak("$value must have a positive value");
        }
        $self->{$property} = $value;
    }
    if ( my $extra = join ', ' => keys %arg_for ) {
        croak("Unknown keys to new(): $extra");
    }
}
sub series         { shift->{series} }
sub title          { shift->{title} }
sub director       { shift->{director} }
sub genre          { shift->{genre} }
sub season         { shift->{season} }
sub episode_number { shift->{episode_number} }
sub as_string {
    my $self       = shift;
    my @properties = qw(
      series
      title
      director
      genre
      season
      episode_number
    );
    my $as_string = '';
    foreach my $property (@properties) {
        $as_string .= sprintf "%-14s - %s\n", ucfirst($property),
          $self->$property;
    }
    return $as_string;
}
1;

There are many strategies we could reuse to rewrite that. For this example, we’re going to embed Moose::Util::TypeConstraints directly into our module and use an anonymous enum type for the genre and create an IntPositive type for the episode_number and season.

package TV::Episode;
use Moose;
use MooseX::StrictConstructor;
use Moose::Util::TypeConstraints;
use namespace::autoclean;
use Carp 'croak';
our $VERSION = '0.01';
subtype 'IntPositive',
         as    'Int',
         where { $_ > 0 };
has 'series'
  => ( is => 'ro', isa => 'Str',         required => 1 );
has 'director'
  => ( is => 'ro', isa => 'Str',         required => 1 );
has 'title'
  => ( is => 'ro', isa => 'Str',         required => 1 );
has 'season'
  => ( is => 'ro', isa => 'IntPositive', required => 1 );
has 'episode_number'
  => ( is => 'ro', isa => 'IntPositive', required => 1 );
has 'genre'          => (
    is       => 'ro',
    isa      => enum(qw(comedy drama documentary awesome)),
    required => 1
);
sub as_string {
    my $self = shift;
    my @attributes =
      map { $_->name }
      $self->meta->get_all_attributes;
    my $as_string = '';
    foreach my $attribute (@attributes) {
        $as_string .= sprintf "%-14s - %s\n",
          ucfirst($attribute),
          $self->$attribute;
    }
    return $as_string;
}
__PACKAGE__->meta->make_immutable;
1;

As you can see, this version is much shorter than the original version. In fact, if you pushed the as_string method into a role, you could reduce the class to this:

package TV::Episode;
use Moose;
use MooseX::StrictConstructor;
use My::CustomTypes;      # for Genre and IntPositive
with 'Does::ToString';    # for the as_string method
use namespace::autoclean;
our $VERSION = '0.01';
has 'series'   => ( is => 'ro', isa => 'Str', required => 1 );
has 'director' => ( is => 'ro', isa => 'Str', required => 1 );
has 'title'    => ( is => 'ro', isa => 'Str', required => 1 );
has 'genre'    => ( is => 'ro', isa => 'Genre', required => 1 );
has 'season'
  => ( is => 'ro', isa => 'IntPositive', required => 1 );
has 'episode_number'
  => ( is => 'ro', isa => 'IntPositive', required => 1 );
__PACKAGE__->meta->make_immutable;
1;

As you can see, by carefully planning out your code, you can make new classes very simple and easy to build and maintain. This is why Moose has become the OO system of choice for many Perl programmers.

Considering that the original version was almost twice as long as our revised version, and almost four times longer than our “ideal” version, which would you rather write?

Try it out Rewrite Television::Episode::Broadcast with Moose.

You might recall the old version of TV::Episode::Broadcast.

package TV::Episode::Broadcast;
use strict;
use warnings;
use Try::Tiny;
use Carp 'croak';
use base 'TV::Episode';
sub _initialize {
    my ( $self, $arg_for ) = @_;
    my %arg_for = %$arg_for;
    my $broadcast_date = delete $arg_for{broadcast_date};
    try {
        $broadcast_date->isa('DateTime') or die;
    }
    catch {
        croak("broadcast_date requires a DateTime object");
    };
    $self->{broadcast_date} = $broadcast_date;
    $self->SUPER::_initialize( \%arg_for );
}
sub broadcast_date { shift->{broadcast_date} }
sub as_string {
    my $self    = shift;
    my $episode = $self->SUPER::as_string;
    my $date    = $self->broadcast_date;
    $episode .= sprintf "%-14s - %4d-%2d-%2d\n"
      => 'Broadcast date',
         $date->year,
         $date->month,
         $date->day;
    return $episode;
}
1;

With Moose, that is tremendously simplified. We’ll go ahead and extend our Moosified version to TV::Episode.

1. Type in the following class and save it as lib/TV/Episode/Broadcast.pm.

   package TV::Episode::Broadcast;
   use Moose;
   use namespace::autoclean;
   extends 'TV::Episode';
   has 'broadcast_date' => (
     is       => 'ro',
     isa      => 'DateTime',
     required => 1,
   );
   __PACKAGE__->meta->make_immutable;
   1;

   Note

   TV/Episode/Broadcast.pm available for download at Wrox.com.

2. Type in the following program and save it as episode.pl.

   use strict;
   use warnings;
   use lib 'lib';
   use DateTime;
   use TV::Episode;
   use TV::Episode::Broadcast;
   my $episode = TV::Episode->new(
       {
           series         => 'Firefly',
           director       => 'Marita Grabiak',
           title          => 'Jaynestown',
           genre          => 'awesome',
           season         => 1,
           episode_number => 7,
       }
   );
   print $episode->as_string;
   print "----\n";
   my $broadcast = TV::Episode::Broadcast->new(
       {
           series         => 'Firefly',
           director       => 'Allan Kroeker',
           title          => 'Ariel',
           genre          => 'awesome',
           season         => 1,
           episode_number => 9,
           broadcast_date => DateTime->new(
               year  => 2002,
               month => 11,
               day   => 15,
           ),
       }
   );
   print $broadcast->as_string;

3. Run the program with perl episode.pl. You should see output similar to the following:

   Director       - Marita Grabiak
   Episode_number - 7
   Genre          - awesome
   Season         - 1
   Series         - Firefly
   Title          - Jaynestown
   ----
   Broadcast_date - 2002-11-15T00:00:00
   Director       - Allan Kroeker
   Episode_number - 9
   Genre          - awesome
   Season         - 1
   Series         - Firefly
   Title          - Ariel

How it works

This one is pretty awesome. We’ve gone from a third-one line version of TV::Episode::Broadcast to a seven line version.

In this case, the magic was adding the broadcast_date attribute and taking advantage of the following line in our TV::Episode::as_string() method:

my @attributes = sort map { $_->name }
  $self->meta->get_all_attributes;

When you subclass and call an inherited method, the metaclass returned by $self->meta is for the subclass, not the parent class. Since the subclass inherits the superclass’s behavior, all of its attributes are reported in the get_all_attributes() method class. This power is part of what allows us to do things with Moose much more easily than with Perl’s built-in OO.

And for those readers who object that they now lack control over how the items in as_string() are ordered: you’re quite right. However, there are several strategies to get around this, sub as providing an _ordered_attributes() method and overriding it in a subclass, or delving into more metaprogramming to allow you to attach additional information to attributes to better control their sort order. We’ll leave that as an exercise for the reader.

A shell of all Moose classes should look like this:

package Person;
use Moose;
use namespace::autoclean;
# extends, roles, attributes, etc.
# methods
__PACKAGE__->meta->make_immutable;
1;

By using namespace::autoclean, you guarantee that imported functions are not accidentally treated as methods. By making your class immutable, you gain a significant performance improvement in your code.

BUILDARGS allows you to alter the argument list before calling new() and BUILD allows you to do validation on your object that may be difficult in the constructor.

If you inherit from a class providing a BUILDARGS method, use super() to call that parent method. You’ve seen this from the override() function we described earlier.

This is often bad:

has 'budget' => ( is => 'ro', isa => 'Num' );

If you are not going to require attribute to be provided, your code may blow up when you try to use the attribute value. A better strategy is to provide a default and document it.

has 'budget' => ( is => 'ro', isa => 'Num', default => 100 );

Remember that if the default is a reference, you must wrap it in an anonymous subroutine:

has 'birthday' => (
    is      => 'ro',
    isa     => 'DateTime',
    default => sub { DateTime->now } );

Generally you want your attributes to be read-only. This makes it much harder for someone to change the state of the object to something invalid later on. Sometimes, though, your class needs to change the attribute value internally, so make a private “writer”:

has 'budget' => (
    is     => 'ro',
    isa    => 'Num',
    writer => '_set_budget',
);

subtype 'My::Company::NonNegativeInteger'
    => as      'Int'
    => where   { $_ >= 0 }
    => message { "A Hand must have 0 or more fingers, not $_" };

By doing this, it’s easy to find the types and manage them. Also, by adding a custom My::Company:: prefix to the subtype name, you are less likely to conflict with another subtype of the same name.

Use roles instead.

If you feel that you must use multiple inheritance to solve a problem, pull out the code you wish to share and put it in a role. The extra class (or classes!) you want to inherit from should now use that role and the new class you are writing can use that role, too. This should make your code much easier to maintain and avoids bugs in inheritance order and accidentally overriding methods you did not mean to override.

It’s perfectly legal to do this:

package Foo;
use Moose;
with 'RoleA';
with 'RoleB';

But what happens if both RoleA and RoleB provide a discharge() method? Well, RoleA will provide the discharge() method and RoleB’s discharge() method be silently ignored. This is because when you consume a role, Moose assumes that your class’s methods take precedence over role methods. Thus, when RoleA’s discharge() method is added to your class, by the time you consume RoleB, Moose sees that your Foo class already has a discharge() method and ignores the one from RoleB.

Instead, be explicit about what you want:

package Foo;
use Moose;
with 'RoleA' => { excludes => "discharge" },
     'RoleB';

Even if you really did want to exclude the RoleB discharge method:

package Foo;
use Moose;
with 'RoleA',
     'RoleB' => { excludes => "discharge" };

In this case, it might be functionally equivalent to consuming those roles separately; it’s cleaner and self-documenting. To really understand this, consider our PracticalJoke class from earlier:

package PracticalJoke;
use Moose;
with 'Bomb'   => { excludes => 'explode' },
     'Spouse' => { excludes => 'fuse' };

If you had written:

package PracticalJoke;
use Moose;
with 'Bomb';
with 'Spouse';

You may not have spotted the method conflicts and thus had your code fail in ways you did not expect.

Consume all of your roles at once and be explicit about what you are doing.