NAME

Class::Role - Support for the role object model

SYNOPSIS

package LongLiver;
    use Class::Role;              # This is a role

    sub profess {
        my ($self) = @_;
        print $self->name . " live a long time\n";
    }

package Donkey;
    use Class::Role LongLiver;    # Incorporates this role

    sub name {
        return "Donkeys";
    }

    sub new {
        bless {} => shift;
    }

package main;
my $benjamin = Donkey->new;

$benjamin->profess;         # prints "Donkeys live a long time"

DESCRIPTION

Class::Role is an implementation of 'traits', as explained in this paper:

http://www.cse.ogi.edu/~black/publications/TR_CSE_02-012.pdf

It's an object model similar to mixins, except saner. The module gets its name from Larry's current name for a similar concept in Perl 6's object model. In Perl 6, traits are a different thing entirely, and I don't want to confuse anybody. :-)

Inheritance is [was designed to be] used as a way to extend an object in its behavior, but it is often abused as a method of simple code reuse (in the form of stateless, abstract classes). Roles fit this latter, er, role better. A Role is a small, combinable piece of reusable code.

Roles are stateless collections of methods that can be combined into a class (or another role). These methods may call methods of the combining object, not defined by the role itself. They are incorporated in as if they were written directly into the combining class.

To define a role, create a package with the methods you want the role to provide, and use Class::Role, as in the SYNOPSIS.

When creating a role, you may specify which methods you wish to export to the combining class with the -methods option. If the option is not given, all methods (except for import) are exported.

To combine a role, either use Class::Role with the name of the role as an argument, or just eg. use TwoLegs, if you have defined it in TwoLegs.pm. Methods defined in the combining class override methods in a combined role, however methods in the role override methods in any base classes.

When combining a role, there are several options you can give:

-excludes

Give a method or arrayref of methods to exclude from combining. This is the recommended way to deal with conflicts (see below).

For instance,

use Class::Role Farm, excludes => ['snowball'];

-conflict

What to do if there's role conflict. One of the values:

'die'

Exit with an error message. This is the default.

'exclude'

Omit the offending method entirely. Usually this means you'll implement it yourself.

'keep'

"Keep" any existing role method defined; that is, use the first one. Methods in the combining class still override.

'replace'

Overwrite any existing role method defined; that is, use the last one. Methods in the combining class still override.

'mixin'

Synonym for 'replace'.

It is recommended that you keep this the default.

There is one small detail regarding methods behaving exactly as if they were written directly into the combining class: SUPER doesn't work right. SUPER would instead look in any base classes of the role, not of the the combining class.

To circumvent this, Class::Role provides the pseudopackage PARENTCLASS, which works exactly like SUPER, except that it works correctly for (and only for) roles. So, when you're writing a role, use PARENTCLASS instead of SUPER.

NOTE: in the first release of this module, PARENTCLASS was named PARENT, but that was conflicting with the parent module.

SEE ALSO

mixin, Class::Mixin

AUTHOR

Luke Palmer, <luke@luqui.org>

COPYRIGHT AND LICENSE

Copyright 2003 by Luke Palmer

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