/ 
Jojo-Role-0.6.0
River stage zero No dependents
/ Jojo::Role

NAME

Jojo::Role - Role::Tiny + lexical "with"

VERSION

version 0.6.0

SYNOPSIS

package Some::Role {
  use Jojo::Role;    # requires perl 5.18+

  sub foo {...}
  sub bar {...}
  around baz => sub {...};
}

package Some::Class {
  use Jojo::Role -with;
  with 'Some::Role';

  # bar gets imported, but not foo
  sub foo {...}

  # baz is wrapped in the around modifier by Class::Method::Modifiers
  sub baz {...}
}

DESCRIPTION

Jojo::Role works kind of like Role::Tiny but with, requires, before, after and around are exported as lexical subroutines.

This is a companion to Jojo::Base.

Jojo::Role may be used in two ways. First, to declare a role, which is done with

use Jojo::Base;
use Jojo::Base -role;    # Longer version

Second, to compose one or more roles into a class, via

use Jojo::Base -with;

IMPORTED -role SUBROUTINES

The -role tag exports the following subroutines into the caller.

after

after foo => sub { ... };

Declares an "after" modifier to be applied to the named method at composition time.

around

around => sub { ... };

Declares an "around" modifier to be applied to the named method at composition time.

before

before => sub { ... };

Declares a "before" modifier to be applied to the named method at composition time.

requires

requires qw(foo bar);

Declares a list of methods that must be defined to compose the role.

with

with 'Some::Role';

with 'Some::Role1', 'Some::Role2';

Composes one or more roles into the current role.

IMPORTED -with SUBROUTINES

The -with tag exports the following subroutine into the caller. It is equivalent to using Role::Tiny::With.

with

with 'Some::Role1', 'Some::Role2';

Composes one or more roles into the current class.

METHODS

Jojo::Role inherits all methods from Role::Tiny and implements the following new ones.

apply_roles_to_package

Jojo::Role->apply_roles_to_package('Some::Package', qw(Some::Role +Other::Role));

create_class_with_roles

Jojo::Role->create_class_with_roles('Some::Base', qw(Some::Role1 +Role2));

import

Jojo::Role->import();
Jojo::Role->import(-role);
Jojo::Role->import(-with);

make_role

Jojo::Role->make_role('Some::Package');

Promotes a given package to a role. No subroutines are imported into 'Some::Package'.

CAVEATS

  • Jojo::Role requires perl 5.18 or newer

  • Because a lexical sub does not behave like a package import, some code may need to be enclosed in blocks to avoid warnings like

    "state" subroutine &with masks earlier declaration in same scope at...

SEE ALSO

Role::Tiny, Jojo::Base.

ACKNOWLEDGMENTS

Thanks to the authors of Role::Tiny, which hold the copyright over the original code.

AUTHOR

Adriano Ferreira <ferreira@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017-2018 by Adriano Ferreira.

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