package Moose::Cookbook::Roles::Recipe2;
-# ABSTRACT: Advanced Role Composition - method exclusion and aliasing
-
__END__
-
=pod
-=head1 SYNOPSIS
-
- package Restartable;
- use Moose::Role;
-
- has 'is_paused' => (
- is => 'rw',
- isa => 'Bool',
- default => 0,
- );
-
- requires 'save_state', 'load_state';
-
- sub stop { 1 }
-
- sub start { 1 }
-
- package Restartable::ButUnreliable;
- use Moose::Role;
-
- with 'Restartable' => {
- -alias => {
- stop => '_stop',
- start => '_start'
- },
- -excludes => [ 'stop', 'start' ],
- };
-
- sub stop {
- my $self = shift;
-
- $self->explode() if rand(1) > .5;
-
- $self->_stop();
- }
-
- sub start {
- my $self = shift;
-
- $self->explode() if rand(1) > .5;
-
- $self->_start();
- }
-
- package Restartable::ButBroken;
- use Moose::Role;
-
- with 'Restartable' => { -excludes => [ 'stop', 'start' ] };
-
- sub stop {
- my $self = shift;
-
- $self->explode();
- }
-
- sub start {
- my $self = shift;
-
- $self->explode();
- }
-
-=head1 DESCRIPTION
-
-In this example, we demonstrate how to exercise fine-grained control
-over what methods we consume from a role. We have a C<Restartable>
-role which provides an C<is_paused> attribute, and two methods,
-C<stop> and C<start>.
-
-Then we have two more roles which implement the same interface, each
-putting their own spin on the C<stop> and C<start> methods.
-
-In the C<Restartable::ButUnreliable> role, we want to provide a new
-implementation of C<stop> and C<start>, but still have access to the
-original implementation. To do this, we alias the methods from
-C<Restartable> to private methods, and provide wrappers around the
-originals (1).
-
-Note that aliasing simply I<adds> a name, so we also need to exclude the
-methods with their original names.
-
- with 'Restartable' => {
- -alias => {
- stop => '_stop',
- start => '_start'
- },
- -excludes => [ 'stop', 'start' ],
- };
-
-In the C<Restartable::ButBroken> role, we want to provide an entirely
-new behavior for C<stop> and C<start>. We exclude them entirely when
-composing the C<Restartable> role into C<Restartable::ButBroken>.
-
-It's worth noting that the C<-excludes> parameter also accepts a single
-string as an argument if you just want to exclude one method.
-
- with 'Restartable' => { -excludes => [ 'stop', 'start' ] };
-
-=head1 CONCLUSION
-
-Exclusion and renaming are a power tool that can be handy, especially
-when building roles out of other roles. In this example, all of our
-roles implement the C<Restartable> role. Each role provides same API,
-but each has a different implementation under the hood.
-
-You can also use the method aliasing and excluding features when
-composing a role into a class.
-
-=head1 FOOTNOTES
-
-=over 4
-
-=item (1)
-
-The mention of wrapper should tell you that we could do the same thing
-using method modifiers, but for the sake of this example, we don't.
-
-=back
-
-=begin testing
-
-{
- my $unreliable = Moose::Meta::Class->create_anon_class(
- superclasses => [],
- roles => [qw/Restartable::ButUnreliable/],
- methods => {
- explode => sub { }, # nop.
- 'save_state' => sub { },
- 'load_state' => sub { },
- },
- )->new_object();
- ok( $unreliable, 'made anon class with Restartable::ButUnreliable role' );
- can_ok( $unreliable, qw/start stop/ );
-}
-
-{
- my $cnt = 0;
- my $broken = Moose::Meta::Class->create_anon_class(
- superclasses => [],
- roles => [qw/Restartable::ButBroken/],
- methods => {
- explode => sub { $cnt++ },
- 'save_state' => sub { },
- 'load_state' => sub { },
- },
- )->new_object();
-
- ok( $broken, 'made anon class with Restartable::ButBroken role' );
-
- $broken->start();
-
- is( $cnt, 1, '... start called explode' );
-
- $broken->stop();
-
- is( $cnt, 2, '... stop also called explode' );
-}
-
-=end testing
+=head1 RENAMED TO L<Moose::Cookbook::Roles::Restartable_AdvancedComposition>
=cut
projects / gitmo/Moose-OldDocs.git / blobdiff