/ 
Perl6-Roles-0.01
River stage zero No dependents
/ Perl6::Roles

NAME

Perl6::Role - Perl6 roles in Perl5

SYNOPSIS

package Some::Role;

# to make the package a role, 
# just inherit from Perl6::Roles
use base 'Perl6::Roles'; 

sub foo { ... }
sub foobar { ... }

package Some::Other::Role;

use base 'Perl6::Roles';

sub bar { ... }

package Your::Class;

use Some::Role;
Some::Role->apply( __PACKAGE__ );
# or ...
Some::Role->apply( 'Some::Class' ); 

sub new { ... }
sub foobar { ... }
sub bar { ... }

package main;

my $object = Your::Class->new;
$object->foo(); # This calls Some::Role::foo()
$object->bar(); # This calls Your::Class::bar()
$object->foobar(); # This calls Your::Class::foobar()

if ( Your::Class->does( 'Some::Role' ) ) {
    # This will evaluate as true
}

if ( $object->does( 'Some::Role' ) ) {
    # This will evaluate as true
}

Some::Other::Role->apply( $object );

if ( Your::Class->does( 'Some::Other::Role' ) ) {
    # This will evaluate as false
}

if ( $object->does( 'Some::Other::Role' ) ) {
    # This will evaluate as true
}

DESCRIPTION

This is an implementation of current state of Perl6 roles in Perl5. It draws very heavily from both the Class::Role and Class::Roles modules, but is backwards compatible with neither of them.

ROLES

What is a Role?

Roles are a form of behavior reuse, and can be thought of as a collection of methods unassociated with a particular class. Roles are composed into classes, at which point the methods in the role are flattened into that particular class.

A valid role is one that inherits directly from Perl6::Roles and does not inherit from anything else. Other than that, it is just a package with methods inside.

Is attribute composition supported?

Since Perl (5) provides no consistent way to handle instance attributes, it is difficult to code this behavior in a generic way. That is not to say it is not possible to do this, especially given some kind of consistent class/instance structure. However, this is left as an exercise for the reader.

METHODS

apply( $class|$object )

If a $class, this will apply the role (which is the invocant) to the given class. It will add all the methods within the role that the class doesn't already have and mark the class as 'does' the role.

If an $object, this will create a new class that inherits from the original class, apply the role to that new class, and rebless the object into that new class.

does( $role )

This method is not actually contained within Perl6::Roles. It is installed in UNIVERSAL, which is the package that all objects automagically inherit from. This allows the syntax $some_random_object->does( 'Some::Role' );.

This method will return true if the given class or object 'does' the given role and false otherwise.

Note: A class does itself and all its parents. An object does its class and all of its parent classes.

CODE COVERAGE

We use Devel::Cover to test the code coverage of our tests. Below is the Devel::Cover report on this module's test suite.

---------------------------- ------ ------ ------ ------ ------ ------ ------
File                           stmt   bran   cond    sub    pod   time  total
---------------------------- ------ ------ ------ ------ ------ ------ ------
/Perl6/Roles.pm               100.0  100.0   90.9  100.0  100.0  100.0   99.2
Total                         100.0  100.0   90.9  100.0  100.0  100.0   99.2
---------------------------- ------ ------ ------ ------ ------ ------ ------

ACKNOWLEDGEMENTS

This code is based very heavily upon both Class::Role (written by Luke Palmer) and Class::Roles (written by chromatic).

AUTHORS

Rob Kinyon <rob.kinyon@iinteractive.com>

Stevan Little <stevan.little@iinteractive.com>

Thanks to Infinity Interactive for generously donating our time.

COPYRIGHT AND LICENSE

Copyright 2005 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.