NAME

MooseX::Method - Method declaration with type checking

SYNOPSIS

package Foo;

use Moose;
use MooseX::Method;

method hello => named (
  who => { isa => 'Str',required => 1 },
  age => { isa => 'Int',required => 1 },
) => sub {
  my ($self,$args) = @_;

  print "Hello $args->{who}, I am $args->{age} years old!\n";
};

method morning => positional (
  { isa => 'Str',required => 1 },
) => sub {
  my ($self,$name) = @_;

  print "Good morning $name!\n";
};

method greet => semi (
  { isa => 'Str' },
  excited => { isa => 'Bool',default => 0 },
) => sub {
  my ($self,$name,$args) = @_;

  if ($args->{excited}) {
    print "GREETINGS $name!\n";
  } else {
    print "Hi $name!\n";
  }
};

Foo->hello (who => 'world',age => 42); # This works.

Foo->morning ('Jens'); # This too.

Foo->greet ('Jens',excited => 1); # And this as well.

Foo->hello (who => 'world',age => 'fortytwo'); # This doesn't.

Foo->morning; # This neither.

Foo->greet; # Won't work.

DESCRIPTION

The problem

This module is an attempt to solve a problem I've often encountered but never really found any good solution for, namely validation of method parameters. How many times haven't we all found ourselves writing code like this:

sub foo {
  my ($self,$args) = @_;

  die "Invalid arg1"
    unless (defined $arg->{bar} && $arg->{bar} =~ m/bar/);
}

Manual parameter validation is a tedious and repetive process and maintaining it consistently throughout your code can be downright hard sometimes. Modules like Params::Validate makes the job a bit easier but it doesn't do much for elegance and it still requires more weird code than what should strictly speaking be neccesary.

The solution

MooseX::Method to the rescue. It lets you declare what parameters people should be passing to your method using Moose-style declaration and Moose types. It doesn't get much Moosier than this.

DECLARING METHODS

method $name => named () => sub {}

The exported function method installs a method into the class from which it is called from. The first parameter it takes is the name of the method. The rest of the parameters needs not be in any particular order, though it's probably best for the sake of readability to keep the subroutine at the end.

Parameters

The parameter specification should look something to this effect:

named (
  foo => { isa => 'Int',required => 1 },
  bar => { isa => 'Int' },
)

Or for positional arguments...

positional (
  { isa => 'Int',required => 1 },
  { isa => 'Int' },
)

The first example will make MooseX::Method create a method which takes two parameters, 'foo' and 'bar', of which only 'foo' is mandatory. The second example will create two positional parameters with the same properties.

There's also a third type of signature available, which lets you get the best from both worlds.

semi (
  { isa => 'Int' },
  foo => { isa => 'Int' },
)

Here we mix the two previously mentioned signature types, which lets you call a method with a syntax like:

Foo->add_item ($item,protected => 1);

A gotcha to be aware of is that all positional parameters becomes required when using this signature type. Named parameters can still be mandatory or optional like usual. Also, all positional arguments must be put first in the argument list like in the example used. Named parameters are put afterwards.

Currently, a parameter may set any of the following fields:

isa

If a value is provided, it must satisfy the constraints of the type specified in this field.

does

Require that the value provided is able to do a certain role.

default

Sets the parameter to a default value if the user does not provide it.

required

If this field is set, supplying a value to the method isn't optional but the value may be supplied by the default field.

coerce

If the type supports coercion, attempt to coerce the value provided if it does not satisfy the requirements of isa. See Moose for examples of how to coerce.

metaclass

This is used as parameter metaclass if specified. If you don't know what this means, read the documentation for Moose.

Attributes

To set a method attribute, use the following syntax:

method foo => attr (
  attribute => $value,
) => named (
  # Regular parameter stuff here
) => sub {};

You can set the default method attributes for a class by having a hashref with them returned from the method _default_method_attributes like this:

sub _default_method_attributes { attr (attribute => $value) }

method foo => attr (
  overridden_attribute => $value,
) => named (
  # Regular parameter stuff here
) => sub {};

At present time, not many attributes will actually do much.

metaclass

Sets the metaclass to use for when creating the method.

FUTURE

I'm considering using a param() function to declare individual parameters, but I feel this might have a bit too high risk of clashing with existing functions of other modules. Your thoughts on the subject is welcome.

CAVEATS

Methods are added to the class at runtime, which obviously means they won't be available to play with at compile-time. Moose won't mind this but a few other modules probably will. A workaround for this that sometimes work is to encapsulate the method declarations in a BEGIN block.

There's also a problem related to how roles are loaded in Moose. Since both MooseX::Method methods and Moose roles are loaded runtime, any methods a role requires in some way must be declared before the 'with' statement. This affects things like 'before' and 'after'.

ACKNOWLEDGEMENTS

Stevan Little for making Moose and luring me into the world of metafoo.

SEE ALSO

Moose

The #moose channel on irc.perl.org

BUGS

Most software has bugs. This module probably isn't an exception. If you find a bug please either email me, or add the bug to cpan-RT.

AUTHOR

Anders Nor Berle <debolaz@gmail.com>

COPYRIGHT AND LICENSE

Copyright 2007 by Anders Nor Berle.

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

cpanm MooseX::Method

perl -MCPAN -e shell
install MooseX::Method