Moose::Cookbook::Roles::Recipe3(3)			User Contributed Perl Documentation			Moose::Cookbook::Roles::Recipe3(3)

NAME

       Moose::Cookbook::Roles::Recipe3 - Applying a role to an object instance

VERSION

       version 2.0205

SYNOPSIS

	 package MyApp::Role::Job::Manager;

	 use List::Util qw( first );

	 use Moose::Role;

	 has 'employees' => (
	     is  => 'rw',
	     isa => 'ArrayRef[Employee]',
	 );

	 sub assign_work {
	     my $self = shift;
	     my $work = shift;

	     my $employee = first { !$_->has_work } @{ $self->employees };

	     die 'All my employees have work to do!' unless $employee;

	     $employee->work($work);
	 }

	 package main;

	 my $lisa = Employee->new( name => 'Lisa' );
	 MyApp::Role::Job::Manager->meta->apply($lisa);

	 my $homer = Employee->new( name => 'Homer' );
	 my $bart  = Employee->new( name => 'Bart' );
	 my $marge = Employee->new( name => 'Marge' );

	 $lisa->employees( [ $homer, $bart, $marge ] );
	 $lisa->assign_work('mow the lawn');

DESCRIPTION

       In this recipe, we show how a role can be applied to an object. In this specific case, we are giving an employee managerial
       responsibilities.

       Applying a role to an object is simple. The Moose::Meta::Role object provides an "apply" method. This method will do the right thing when
       given an object instance.

	 MyApp::Role::Job::Manager->meta->apply($lisa);

       We could also use the "apply_all_roles" function from Moose::Util.

	 apply_all_roles( $person, MyApp::Role::Job::Manager->meta );

       The main advantage of using "apply_all_roles" is that it can be used to apply more than one role at a time.

       We could also pass parameters to the role we're applying:

	 MyApp::Role::Job::Manager->meta->apply(
	     $lisa,
	     -alias => { assign_work => 'get_off_your_lazy_behind' },
	 );

       We saw examples of how method exclusion and alias working in roles recipe 2.

CONCLUSION

       Applying a role to an object instance is a useful tool for adding behavior to existing objects. In our example, it is effective used to
       model a promotion.

       It can also be useful as a sort of controlled monkey-patching for existing code, particularly non-Moose code. For example, you could create
       a debugging role and apply it to an object at runtime.

AUTHOR

       Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011 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.12.5							    2011-09-06					Moose::Cookbook::Roles::Recipe3(3)