From: Dave Rolsky <autarch@urth.org>
Date: Fri, 11 Sep 2009 15:09:24 +0000 (-0500)
Subject: Add a section on applying roles to an object (accidentally added this in a branch... 
X-Git-Tag: 0.90~53
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=40edf9591aa274f1ec9dbc02d81f8dc96353bc8a;p=gitmo%2FMoose.git

Add a section on applying roles to an object (accidentally added this in a branch where it doesn't belong)
---

diff --git a/lib/Moose/Manual/Roles.pod b/lib/Moose/Manual/Roles.pod
index c2f5df1..3c36265 100644
--- a/lib/Moose/Manual/Roles.pod
+++ b/lib/Moose/Manual/Roles.pod
@@ -338,6 +338,27 @@ 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 ADDING A ROLE TO AN OBJECT INSTANCE
+
+Sometimes 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 C<apply_all_roles> function from
+L<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
+C<with>.
+
 =head1 AUTHOR
 
 Dave Rolsky E<lt>autarch@urth.orgE<gt>