NAME
MooseX::Params - Subroutine signature declaration via attributes
VERSION
version 0.010
SYNOPSIS
# use Moose types for validation
# positional arguments are by default required
sub add :Args(Int first, Int second) {
return $_{first} + $_{second};
}
say add(2, 3); # 5
say add(2); # error
# @_ still works: you can ignore %_ if you want to
sub add2 :Args(Int first, Int second) {
my ($first, $second) = @_;
return $first + $second;
}
say add2(2, 3); # 5
# '&' before a type constraint enables coercion
subtype 'HexNum', as 'Str', where { /[a-f0-9]/i };
coerce 'Int', from 'HexNum', via { hex $_ };
sub add3 :Args(&Int first, &Int second) {
return $_{first} + $_{second};
}
say add3('A', 'B'); # 21
# slurpy arguments consume the remainder of @_
sub sum :Args(ArrayRef *values) {
my $sum = 0;
my @values = @{$_{values}};
foreach my $value (@values) {
$sum += $value;
}
return $sum;
}
say sum(2, 3, 4, 5); # 14
# 'all' is optional:
# if not present search the text within a file and return 1 if found, 0 if not
# if present search the text and return number of lines in which text is found
sub search :Args(text, fh, all?) {
my $cnt = 0;
while (my $line = $_{fh}->getline) {
if ( index($line, $_{text}) > -1 ) {
return 1 if not $_{all};
$cnt++;
}
}
return $cnt;
}
# named arguments
sub foo :Args(a, :b) {
return $_{a} + $_{b} * 2;
}
# say foo( 3, b => 2 ); # 7
# say foo(4, 9); # error
# say foo(2); # error
# say foo(2, 3, 4); # error
# parameters are immutable, assign to a variable to edit
sub trim :Args(Str string) {
my $string = $_{string};
$string =~ s/^\s*//;
$string =~ s/\s*$//;
return $string;
}
# parameters can have simple defaults
sub find_clothes :Args(:size = 'medium', :color = 'white') { ... }
# or builders for more complex tasks
sub find_clothes :Args(
:size = _build_param_size,
:color = _build_param_color,
:height = 170 )
{ ... }
sub _build_param_color {
return (qw(red green blue))[ int( rand 3 ) ];
}
# you can access all other parameters within a builder
sub _build_param_size {
return $_{height} > 200 ? 'large' : 'medium';
}
# preprocess @_ with buildargs
sub process_template
:Args(input, output, params)
:BuildArgs(_buildargs_process_template)
{
say "open $_{input}";
say "replace " . Dumper $_{params};
say "save $_{output}";
}
# if 'output' is not provided, deduct it from input filename
sub _buildargs_process_template {
if (@_ == 2) {
my ($input, $params) = @_;
my $output = $input;
substr($output, -4, 4, "html");
return $input, $output, $params;
} else {
return @_;
}
}
my %data = (
fname => "Foo",
lname => "Bar",
);
process_template("index.tmpl", \%data);
# open index.tmpl
# replace {"lname" => "Bar", "fname" => "Foo"}
# save index.html
process_template("from.tmpl", "to.html", \%data);
# open from.tmpl
# replace {"lname" => "Bar", "fname" => "Foo"}
# save to.html
# additional validation with checkargs
sub process_person
:Args(:first_name!, :last_name!, :country!, :ssn?)
:CheckArgs # shortcut for :CheckArgs(_checkargs_${subname})
{ ... }
sub _checkargs_process_person {
if ( $_{country} eq 'USA' ) {
die 'All US residents must have an SSN' unless $_{ssn};
}
}
# return value validation
sub sum :Args(a, b) :Returns(Num) { ... }
# validate non-scalar return values
sub get_data :Returns(Array) { qw(foo bar baz) }
my ($foo, $bar, $baz) = get_data();
# force special behavior in sclar context
sub get_winners :Returns(Array) :ReturnsScalar(First) {
my @ordered_winners = ...;
return @ordered_winners;
}
my $first_place = get_winners();
# in a class
package User;
use Moose;
use MooseX::Params;
use DateTime;
extends 'Person';
has 'password' => (
is => 'rw',
isa => 'Str',
);
has 'last_login' => (
is => 'rw',
isa => 'DateTime',
);
# note the shortcut invocant syntax
sub login :Args(self: Str pw) :Returns(Bool) {
return 0 if $_{pw} ne $_{self}->password;
$_{self}->last_login( DateTime->now() );
return 1;
}
DESCRIPTION
This module provides an attributes-based interface for parameter
processing in Perl 5. For the original rationale see
<http://mechanicalrevolution.com/blog/parameter_apocalypse.html>.
The proposed interface is based on three cornerstone propositions:
* Parameters are first-class entities that deserve their own meta
protocol. A common meta protocol may be used by different
implementations (e.g. this library, MooseX::Params::Validate,
MooseX::Method::Sigantures) and allow them to coexist better. It is
also the necessary foundation for more advanced features such as
multimethods and extended role validation.
* Parameters should benefit from the same power and flexibility that
Moose attributes have. This module implements most of this
functionality, including laziness.
* The global variable %_ is used as a placeholder for processed
parameters. It is considered by the author of this module as an
intuitive alternative to manual unpacking of @_ while staying within
the limits of traditional Perl syntax.
USE WITH CARE
This is still an experimental module and is subject to backwards
incompatible changes. It is barely tested and most certainly has serious
lurking bugs, has a lot of room for performance optimizations, and its
error reporting could be vastly improved.
BACKWARDS INCOMPATIBLE CHANGES
Version 0.005 removes the interface based on the "method" keyword, and
retains only the attributes-based interface. Also, $self is no longer
localized inside methods, you must use $_{self} instead.
SIGNATURE SYNTAX
Signatures are declared with the ":Args" attribute. All parsed
parameters are made available inside your subroutine within the special
%_ hash. All elements of %_ are read-only, and an attempt to modify them
will throw an exception. An attempt to use a hash element which is not a
valid parameter name for this subroutine will also throw an exception.
@_ is not affected by the use of signatures, so you can still use it to
manually unpack arguments if you want to.
Parameter names
Parameter names can by any valid perl identifiers, and they are
separated by commas.
sub rank :Args(first, second, third) {
say "$_{first} is first, $_{second} is second, and $_{third} is third";
}
Invocant
Method signatures can specify their invocant as the first parameter,
followed by a colon:
sub rank :Args(self: first, second, third) {
my $competition = $_{self}->competition;
...
}
Type constraints
Moose type constraints may be used for validation.
sub rank :Args(Str first, Str second, Str third) { ... }
An ampersand before a type enables coercion for this type.
subtype 'Name' ...;
coerce 'Name', from 'Str', via { ... };
sub rank :Args(&Name first, &Name second, &Name third) { ... }
Positional and named parameters
Parameters are by default positional.
sub rank :Args(first, second, third) { ... }
# rank('Peter', 'George', 'John')
Named parameters are prefixed by a colon.
sub rank :Args(:first, :second, :third) { ... }
# rank( first => 'Peter', second => 'George', third => 'John')
Named parameters may be passed by one name and accessed by another.
sub rank :Args(:gold(first), :silver(second), :bronze(third)) {
say "$_{first} is first, $_{second} is second, and $_{third} is third";
}
# rank( gold => 'Peter', silver => 'George', bronze => 'John')
Positional and named parameters may be mixed, but positional parameters
must come first.
sub rank :Args(first, :second, :third) {
say "$_{first} is first, $_{second} is second, and $_{third} is third";
}
# rank( 'Peter', second => 'George', third => 'John')
Required parameters
An exclamation mark ("!") after the name denotes a required parameter,
and a question mark ("?") denotes an optional parameter.
sub rank :Args(first!, second?, third?) { ... }
Positional parameters are by default required, and named parameters are
by default optional.
Slurpy parameters
A parameter prefixed by an asterisk ("*") is slurpy, i.e. it consumes
the remainder of the argument list. Slurpy parameters must come last in
the signature.
sub rank :Args(ArrayRef *winners) {
say "$_{winners}[0] is first, $_{winners}[1] is second, and $_{winners}[2] is third";
}
Default values
A parameter may be given a simple default value, which can be either a
quoted string or an unsigned integer.
sub rank :Args(first = 'Peter', second = 'George', third = 'John') { ... }
You may use either single or double quotes to quote a string, but they
will always be interpreted as if single quotes were used.
Builders
Where a default value is not sufficient, parameters may specify builders
instead. A builder is a subroutine whose return value will be used as
default value for the parameter.
sub rank :Args(ArrayRef *winners = calculate_winners) { ... }
sub calculate_winners { ... }
The name of the builder may be optionally followed by a pair of
parenthesis.
sub rank :Args(ArrayRef *winners = calculate_winners()) { ... }
All builders are executed lazily, i.e. the first time the parameter is
accessed. If a parameter name is followed by an equal sign, but neither
a default value nor a builder is specified, it is assumed that the
parameter has a builder named "_build_param_${name}". In this case the
equal sign may also be placed before the name of the parameter.
sub rank :Args(ArrayRef *winners=) { ... }
# is equivalent to
sub rank :Args(ArrayRef =*winners) { ... }
# is equivalent to
sub rank :Args(ArrayRef *winners = _build_param_winners) { ... }
sub _build_param_winners { ... }
Within a parameter builder, you can access all other parameters in the
%_ hash.
sub connect :Args(=:dbh, :host, :port, :database) { ... }
sub _build_param_dbh {
return DBI->connect("dbi:mysql:host=$_{host};port=$_{port};database=$_{database}");
}
BUILDARGS AND CHECKARGS
BuildArgs
The "BuildArgs" attribute allows you to specify a subroutine that will
be used to preprocess your arguments before they are validated against
the supplied signature. It can be used as to create poor man's
multimethods by coercing different types of arguments to a single
signature. It is somewhat similar to what Moose's "BUILDARGS" does for
class constructors.
sub rank
:Args(:first :second :third)
:BuildArgs(_buildargs_rank)
{ ... }
# allow positional parameters as well
sub _buildargs_rank {
if (@_ == 3) {
return first => $_[0], second => $_[1], third => $_[2];
} else {
return @_;
}
}
If "BuildArgs" is specified without a subroutine name,
"_buildargs_${subname}" will be assumed.
sub rank :Args(...) :BuildArgs { ... }
# is equivalent to
sub rank :Args(...) :BuildArgs(_buildargs_rank) { ... }
CheckArgs
The "CheckArgs" attribute allows you to specify a subroutine that will
be used to perform additional validation after the arguments are
validated against the supplied signature. It can be used to perform more
complex validations that cannot be expressed in a simple signature. It
is somewhat similar to what Moose's "BUILD" does for class constructors.
Inside a "CheckArgs" subroutine you can access the processed parameters
in the %_ hash.
sub rank
:Args(:first :second :third)
:CheckArgs(_checkargs_rank)
{ ... }
# make sure names do not repeat
sub _checkargs_rank {
if (
($_{first} eq $_{second}) or
($_{first} eq $_{third} ) or
($_{second} eq $_{third} )
) { die "One player can only take one place!"; }
}
If "CheckArgs" is specified without a subroutine name,
"_checkargs_${subname}" will be assumed.
sub rank :Args(...) :CheckArgs { ... }
# is equivalent to
sub rank :Args(...) :CheckArgs(_checkargs_rank) { ... }
RETURN VALUE VALIDATION
Returns
"MooseX::Params" provids a basic mechanism for return value validation
via the "Returns" attribute.
sub add :Args(a, b) :Returns(Num) { return $_{a} + $_{b} }
my $five = add(2,3);
Any Moose type name may be used as an arbument to "Returns". If your
subroutine returns a list of values, you will need to use the special
parametric types "Array" and "Hash". They behave identically to
"ArrayRef" and "HashRef", except that they work with lists instead of
references:
sub myreverse :Args(*items) :Returns(Array) { return reverse @{ $_{items} } }
my @list = qw(foo bar baz);
my @reversed = myreverse(@list);
Note that "wantarray" inside subroutines that use "Returns" will always
return true (see below).
ReturnsScalar
Return value validation does not play well with context magic. If you
return different values depending on context, validation will break.
Therefore, subroutines that use "Returns" are always evaluated in list
context to obrain their return value. The "ResultScalar" attribute
allows you to explicitly change how your subroutine will behave in
scalar context. It accepts one of four options:
Count (default)
In scalar context return the number of items in the return value
list.
First
In scalar context return the first item in the return value list.
Last
In scalar context return the last item in the return value list.
ArrayRef
In scalar context return a reference to the return value list.
sub results :Returns(Array[MyApp::Object]) :ReturnsScalar(ArrayRef) { ... }
META CLASSES
"MooseX::Params" provides method and parameter metaroles, please see
their sourcecode for details:
* MooseX::Params::Meta::Method
* MooseX::Params::Meta::Parameter
TODO
* return value validation ("Returns" and "ReturnsScalar")
* subroutine traits ("Does")
* better error checking and reporting
* improved performance
* lightweight implementation without meta and magic
Whether or not these features will be implemented depends mostly on the
community response to the proposed API. Currently the best way to
contribute to this module would be to provide feedback and commentary -
the Moose mailing list will be a good place for this.
BUGS
Plenty. Some of the known ones are:
* No checking for surplus arguments
* "foreach my $value (@{$_{arrayref}})" attempts to modify
$_{arrayref} and triggers an exception
* May be incompatible with other modules that provide attributes,
including Perl6::Export::Attrs
* "MooseX::Params::Meta::Method" is a class, should be a role
SEE ALSO
* MooseX::Params::Validate
* MooseX::Method::Signatures
AUTHOR
Peter Shangov <pshangov@yahoo.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Peter Shangov.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.