lib/Moose/Manual/Roles.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes
   6
   7 =head1 WHAT IS A ROLE?
   8
   9 A role is something that classes do. Usually, a role encapsulates some
  10 piece of behavior or state that can be shared between classes. It is
  11 important to understand that I<roles are not classes>. You cannot
  12 inherit from a role, and a role cannot be instantiated. We sometimes
  13 say that roles are I<consumed>, either by classes or other roles.
  14
  15 Instead, a role is I<composed> into a class. In practical terms, this
  16 means that all of the methods and attributes defined in a role are
  17 added directly to (we sometimes say "flattened into") the class that
  18 consumes the role. These attributes and methods then appear as if they
  19 were defined in the class itself. A subclass of the consuming class
  20 will inherit all of these methods and attributes.
  21
  22 Moose roles are similar to mixins or interfaces in other languages.
  23
  24 Besides defining their own methods and attributes, roles can also
  25 require that the consuming class define certain methods of its
  26 own. You could have a role that consisted only of a list of required
  27 methods, in which case the role would be very much like a Java
  28 interface.
  29
  30 Note that attribute accessors also count as methods for the
  31 purposes of satisfying the requirements of a role.
  32
  33 =head1 A SIMPLE ROLE
  34
  35 Creating a role looks a lot like creating a Moose class:
  36
  37   package Breakable;
  38
  39   use Moose::Role;
  40
  41   has 'is_broken' => (
  42       is  => 'rw',
  43       isa => 'Bool',
  44   );
  45
  46   sub break {
  47       my $self = shift;
  48
  49       print "I broke\n";
  50
  51       $self->is_broken(1);
  52   }
  53
  54 Except for our use of L<Moose::Role>, this looks just like a class
  55 definition with Moose. However, this is not a class, and it cannot be
  56 instantiated.
  57
  58 Instead, its attributes and methods will be composed into classes
  59 which use the role:
  60
  61   package Car;
  62
  63   use Moose;
  64
  65   with 'Breakable';
  66
  67   has 'engine' => (
  68       is  => 'ro',
  69       isa => 'Engine',
  70   );
  71
  72 The C<with> function composes roles into a class. Once that is done,
  73 the C<Car> class has an C<is_broken> attribute and a C<break>
  74 method. The C<Car> class also C<does('Breakable')>:
  75
  76   my $car = Car->new( engine => Engine->new );
  77
  78   print $car->is_broken ? 'Still working' : 'Busted';
  79   $car->break;
  80   print $car->is_broken ? 'Still working' : 'Busted';
  81
  82   $car->does('Breakable'); # true
  83
  84 This prints:
  85
  86   Still working
  87   I broke
  88   Busted
  89
  90 We could use this same role in a C<Bone> class:
  91
  92   package Bone;
  93
  94   use Moose;
  95
  96   with 'Breakable';
  97
  98   has 'marrow' => (
  99       is  => 'ro',
 100       isa => 'Marrow',
 101   );
 102
 103 =head1 REQUIRED METHODS
 104
 105 As mentioned previously, a role can require that consuming classes
 106 provide one or more methods. Using our C<Breakable> example, let's
 107 make it require that consuming classes implement their own C<break>
 108 methods:
 109
 110   package Breakable;
 111
 112   use Moose::Role;
 113
 114   requires 'break';
 115
 116   has 'is_broken' => (
 117       is  => 'rw',
 118       isa => 'Bool',
 119   );
 120
 121   after 'break' => sub {
 122       my $self = shift;
 123
 124       $self->is_broken(1);
 125   };
 126
 127 If we try to consume this role in a class that does not have a
 128 C<break> method, we will get an exception.
 129
 130 You can see that we added a method modifier on C<break>. We want
 131 classes that consume this role to implement their own logic for
 132 breaking, but we make sure that the C<is_broken> attribute is always
 133 set to true when C<break> is called.
 134
 135   package Car
 136
 137   use Moose;
 138
 139   with 'Breakable';
 140
 141   has 'engine' => (
 142       is  => 'ro',
 143       isa => 'Engine',
 144   );
 145
 146   sub break {
 147       my $self = shift;
 148
 149       if ( $self->is_moving ) {
 150           $self->stop;
 151       }
 152   }
 153
 154 =head2 Roles Versus Abstract Base Classes
 155
 156 If you are familiar with the concept of abstract base classes in other
 157 languages, you may be tempted to use roles in the same way.
 158
 159 You I<can> define an "interface-only" role, one that contains I<just>
 160 a list of required methods.
 161
 162 However, any class which consumes this role must implement all of the
 163 required methods, either directly or through inheritance from a
 164 parent. You cannot delay the method requirement check so that they can
 165 be implemented by future subclasses.
 166
 167 Because the role defines the required methods directly, adding a base
 168 class to the mix would not achieve anything. We recommend that you
 169 simply consume the interface role in each class which implements that
 170 interface.
 171
 172 =head1 USING METHOD MODIFIERS
 173
 174 Method modifiers and roles are a very powerful combination.  Often, a
 175 role will combine method modifiers and required methods. We already
 176 saw one example with our C<Breakable> example.
 177
 178 Method modifiers increase the complexity of roles, because they make
 179 the role application order relevant. If a class uses multiple roles,
 180 each of which modify the same method, those modifiers will be applied
 181 in the same order as the roles are used:
 182
 183   package MovieCar;
 184
 185   use Moose;
 186
 187   extends 'Car';
 188
 189   with 'Breakable', 'ExplodesOnBreakage';
 190
 191 Assuming that the new C<ExplodesOnBreakage> method I<also> has an
 192 C<after> modifier on C<break>, the C<after> modifiers will run one
 193 after the other. The modifier from C<Breakable> will run first, then
 194 the one from C<ExplodesOnBreakage>.
 195
 196 =head1 METHOD CONFLICTS
 197
 198 If a class composes multiple roles, and those roles have methods of
 199 the same name, we will have a conflict. In that case, the composing
 200 class is required to provide its I<own> method of the same name.
 201
 202   package Breakdancer;
 203
 204   use Moose::Role
 205
 206   sub break {
 207
 208   }
 209
 210 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
 211 provide our own C<break> method:
 212
 213   package FragileDancer;
 214
 215   use Moose;
 216
 217   with 'Breakable', 'Breakdancer';
 218
 219   sub break { ... }
 220
 221 =head1 METHOD EXCLUSION AND ALIASING
 222
 223 If we want our C<FragileDancer> class to be able to call the methods
 224 from both its roles, we can alias the methods:
 225
 226   package FragileDancer;
 227
 228   use Moose;
 229
 230   with 'Breakable'   => { -alias => { break => 'break_bone' } },
 231        'Breakdancer' => { -alias => { break => 'break_dance' } };
 232
 233 However, aliasing a method simply makes a I<copy> of the method with
 234 the new name. We also need to exclude the original name:
 235
 236   with 'Breakable' => {
 237       -alias    => { break => 'break_bone' },
 238       -excludes => 'break',
 239       },
 240       'Breakdancer' => {
 241       -alias    => { break => 'break_dance' },
 242       -excludes => 'break',
 243       };
 244
 245 The excludes parameter prevents the C<break> method from being composed
 246 into the C<FragileDancer> class, so we don't have a conflict. This
 247 means that C<FragileDancer> does not need to implement its own
 248 C<break> method.
 249
 250 This is useful, but it's worth noting that this breaks the contract
 251 implicit in consuming a role. Our C<FragileDancer> class does both the
 252 C<Breakable> and C<BreakDancer>, but does not provide a C<break>
 253 method. If some API expects an object that does one of those roles, it
 254 probably expects it to implement that method.
 255
 256 In some use cases we might alias and exclude methods from roles, but
 257 then provide a method of the same name in the class itself.
 258
 259 =head1 ROLE EXCLUSION
 260
 261 A role can say that it cannot be combined with some other role. This
 262 should be used with great caution, since it limits the re-usability of
 263 the role.
 264
 265   package Breakable;
 266
 267   use Moose::Role;
 268
 269   excludes 'BreakDancer';
 270
 271 =head1 AUTHOR
 272
 273 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 274
 275 =head1 COPYRIGHT AND LICENSE
 276
 277 Copyright 2009 by Infinity Interactive, Inc.
 278
 279 L<http://www.iinteractive.com>
 280
 281 This library is free software; you can redistribute it and/or modify
 282 it under the same terms as Perl itself.
 283
 284 =cut