Stevan Little > Moose-1.00 > Moose::Manual::Roles

Download:
Moose-1.00.tar.gz

Annotate this POD

CPAN RT

New  8
Open  41
Stalled  7
View/Report Bugs
Source   Latest Release: Moose-2.1302-TRIAL

NAME ^

Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes

WHAT IS A ROLE? ^

A role is something that classes do. Usually, a role encapsulates some piece of behavior or state that can be shared between classes. It is important to understand that roles are not classes. You cannot inherit from a role, and a role cannot be instantiated. We sometimes say that roles are consumed, either by classes or other roles.

Instead, a role is composed into a class. In practical terms, this means that all of the methods and attributes defined in a role are added directly to (we sometimes say "flattened into") the class that consumes the role. These attributes and methods then appear as if they were defined in the class itself. A subclass of the consuming class will inherit all of these methods and attributes.

Moose roles are similar to mixins or interfaces in other languages.

Besides defining their own methods and attributes, roles can also require that the consuming class define certain methods of its own. You could have a role that consisted only of a list of required methods, in which case the role would be very much like a Java interface.

Note that attribute accessors also count as methods for the purposes of satisfying the requirements of a role.

A SIMPLE ROLE ^

Creating a role looks a lot like creating a Moose class:

  package Breakable;

  use Moose::Role;

  has 'is_broken' => (
      is  => 'rw',
      isa => 'Bool',
  );

  sub break {
      my $self = shift;

      print "I broke\n";

      $self->is_broken(1);
  }

Except for our use of Moose::Role, this looks just like a class definition with Moose. However, this is not a class, and it cannot be instantiated.

Instead, its attributes and methods will be composed into classes which use the role:

  package Car;

  use Moose;

  with 'Breakable';

  has 'engine' => (
      is  => 'ro',
      isa => 'Engine',
  );

The with function composes roles into a class. Once that is done, the Car class has an is_broken attribute and a break method. The Car class also does('Breakable'):

  my $car = Car->new( engine => Engine->new );

  print $car->is_broken ? 'Busted' : 'Still working';
  $car->break;
  print $car->is_broken ? 'Busted' : 'Still working';

  $car->does('Breakable'); # true

This prints:

  Still working
  I broke
  Busted

We could use this same role in a Bone class:

  package Bone;

  use Moose;

  with 'Breakable';

  has 'marrow' => (
      is  => 'ro',
      isa => 'Marrow',
  );

See also Moose::Cookbook::Roles::Recipe1 for an example.

REQUIRED METHODS ^

As mentioned previously, a role can require that consuming classes provide one or more methods. Using our Breakable example, let's make it require that consuming classes implement their own break methods:

  package Breakable;

  use Moose::Role;

  requires 'break';

  has 'is_broken' => (
      is  => 'rw',
      isa => 'Bool',
  );

  after 'break' => sub {
      my $self = shift;

      $self->is_broken(1);
  };

If we try to consume this role in a class that does not have a break method, we will get an exception.

You can see that we added a method modifier on break. We want classes that consume this role to implement their own logic for breaking, but we make sure that the is_broken attribute is always set to true when break is called.

  package Car

  use Moose;

  with 'Breakable';

  has 'engine' => (
      is  => 'ro',
      isa => 'Engine',
  );

  sub break {
      my $self = shift;

      if ( $self->is_moving ) {
          $self->stop;
      }
  }

Roles Versus Abstract Base Classes

If you are familiar with the concept of abstract base classes in other languages, you may be tempted to use roles in the same way.

You can define an "interface-only" role, one that contains just a list of required methods.

However, any class which consumes this role must implement all of the required methods, either directly or through inheritance from a parent. You cannot delay the method requirement check so that they can be implemented by future subclasses.

Because the role defines the required methods directly, adding a base class to the mix would not achieve anything. We recommend that you simply consume the interface role in each class which implements that interface.

Required Attributes

As mentioned before, a role requirement may also be satisfied by an attribute accessor. But any has functions, which will generate accessors that satisfy the role requirement, must be placed before the with function that composes the role.

  package Breakable;

  use Moose::Role;

  requires 'stress';

  package Car;

  use Moose;

  has 'stress' => ( 
      is  => 'rw',
      isa => 'Int',
  );

  with 'Breakable';

USING METHOD MODIFIERS ^

