Curtis "Ovid" Poe > Role-Basic > Role::Basic

Download:
Role-Basic-0.13.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  2
View/Report Bugs
Module Version: 0.13   Source  

NAME ^

Role::Basic - Just roles. Nothing else.

VERSION ^

Version 0.13

SYNOPSIS ^

In a role:

    package Does::Serialize::AsYAML;
    use Role::Basic;
    use YAML::Syck;
    requires 'as_hash';

    sub serialize {
        my $self = shift;
        return Dump( $self->as_hash );
    }

    1;

In your class:

    package My::Class;
    use Role::Basic 'with';

    with qw(
        Does::Serialize::AsYAML
    );

    sub as_hash { ... } # because the role requires it

BETA CODE ^

This code appears to be stable and currently passes over 300 tests. We've not (yet) heard of any bugs. There are no functional changes with this release. It's merely here to let early-adopters know it's safe to give it a spin.

DESCRIPTION ^

For an extended discussion, see http://blogs.perl.org/users/ovid/2010/12/rolebasic---when-you-only-want-roles.html.

Sometimes you want roles. You're not sure about Moose, Mouse, Moo and what was that damned Squirrel thing anyway? Then there's Class::Trait, but it has a funky syntax and the maintainer's deprecated it in favor of Moose::Role and you really don't care that it handles overloading, instance application or has a workaround for the SUPER:: bug. You think a meta-object protocol sounds nifty, but you don't understand it. Maybe you're not sure you want the syntactic sugar for object declaration. Maybe you've convinced your colleagues that roles are a good idea but they're leery of dragging in Moose (your author has had this happen more than once and heard of others making the same complaint). Sometimes you just want good old-fashioned roles which let you separate class responsibility from code reuse.

Whatever your reasons, this is the module you're looking for. It only provides roles and its major design goals are safety and simplicity. It also aims to be a subset of Moose::Role behavior so that when/if you're ready to upgrade, there will be minimal pain.

DECLARING A ROLE ^

To declare the current package as a role, simply add the following line to the package:

    use Role::Basic;

You can then use with to consume other roles and requires to list the methods this role requires. Note that the only methods the role will provide are methods declared directly in the role or consumed from other roles. Thus:

    package My::Role;
    use Role::Basic;
    use List::Util 'sum'; # this will not be provided by the role
    with 'Some::Other::Role'; # any methods from this role will be provided

    sub some_method {...} # this will be provided by the role

Allowed methods in roles

Warning: this functionality is experimental and is subject to change with no warning.

As mentioned, methods imported into a role are not provided by that role. However, this can make it very hard when you want to provide simple getters/setters. To get around this limitation, a role (and only roles, not classes) may specify one class which they 'allow' to provide additional methods:

    package My::Role;
    use Role::Basic allow => 'Class::BuildMethods';
    use Class::BuildMethods qw/foo bar/;

    # your role will now provide foo and bar methods
    # rest of role definition here

Please note that if you do this, the code which provides these 'extra' methods should not provide them in a way which is incompatible with your objects. For example, many getter/setters generation classes assume you're using a blessed hashref. Most objects are, but the role should not make such an assumption about the class which consumes it. In the above example, we use Class::BuildMethods. It's agnostic about your object implementation, but it's slow.

See http://blogs.perl.org/users/ovid/2011/01/happy-new-yearroles.html and search for 'glue' to understand why this is important.

CONSUMING ROLES ^

To declare the current package as a class that will use roles, simply add the following line to the package:

    use Role::Basic 'with';

Just as with Moose, you can have -alias, -excludes, and -version.

Unlike Moose, we also provide a -rename target. It combines -alias and -excludes. This code:

    package My::Class;
    use Role::Basic 'with';

    with 'My::Role' => {
        -rename => { foo => 'baz', bar => 'gorch' },
    };

Is identical to this code:

    package My::Class;
    use Role::Basic 'with';

    with 'My::Role' => {
        -alias    => { foo => 'baz', bar => 'gorch' },
        -excludes => [qw/foo bar/],
    };

EXPORT ^

Both roles and classes will receive the following methods:

Further, if you're a role, you can also specify methods you require:

DESIGN GOALS AND LIMITATIONS ^

There are two overriding design goals for Role::Basic: simplicity and safety. We make it a bit harder to shoot yourself in the foot and we aim to keep the code as simple as possible. Feature requests are welcomed, but will not be acted upon if they violate either of these two design goals.

Thus, if you need something which Role::Basic does not support, you're strongly encouraged to consider Moose or Mouse.

The following list details the outcomes of this module's goals.

AUTHOR ^

Curtis 'Ovid' Poe, <ovid at cpan.org>

BUGS ^

Please report any bugs or feature requests to bug-role-basic at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Role-Basic. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Role::Basic

You can also look for information at:

SEE ALSO ^

LICENSE AND COPYRIGHT ^

Copyright 2010 Curtis 'Ovid' Poe.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

syntax highlighting: