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 =head2 Required Attributes
 173
 174 As mentioned before, a role requirement may also be satisfied by an
 175 attribute accessor. But any C<has> functions, which will generate
 176 accessors that satisfy the role requirement, must be placed
 177 I<before> the C<with> function that composes the role.
 178
 179   package Breakable;
 180
 181   use Moose::Role;
 182
 183   requires 'stress';
 184
 185   package Car;
 186
 187   use Moose;
 188
 189   has 'stress' => (
 190       is  => 'rw',
 191           isa => 'Int',
 192   );
 193
 194   with 'Breakable';
 195
 196 =head1 USING METHOD MODIFIERS
 197
 198 Method modifiers and roles are a very powerful combination.  Often, a
 199 role will combine method modifiers and required methods. We already
 200 saw one example with our C<Breakable> example.
 201
 202 Method modifiers increase the complexity of roles, because they make
 203 the role application order relevant. If a class uses multiple roles,
 204 each of which modify the same method, those modifiers will be applied
 205 in the same order as the roles are used:
 206
 207   package MovieCar;
 208
 209   use Moose;
 210
 211   extends 'Car';
 212
 213   with 'Breakable', 'ExplodesOnBreakage';
 214
 215 Assuming that the new C<ExplodesOnBreakage> method I<also> has an
 216 C<after> modifier on C<break>, the C<after> modifiers will run one
 217 after the other. The modifier from C<Breakable> will run first, then
 218 the one from C<ExplodesOnBreakage>.
 219
 220 =head1 METHOD CONFLICTS
 221
 222 If a class composes multiple roles, and those roles have methods of
 223 the same name, we will have a conflict. In that case, the composing
 224 class is required to provide its I<own> method of the same name.
 225
 226   package Breakdancer;
 227
 228   use Moose::Role
 229
 230   sub break {
 231
 232   }
 233
 234 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
 235 provide our own C<break> method:
 236
 237   package FragileDancer;
 238
 239   use Moose;
 240
 241   with 'Breakable', 'Breakdancer';
 242
 243   sub break { ... }
 244
 245 =head1 METHOD EXCLUSION AND ALIASING
 246
 247 If we want our C<FragileDancer> class to be able to call the methods
 248 from both its roles, we can alias the methods:
 249
 250   package FragileDancer;
 251
 252   use Moose;
 253
 254   with 'Breakable'   => { -alias => { break => 'break_bone' } },
 255        'Breakdancer' => { -alias => { break => 'break_dance' } };
 256
 257 However, aliasing a method simply makes a I<copy> of the method with
 258 the new name. We also need to exclude the original name:
 259
 260   with 'Breakable' => {
 261       -alias    => { break => 'break_bone' },
 262       -excludes => 'break',
 263       },
 264       'Breakdancer' => {
 265       -alias    => { break => 'break_dance' },
 266       -excludes => 'break',
 267       };
 268
 269 The excludes parameter prevents the C<break> method from being composed
 270 into the C<FragileDancer> class, so we don't have a conflict. This
 271 means that C<FragileDancer> does not need to implement its own
 272 C<break> method.
 273
 274 This is useful, but it's worth noting that this breaks the contract
 275 implicit in consuming a role. Our C<FragileDancer> class does both the
 276 C<Breakable> and C<BreakDancer>, but does not provide a C<break>
 277 method. If some API expects an object that does one of those roles, it
 278 probably expects it to implement that method.
 279
 280 In some use cases we might alias and exclude methods from roles, but
 281 then provide a method of the same name in the class itself.
 282
 283 =head1 ROLE EXCLUSION
 284
 285 A role can say that it cannot be combined with some other role. This
 286 should be used with great caution, since it limits the re-usability of
 287 the role.
 288
 289   package Breakable;
 290
 291   use Moose::Role;
 292
 293   excludes 'BreakDancer';
 294
 295 =head1 AUTHOR
 296
 297 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 298
 299 =head1 COPYRIGHT AND LICENSE
 300
 301 Copyright 2009 by Infinity Interactive, Inc.
 302
 303 L<http://www.iinteractive.com>
 304
 305 This library is free software; you can redistribute it and/or modify
 306 it under the same terms as Perl itself.
 307
 308 =cut