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.