/ 
MooseX-Extended-0.21
River stage one • 1 direct dependent • 1 total dependent
/ MooseX::Extended::Role

NAME

MooseX::Extended::Role - MooseX::Extended roles

VERSION

version 0.21

SYNOPSIS

package Not::Corinna::Role::Created {
    use MooseX::Extended::Role types => ['PositiveInt'];

    field created => ( isa => PositiveInt, default => sub { time } );
}

Similar to MooseX::Extended, providing almost everything that module provides. However, for obvious reasons, it does not include MooseX::StrictConstructor or make your class immutable, or set the C3 mro.

Note that there is no need to add a 1 at the end of the role.

CONFIGURATION

You may pass an import list to MooseX::Extended::Role.

use MooseX::Extended::Role
  excludes => [qw/WarnOnConflict carp/],         # I don't want these features
  types    => [qw/compile PositiveInt HashRef/]; # I want these type tools

types

Allows you to import any types provided by MooseX::Extended::Types.

This:

use MooseX::Extended::Role types => [qw/compile PositiveInt HashRef/];

Is identical to this:

use MooseX::Extended::Role;
use MooseX::Extended::Types qw( compile PositiveInt HashRef );

excludes

You may find some features to be annoying, or even cause potential bugs (e.g., if you have a `croak` method, our importing of Carp::croak will be a problem. You can exclude the following:

  • WarnOnConflict

    use MooseX::Extended::Role excludes => ['WarnOnConflict'];

    Excluding this removes the MooseX::Role::WarnOnConflict role.

  • autoclean

    use MooseX::Extended::Role excludes => ['autoclean'];

    Excluding this will no longer import namespace::autoclean.

  • carp

    use MooseX::Extended::Role excludes => ['carp'];

    Excluding this will no longer import Carp::croak and Carp::carp.

  • true

    use MooseX::Extended::Role excludes => ['true'];

    Excluding this will require your module to end in a true value.

  • param

    use MooseX::Extended::Role excludes => ['param'];

    Excluding this will make the param function unavailable.

  • field

    use MooseX::Extended::Role excludes => ['field'];

    Excluding this will make the field function unavailable.

includes

Some experimental features are useful, but might not be quite what you want.

  • multi

    use MooseX::Extended::Role includes => [qw/multi/];

multi sub foo ($self, $x)      { ... }
multi sub foo ($self, $x, $y ) { ... }

    Allows you to redeclare a method (or subroutine) and the dispatch will use the number of arguments to determine which subroutine to use. Note that "slurpy" arguments such as arrays or hashes will take precedence over scalars:

    multi sub foo ($self, @x) { ... }
multi sub foo ($self, $x) { ... } # will never be called

    Only available on Perl v5.26.0 or higher. Requires Syntax::Keyword::MultiSub.

  • async

    package My::Thing {
    use MooseX::Extended
    types    => [qw/Str/],
    includes => ['async'];
    use IO::Async::Loop;

    field output => ( is => 'rw', isa => Str, default => '' );

    async sub doit ( $self, @list ) {
        my $loop = IO::Async::Loop->new;
        $self->output('> ');
        foreach my $item (@list) {
            await $loop->delay_future( after => 0.01 );
            $self->output( $self->output . "$item " );
        }
    }
}

    Allows you to write asynchronous code with async and await.

    Only available on Perl v5.26.0 or higher. Requires Future::AsyncAwait.

IDENTICAL METHOD NAMES IN CLASSES AND ROLES

In Moose if a class defines a method of the name as the method of a role it's consuming, the role's method is silently discarded. With MooseX::Extended::Role, you get a warning. This makes maintenance easier when to prevent you from accidentally overriding a method.

For example:

package My::Role {
    use MooseX::Extended::Role;

    sub name {'Ovid'}
}

package My::Class {
    use MooseX::Extended;
    with 'My::Role';
    sub name {'Bob'}
}

The above code will still run, but you'll get a very verbose warning:

The class My::Class has implicitly overridden the method (name) from
role My::Role. If this is intentional, please exclude the method from
composition to silence this warning (see Moose::Cookbook::Roles::Recipe2)

To silence the warning, just be explicit about your intent:

package My::Class {
    use MooseX::Extended;
    with 'My::Role' => { -excludes => ['name'] };
    sub name {'Bob'}
}

Alternately, you can exclude this feature. We don't recommend this, but it might be useful if you're refactoring a legacy Moose system.

use MooseX::Extended::Role excludes => [qw/WarnOnConflict/];

REDUCING BOILERPLATE

Let's say you've settled on the following feature set:

use MooseX::Extended::Role
    excludes => [qw/WarnOnConflict carp/],
    includes => [qw/multi/];

And you keep typing that over and over. We've removed a lot of boilerplate, but we've added different boilerplate. Instead, just create My::Custom::Moose::Role and use My::Custom::Moose::Role;. See MooseX::Extended::Role::Custom for details.

AUTHOR

Curtis "Ovid" Poe <curtis.poe@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2022 by Curtis "Ovid" Poe.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)