From: Gerda Shank <gerda.shank@gmail.com>
Date: Tue, 8 Sep 2009 23:03:22 +0000 (-0400)
Subject: documentation for applying roles, specifically to instances
X-Git-Tag: 0.89_02~13
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b9cb323b8ba024b6e96918a3dbd5255e7f470cc0;p=gitmo%2FMoose.git

documentation for applying roles, specifically to instances
---

diff --git a/lib/Moose/Manual/Roles.pod b/lib/Moose/Manual/Roles.pod
index 888a238..c2f5df1 100644
--- a/lib/Moose/Manual/Roles.pod
+++ b/lib/Moose/Manual/Roles.pod
@@ -100,6 +100,8 @@ We could use this same role in a C<Bone> class:
       isa => 'Marrow',
   );
 
+See also L<Moose::Cookbook::Roles::Recipe1> for an example.
+
 =head1 REQUIRED METHODS
 
 As mentioned previously, a role can require that consuming classes
@@ -242,6 +244,14 @@ provide our own C<break> method:
 
   sub break { ... }
 
+A role can be a collection of other roles:
+
+  package Break::Bundle;
+
+  use Moose::Role;
+
+  with ('Breakable', 'Breakdancer');
+
 =head1 METHOD EXCLUSION AND ALIASING
 
 If we want our C<FragileDancer> class to be able to call the methods
@@ -280,6 +290,8 @@ 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 L<Moose::Cookbook::Roles::Recipe2> for an example.
+
 =head1 ROLE EXCLUSION
 
 A role can say that it cannot be combined with some other role. This
@@ -292,6 +304,40 @@ the role.
 
   excludes 'BreakDancer';
 
+=head1 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 L<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 L<Moose::Role> and L<Moose::Util> for more details and 
+L<Moose::Cookbook::Roles::Recipe3> for a more developed example.
+
 =head1 AUTHOR
 
 Dave Rolsky E<lt>autarch@urth.orgE<gt>
diff --git a/lib/Moose/Role.pm b/lib/Moose/Role.pm
index ea4b80e..fcf7c88 100644
--- a/lib/Moose/Role.pm
+++ b/lib/Moose/Role.pm
@@ -234,6 +234,23 @@ this, your class's C<meta> object will have the specified traits
 applied to it. See L<Moose/Metaclass and Trait Name Resolution> for more
 details.
 
+=head1 APPLYING ROLES
+
+In addition to being applied to a class using the 'with' syntax (see
+L<Moose::Manual::Roles>) and using the L<Moose::Util> 'apply_all_roles'
+method, roles may also be applied to an instance of a class using
+L<Moose::Util> 'apply_all_roles' or the role's metaclass:
+
+   MyApp::Test::SomeRole->meta->apply( $instance );
+
+Doing this creates a new, mutable, anonymous subclass, applies the role to that,
+and reblesses. In a debugger, for example, you will see class names of the
+form C< Class::MOP::Class::__ANON__::SERIAL::6 >, which means that doing a 'ref'
+on your instance may not return what you expect. See L<Moose::Object> for 'DOES'.
+
+Additional params may be added to the new instance by providing 'rebless_params'.
+See L<Moose::Meta::Role::Application::ToInstance>.
+
 =head1 CAVEATS
 
 Role support has only a few caveats: