plucky (3) Type::Tiny::Manual::Params.3pm.gz
NAME
Type::Tiny::Manual::Params - advanced information on Type::Params
MANUAL
To get started with Type::Params, please read Type::Tiny::Manual::UsingWithMoo which will cover a lot of
the basics, even if you're not using Moo.
"multiple"
The "multiple" option allows you to specify multiple ways of calling a sub.
sub repeat_string {
state $check = signature(
multiple => [
{ positional => [ Str, Int ] },
{ named => [ string => Str, count => Int ], named_to_list => 1 },
],
);
my ( $string, $count ) = $check->( @_ );
return $string x $count;
}
repeat_string( "Hello", 42 ); # works
repeat_string( string => "Hello", count => 42 ); # works
repeat_string({ string => "Hello", count => 42 }); # works
repeat_string( qr/hiya/ ); # dies
It combines multiple checks and tries each until one works.
"signature_for"
"signature_for" turns "signature" inside out.
Instead of this:
sub foobar {
state $check = signature( positional => [ Int, Str ] );
my ( $foo, $bar ) = $check->( @_ );
...;
}
You do this:
signature_for foobar => (
positional => [ Int, Str ],
);
sub foobar {
my ( $foo, $bar ) = @_;
...;
}
Or in Perl 5.20+, you can even do this:
signature_for foobar => (
positional => [ Int, Str ],
);
sub foobar ( $foo, $bar ) {
...;
}
Functions versus Methods
For subs which are intended to be called as functions:
signature( method => 0, ... );
signature( ... ); # this is the default anyway
For subs which are intended to be called as methods on a blessed object:
signature( method => Object, ... );
And for subs which are intended to be called as methods on a class:
signature( method => ClassName, ... );
signature( method => Str, ... ); # less readable, but faster check!
The following is also allowed, which indicates that the sub is intended to be called as a method, but you
don't want to do type checks on the invocant:
signature( method => 1, ... );
Mixed Named and Positional Parameters
The "head" and "tail" options allow required positional parameters at the start or end of a named
parameter list:
state $check = signature(
head => [ Int ],
named => [
foo => Int,
bar => Optional[Int],
baz => Optional[Int],
],
);
$check->( 42, foo => 21 ); # ok
$check->( 42, foo => 21, bar => 84 ); # ok
$check->( 42, foo => 21, bar => 10.5 ); # not ok
$check->( 42, foo => 21, quux => 84 ); # not ok
Proper Signatures
Don't you wish your subs could look like this?
sub set_name ( Object $self, Str $name ) {
$self->{name} = $name;
}
Well; here are a few solutions for sub signatures that work with Type::Tiny...
Zydeco
Zydeco is a Perl OO syntax toolkit with Type::Tiny support baked in throughout.
package MyApp {
use Zydeco;
class Person {
has name ( type => Str );
method rename ( Str $new_name ) {
printf( "%s will now be called %s\n", $self->name, $new_name );
$self->name( $new_name );
}
coerce from Str via {
$class->new( name => $_ )
}
}
class Company {
has owner ( type => 'Person' );
}
}
my $acme = MyApp->new_company( owner => "Robert" );
$acme->owner->rename( "Bob" );
Kavorka
Kavorka is a sub signatures implementation written to natively use Type::Utils' "dwim_type" for type
constraints, and take advantage of Type::Tiny's features such as inlining, and coercions.
method set_name ( Str $name ) {
$self->{name} = $name;
}
Kavorka's signatures provide a lot more flexibility, and slightly more speed than Type::Params. (The
speed comes from inlining almost all type checks into the body of the sub being declared.)
Kavorka also includes support for type checking of the returned value.
Kavorka can also be used as part of Moops, a larger framework for object oriented programming in Perl.
Function::Parameters
Function::Parameters offers support for Type::Tiny and MooseX::Types.
use Types::Standard qw( Str );
use Function::Parameters;
method set_name ( Str $name ) {
$self->{name} = $name;
}
Attribute::Contract
Both Kavorka and Function::Parameters require a relatively recent version of Perl. Attribute::Contract
supports older versions by using a lot less magic.
You want Attribute::Contract 0.03 or above.
use Attribute::Contract -types => [qw/Object Str/];
sub set_name :ContractRequires(Object, Str) {
my ($self, $name) = @_;
$self->{name} = $name;
}
Attribute::Contract also includes support for type checking of the returned value.
Type::Params versus X
Params::Validate
Type::Params is not really a drop-in replacement for Params::Validate; the API differs far too much to
claim that. Yet it performs a similar task, so it makes sense to compare them.
• Type::Params will tend to be faster if you've got a sub which is called repeatedly, but may be a
little slower than Params::Validate for subs that are only called a few times. This is because it
does a bunch of work the first time your sub is called to make subsequent calls a lot faster.
• Params::Validate doesn't appear to have a particularly natural way of validating a mix of positional
and named parameters.
• Type::Utils allows you to coerce parameters. For example, if you expect a Path::Tiny object, you
could coerce it from a string.
• If you are primarily writing object-oriented code, using Moose or similar, and you are using
Type::Tiny type constraints for your attributes, then using Type::Params allows you to use the same
constraints for method calls.
• Type::Params comes bundled with Types::Standard, which provides a much richer vocabulary of types
than the type validation constants that come with Params::Validate. For example, Types::Standard
provides constraints like "ArrayRef[Int]" (an arrayref of integers), while the closest from
Params::Validate is "ARRAYREF", which you'd need to supplement with additional callbacks if you
wanted to check that the arrayref contained integers.
Whatsmore, Type::Params doesn't just work with Types::Standard, but also any other Type::Tiny type
constraints.
Params::ValidationCompiler
Params::ValidationCompiler does basically the same thing as Type::Params.
• Params::ValidationCompiler and Type::Params are likely to perform fairly similarly. In most cases,
recent versions of Type::Params seem to be slightly faster, but except in very trivial cases, you're
unlikely to notice the speed difference. Speed probably shouldn't be a factor when choosing between
them.
• Type::Params's syntax is more compact:
state $check = signature(
pos => [
Object,
Optional[Int],
Slurpy[ArrayRef],
],
);
Versus:
state $check = validation_for(
params => [
{ type => Object },
{ type => Int, optional => 1 },
{ type => ArrayRef, slurpy => 1 },
],
);
• Params::ValidationCompiler probably has slightly better exceptions.
NEXT STEPS
Here's your next step:
• Type::Tiny::Manual::NonOO
Type::Tiny in non-object-oriented code.
AUTHOR
Toby Inkster <tobyink@cpan.org>.
COPYRIGHT AND LICENCE
This software is copyright (c) 2013-2014, 2017-2023 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.