NAME

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

VERSION

version 0.28

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.

• try

      package My::Try {
          use MooseX::Extended includes => [qw/try/];
  
          sub reciprocal ( $self, $num ) {
              try {
                  return 1 / $num;
              }
              catch {
                  croak "Could not calculate reciprocal of $num: $@";
              }
          }
      }

  Allows you to use try/catch blocks, via Syntax::Keyword::Try.

  Only available on Perl v5.24.0 or higher. Requires Syntax::Keyword::Try.

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/];

ATTRIBUTE SHORTCUTS

param and field in roles allow the same attribute shortcuts as MooseX::Extended.

BUGS AND LIMITATIONS

If the MooseX::Extended::Role is loaded via stringy eval, true is not loaded, This is because there were intermittant errors (maybe 1 out of 5 times) being thrown. Removing this feature under stringy eval solves this. See this github ticket for more infomration.

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)

cpanm MooseX::Extended

perl -MCPAN -e shell
install MooseX::Extended