/ 
MooseX-DeclareX-0.009
River stage one • 5 direct dependents • 5 total dependents
/ MooseX::DeclareX

NAME

MooseX::DeclareX - more sugar for MooseX::Declare

SYNOPSIS

use 5.010;
use MooseX::DeclareX
  keywords => [qw(class exception)],
  plugins  => [qw(guard build preprocess std_constants)],
  types    => [ -Moose ];

class Banana;

exception BananaError
{
  has origin => (
    is       => read_write,
    isa      => Object,
    required => true,
  );
}

class Monkey
{
  has name => (
    is       => read_write,
    isa      => Str,
  );
  
  build name {
    state $i = 1;
    return "Anonymous $i";
  }  
  
  has bananas => (
    is       => read_write,
    isa      => ArrayRef[ Object ],
    traits   => ['Array'],
    handles  => {
      give_banana  => 'push',
      eat_banana   => 'shift',
      lose_bananas => 'clear',
      got_bananas  => 'count',
    },
  );
  
  build bananas {
    return [];
  }
  
  guard eat_banana {
    $self->got_bananas or BananaError->throw(
      origin  => $self,
      message => "We have no bananas today!",
    );
  }
  
  after lose_bananas {
    $self->screech("Oh no!");
  }

  method screech (@strings) {
    my $name = $self->name;
    say "$name: $_" for @strings;
  }  
}

class Monkey::Loud extends Monkey
{
  preprocess screech (@strings) {
    return map { uc($_) } @strings;
  }
}

try {
  my $bobo = Monkey::Loud->new;
  $bobo->give_banana( Banana->new );
  $bobo->lose_bananas;
  $bobo->give_banana( Banana->new );
  $bobo->eat_banana;
  $bobo->eat_banana;
}
catch (BananaError $e) {
  warn sprintf("%s: %s\n", ref $e, $e->message);
}

STATUS

This is very experimental stuff. YOU HAVE BEEN WARNED!

DESCRIPTION

MooseX::DeclareX takes the declarative sugar of MooseX::Declare to the next level. Some people already consider MooseX::Declare to be pretty insane. If you're one of those people, then you're not going to like this...

Keywords

class, role, extends, with, is dirty, is mutable, clean.

Inherited from MooseX::Declare.

method, around, before, after, override, augment

Inherited from MooseX::Method::Signatures.

try, catch

Inherited from TryCatch.

exception

exception Foo is sugar for class Foo extends Throwable::Error. That is, it creates a class which is a subclass of Throwable::Error.

build

This is some sugar for creating builder methods. The following two examples are roughly equivalent:

build fullname {
  join q( ), $self->firstname, $self->surname;
}

sub _build_fullname {
  my $self = shift;
  join q( ), $self->firstname, $self->surname;
}

However, build also performs a little housekeeping for you. If an attribute does not exist with the same name as the builder, it will create one for you (which will be read-only, with type constraint "Any" unless build can detect a more specific type constraint from the method's return signature). If the attribute already exists but does not have a builder set, then it will set it.

guard

Simplifies a common usage pattern for around. A guard protects a method, preventing it from being called unless a condition evaluates to true.

class Doorway
{
  method enter ($person)
  {
    ...
  }
}

class Doorway::Protected
{
  has password => (is => 'ro', isa => 'Str');
  
  guard enter ($person)
  {
    $person->knows( $self->password )
  }
}
preprocess

Another simplification for a common usage pattern for around. Acts much like before, but can modify the parameters seen by the base method. In fact, it must return the processed parameters as a list.

class Speaker
{
  method speak (@words) {
    say for @words;
  }
}

class Speaker::Loud
{
  preprocess speak {
    return map { uc($_) } @_
  }
}
postprocess

Like preprocess but instead acts on the method's return value.

read_only, read_write, true, false

Useful constants when defining Moose attributes. These are enabled by the std_constants plugin.

Export

You should indicate which features you are using:

use MooseX::DeclareX
  keywords => [qw(class role exception)],
  plugins  => [qw(guard build)];

What is the distinction between keywords and plugins? Keywords are the words that declare class-like things. Plugins are the other bits, and only work inside the class-like declarations.

Things inherited from MooseX::Declare and MooseX::Method::Signatures do not need to be indicated; they are always loaded. Things inherited from TryCatch do not need to be indicated; they are available outside class declarations too.

If you don't specify a list of keywords, then the default list is:

[qw(class role exception)]

If you don't specify a list of plugins, then the default list is:

[qw(build guard std_constants)]

That is, there are certain pieces of functionality which are not available by default - they need to be loaded explicitly!

MooseX::Types

You can inject a bunch of MooseX::Types keywords into all classes quite easily:

use MooseX::DeclareX
  keywords => [qw(class role exception)],
  plugins  => [qw(build std_constants)],
  types    => [
    -Moose,                 # use MooseX::Types::Moose -all
    -URI => [qw(FileUri)],  # use MooseX::Types::URI qw(FileUri)
    'Foo::Types',           # use Foo::Types -all
  ];

As per the example, any module which does not include an arrayref of import parameters, gets "-all". A leading hyphen is interpreted as an abbreviation for "MooseX::Types::".

Additional Import Syntactic Sugar

You can specify a list of additional modules that will always be imported "inside" your class/role definitions.

use MooseX::DeclareX
  keywords => [qw(class role exception)],
  plugins  => [qw(build guard std_constants)],
  imports  => [
    'MooseX::ClassAttribute',
    'Path::Class'      => [qw( file dir )],
    'Perl6::Junction'  => [qw( any all none )],
    'List::Util'       => [qw( first reduce )],
  ];

In fact, this is just a minor generalisation of the MooseX::Types feature.

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=MooseX-DeclareX.

SEE ALSO

MooseX::Declare, MooseX::Method::Signatures, TryCatch, Throwable::Error, MooseX::Types.

Additional keywords and plugins are available on CPAN: MooseX::DeclareX::Plugin::abstract, MooseX::DeclareX::Privacy, MooseX::DeclareX::Keyword::interface, MooseX::DeclareX::Plugin::singleton.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2012 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.