Moose::Manual::Roles man page on Kali

Man page or keyword search:  
man Server   9211 pages
apropos Keyword Search (all sections)
Output format
Kali logo
[printable version]

Moose::Manual::Roles(3User Contributed Perl DocumentaMoose::Manual::Roles(3pm)

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

VERSION
       version 2.2009

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.little@iinteractive.com>

       ·   Dave Rolsky <autarch@urth.org>

       ·   Jesse Luehrs <doy@tozt.net>

       ·   Shawn M Moore <code@sartak.org>

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

       ·   Karen Etheridge <ether@cpan.org>

       ·   Florian Ragwitz <rafl@debian.org>

       ·   Hans Dieter Pearcey <hdp@weftsoar.net>

       ·   Chris Prather <chris@prather.org>

       ·   Matt S Trout <mst@shadowcat.co.uk>

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.

perl v5.26.1			  2017-12-21	     Moose::Manual::Roles(3pm)
[top]

List of man pages available for Kali

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net