Method modifiers and roles are a very powerful combination. Often, a role will combine method modifiers and required methods. We already saw one example with our Breakable example.

Method modifiers increase the complexity of roles, because they make the role application order relevant. If a class uses multiple roles, each of which modify the same method, those modifiers will be applied in the same order as the roles are used:

  package MovieCar;

  use Moose;

  extends 'Car';

  with 'Breakable', 'ExplodesOnBreakage';

Assuming that the new ExplodesOnBreakage method also has an after modifier on break, the after modifiers will run one after the other. The modifier from Breakable will run first, then the one from ExplodesOnBreakage.

METHOD CONFLICTS ^

If a class composes multiple roles, and those roles have methods of the same name, we will have a conflict. In that case, the composing class is required to provide its own method of the same name.

  package Breakdancer;

  use Moose::Role

  sub break {

  }

If we compose both Breakable and Breakdancer in a class, we must provide our own break method:

  package FragileDancer;

  use Moose;

  with 'Breakable', 'Breakdancer';

  sub break { ... }

A role can be a collection of other roles:

  package Break::Bundle;

  use Moose::Role;

  with ('Breakable', 'Breakdancer');

METHOD EXCLUSION AND ALIASING ^

If we want our FragileDancer class to be able to call the methods from both its roles, we can alias the methods:

  package FragileDancer;

  use Moose;

  with 'Breakable'   => { -alias => { break => 'break_bone' } },
       'Breakdancer' => { -alias => { break => 'break_dance' } };

However, aliasing a method simply makes a copy of the method with the new name. We also need to exclude the original name:

  with 'Breakable' => {
      -alias    => { break => 'break_bone' },
      -excludes => 'break',
      },
      'Breakdancer' => {
      -alias    => { break => 'break_dance' },
      -excludes => 'break',
      };

The excludes parameter prevents the break method from being composed into the FragileDancer class, so we don't have a conflict. This means that FragileDancer does not need to implement its own break method.

This is useful, but it's worth noting that this breaks the contract implicit in consuming a role. Our FragileDancer class does both the Breakable and BreakDancer, but does not provide a break method. If some API expects an object that does one of those roles, it probably expects it to implement that method.

In some use cases we might alias and exclude methods from roles, but then provide a method of the same name in the class itself.

Also see Moose::Cookbook::Roles::Recipe2 for an example.

ROLE EXCLUSION ^

A role can say that it cannot be combined with some other role. This should be used with great caution, since it limits the re-usability of the role.

  package Breakable;

  use Moose::Role;

  excludes 'BreakDancer';

APPLYING ROLES ^

A role can be applied to a class or an instance in other ways besides using the 'with' syntax.

To apply a role to a class, use Moose::Util and the 'apply_all_roles' function. If you apply the role to a class, it will affect all objects of that class. You can't apply a role to a class if it has been made immutable. In some circumstances it may make sense to make the class mutable, apply the role, then make the class immutable again.

   use Moose::Util;
   ...
   my $class = 'MyApp::Test';
   $class->meta->make_mutable;
   Moose::Util::apply_all_roles($class->meta, ('MyApp::SomeRole'));
   $class->meta->make_immutable;

Do not apply roles to classes that have immutable subclasses, since that will invalidate the metadata of the subclasses.

If you want the role to be applied only to a particular instance and not to the class, you can apply the roles to the instance instead of the class's meta:

   Moose::Util::apply_all_roles($instance, ('MyApp::SomeRole'));

Or you can use the role's meta object:

   MyApp::SomeRole->meta->apply($instance);

The mutable/immutable state is not relevant to roles applied to instances. See Moose::Role and Moose::Util for more details and Moose::Cookbook::Roles::Recipe3 for a more developed example.

ADDING A ROLE TO AN OBJECT INSTANCE ^

Sometimes you may want to add a role to an object instance, rather than to a class. For example, you may want to add debug tracing to one instance of an object while debugging a particular bug. Another use case might be to dynamically change objects based on a user's configuration, as a plugin system.

The best way to do this is to use the apply_all_roles function from Moose::Util:

  use Moose::Util qw( apply_all_roles );

  my $car = Car->new;
  apply_all_roles( $car, 'Breakable' );

This function can apply more than one role at a time, and will do so using the normal Moose role combination system. We recommend using this function to apply roles to an object. This is what Moose uses internally when you call with.

AUTHOR ^

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE ^

Copyright 2009 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: