phpman > perldoc > Moose::Manual::Roles(3pm)

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

VERSION
    version 2.2200

WHAT IS A ROLE?
    A role encapsulates some piece of behavior or state that can be shared between classes. It is
    something that classes *do*. 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, method modifiers, 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 and are based on the original
    concept of Traits <http://scg.unibe.ch/research/traits/> for the Smalltalk-80 dialect Squeak.

    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::Comparable_CodeReuse for an example.

    It's possible to compose existing roles into new roles. For example, we can have a
    "HandleWithCare" class which applies both the "Breakable" and "Package" roles to any class which
    consumes it:

      package HandleWithCare;

      use Moose::Role;

      with 'Breakable', 'Package';

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.

CONSUMING ROLES
    Roles are consumed using the "with" function.

    Most of the time, you should only use one "with", even if you are consuming multiple roles. If
    you consume roles using multiple "with" statements Moose cannot detect method conflicts between
    those roles.

    Roles can be consumed by classes or by other roles. When a class consumes a role which in turn
    consumes other roles, the class gets all of the roles applied at once.

  Required Methods Provided by Attributes
    As mentioned before, a role's required method may also be satisfied by an attribute accessor.
    However, the call to "has" which defines an attribute happens at runtime. This means that you
    must define the attribute *before* consuming the role, or else the role will not see the
    generated accessor. These attributes are Moose Attributes.

      package Breakable;

      use Moose::Role;

      requires 'stress';

      ########

      package Car;

      use Moose;

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

      with 'Breakable';

    In general, we recommend that you always consume roles *after* declaring all your attributes.

    It may also be the case that a class wants to consume two roles where one role has an attribute
    providing a required method for another. For example:

      package Breakable;

      use Moose::Role;

      requires 'stress';

      ########

      package Stressable;

      use Moose::Role;

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

      ########

      package Car;

      use Moose;

      # XXX - this will not work
      with 'Breakable', 'Stressable';

    However, this won't work. The problem is that the accessor methods created for the "stress"
    attribute won't be present in the class when the required method checks are done.

    There are two possible workarounds. The recommended one is to use "stub" subroutine(s) in the
    role providing the accessor(s):

      package Stressable;

      use Moose::Role;

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

    The "sub stress;" line is called a "forward" declaration in the Perl documentation. It creates
    what is called a "stub" subroutine, a declaration without a body. This is good enough to satisfy
    the required method checks done by Moose. The stub will not interfere with the creation of a
    real subroutine later.

    The other alternative is to use two separate calls to "with" in the consuming class:

      package Car;

      use Moose;

      # Not recommended
      with 'Stressable';
      with 'Breakable';

    Each "with" is run as it is seen. The first call will consume just the "Stressable" role, which
    will add the "stress" attribute to the "Car" package, which in turn will create an accessor
    method named "stress". Then when the "Breakable" role is consumed, the method it requires
    already exists.

    However, as mentioned earlier, multiple "with" declarations are not recommended, because method
    conflicts between the roles cannot be seen. In the example above, if both "Stressable" and
    "Breakable" contained methods of the same name, what would happen is that the version in
    "Stressable" would *silently* override the one in "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" role *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');

    When a role consumes another a role, the *consuming* role's methods silently win in any
    conflict, and the consumed role's methods are simply ignored.

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::Restartable_AdvancedComposition for an example.

OVERLOADING
    When a Moose role uses overloading, that overloading is composed into any classes that consume
    the role. This includes the setting of the "fallback" value for that role's overloading. Just as
    with methods and attributes, when a role consumes another role, that other role's overloading
    settings are applied to the role.

    Just as with methods, there can be conflicts with overloading implementations between multiple
    roles when they are all consumed by a class. If two roles both provide different overloading
    implementations for a given operator, that is a conflict. If two roles both implement
    overloading and have different "fallback" values, that is also considered a conflict. These
    conflicts are detected when multiple roles are being composed into a class together.

    When a role consumes another role, the consuming role's overloading fallback and operator
    implementations silently "win" the conflict.

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

ADDING A ROLE TO AN OBJECT INSTANCE
    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".

  Handling required attributes for roles.
    Application of some roles will require additional parameters being specified to satisfy them,
    for example:

        {
            package Car;
            use Moose;
        }
        {
            package Breakable;
            use Moose::Role;

            has 'breakable_parts' => ( is => 'ro', required => 1 );
        }

        my $car = Car->new;

        # next line dies with: Attribute (breakable_parts) is required
        apply_all_roles( $car, 'Breakable' );

    This will require passing the additional parameters at application time as follows:

        apply_all_roles( $car, 'Breakable' => {
                rebless_params => {
                    # Parameters to 'Breakable'
                    breakable_parts => [qw( tires wheels windscreen )],
                }
        });

    Obviously, this interface is better simplified as a method on "Car":

        sub make_breakable {
            my ( $self, %params ) = @_;
            apply_all_roles($self, 'Breakable', { rebless_params => \%params });
        }

        my $car = Car->new();
        $car->make_breakable( breakable_parts => [qw( tires wheels windscreen )] );

AUTHORS
    *   Stevan Little <stevan AT cpan.org>

    *   Dave Rolsky <autarch AT urth.org>

    *   Jesse Luehrs <doy AT cpan.org>

    *   Shawn M Moore <sartak AT cpan.org>

    *   יובל קוג'מן (Yuval Kogman) <nothingmuch AT woobling.org>

    *   Karen Etheridge <ether AT cpan.org>

    *   Florian Ragwitz <rafl AT debian.org>

    *   Hans Dieter Pearcey <hdp AT cpan.org>

    *   Chris Prather <chris AT prather.org>

    *   Matt S Trout <mstrout AT cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2006 by Infinity Interactive, Inc.

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