libtype-tiny-perl 1.002001-1 / usr / share / perl5 / Type / Tiny / Manual / Params.pod

=pod

=encoding utf-8

=head1 NAME

Type::Tiny::Manual::Params - coerce and validate arguments to functions and methods

=head1 DESCRIPTION

There is a module called L<Type::Params> available to wrap up type coercion
and constraint checks into a single, simple and fast check. If you care
about speed, and your sub signatures are fairly simple, then this is the way
to go...

   use feature qw( state );
   use Types::Standard qw( Str );
   use Type::Utils;
   use Type::Params qw( compile );
   
   my $Invocant = class_type { class => __PACKAGE__ };
   
   sub set_name
   {
      state $check = compile($Invocant, Str);
      my ($self, $name) = $check->(@_);
      
      ...;
   }

See the COOKBOOK section of L<Type::Params> for further information.

=head2 The Somewhat More Manual Way...

In general, Type::Params should be sufficient to cover most needs, and
will probably run faster than almost anything you could cook up yourself.
However, sometimes you need to deal with unusual function signatures that
it does not support. For example, imagine function C<< format_string >>
takes an optional hashref of formatting instructions, followed by a
required string. You might expect to be able to handle it like this:

   sub format_string
   {
      state $check = compile(Optional[HashRef], Str);
      my ($instructions, $string) = $check->(@_);
      
      ...;
   }

However, this won't work, as Type::Params expects required parameters to
always precede optional ones. So there are times you need to handle
parameters more manually.

In these cases, bear in mind that for any type constraint object you
have several useful checking methods available:

  Str->check($var)            # returns a boolean
  is_Str($var)                # ditto
  Str->($var)                 # returns $var or dies
  assert_Str($var)            # ditto

Here's how you might handle the C<format_string> function:

   sub format_string
   {
      my $instructions;
      $instructions = shift if HashRef->check($_[0]);
      
      my $string = Str->(shift);
      
      ...;
   }

Alternatively, you could manipulate @_ before passing it to the compiled
check:

   sub format_string
   {
      state $check = compile(HashRef, Str);
      my ($instructions, $str) = $check->(@_==1 ? ({}, @_) : @_);
      
      ...;
   }

=head2 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
L<Type::Tiny>...

=head3 Kavorka

L<Kavorka> is a sub signatures implementation written to natively use
L<Type::Utils>' C<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 L<Moops>, a larger framework for
object oriented programming in Perl.

=head3 Function::Parameters

The following should work with L<Function::Parameters> 1.0201 or above:

   use Type::Utils;
   use Function::Parameters {
      method => {
         strict     => 1,
         reify_type => sub { Type::Utils::dwim_type($_[0]) },
      },
   };
   
   method set_name (Str $name)
   {
      $self->{name} = $name;
   }

Note that by default, Function::Parameters uses Moose's type
constraints. The C<reify_type> option above (introduced in
Function::Parameters 1.0201) allows you to "divert" type constraint
lookups. Using Type::Tiny constraints will gain you about a 7%
speed-up in function signature checks.

An alternative way to use Function::Parameter with Type::Tiny is to
provide type constraint expressions in parentheses:

   use Types::Standard;
   use Function::Parameters ':strict';
   
   method set_name ((Str) $name)
   {
      $self->{name} = $name;
   }

=head3 Attribute::Contract

Both Kavorka and Function::Parameters require a relatively recent
version of Perl. L<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.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENCE

This software is copyright (c) 2013-2014, 2017 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.

=head1 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.

=cut