.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Type::Tiny::Manual::Params 3"
.TH Type::Tiny::Manual::Params 3 "2021-07-31" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Type::Tiny::Manual::Params \- advanced information on Type::Params
.SH "MANUAL"
.IX Header "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.
.ie n .SS """validate"" and ""validate_named"""
.el .SS "\f(CWvalidate\fP and \f(CWvalidate_named\fP"
.IX Subsection "validate and validate_named"
The generally recommended way of using Type::Params is this:
.PP
.Vb 4
\&  sub mysub {
\&    state $check = compile( SIGNATURE );
\&    my @args = $check\->( @_ );
\&  }
.Ve
.PP
But it is possible to do it in one call:
.PP
.Vb 3
\&  sub mysub {
\&    my @args = validate( \e@_, SIGNATURE );
\&  }
.Ve
.PP
There is also a \f(CW\*(C`validate_named\*(C'\fR function which acts as a counterpart for
\&\f(CW\*(C`compile_named\*(C'\fR.
.PP
This will generally be slower and less efficient than using \f(CW\*(C`compile\*(C'\fR first
because Type::Tiny can do a lot of optimizations in that first stage to make
the second stage a lot faster. (And the results of \f(CW\*(C`compile\*(C'\fR get stored in
the \f(CW\*(C`state\*(C'\fR variable so that only has to happen once.)
.PP
There is rarely a reason to use \f(CW\*(C`validate\*(C'\fR and \f(CW\*(C`validate_named\*(C'\fR, but
they exist if you want them.
.ie n .SS """multisig"""
.el .SS "\f(CWmultisig\fP"
.IX Subsection "multisig"
Multisig allows you to allow multiple ways of calling a sub.
.PP
.Vb 12
\& sub repeat_string {
\&   state $check = multisig(
\&     compile(
\&       Int,
\&       Str,
\&     ),
\&     compile_named(
\&       { named_to_list => 1 },
\&       count  => Int,
\&       string => Str,
\&     ),
\&   );
\&   
\&   my ($count, $string) = $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
.Ve
.PP
It combines multiple checks and tries each until one works.
.ie n .SS """wrap_subs"" and ""wrap_methods"""
.el .SS "\f(CWwrap_subs\fP and \f(CWwrap_methods\fP"
.IX Subsection "wrap_subs and wrap_methods"
\&\f(CW\*(C`wrap_subs\*(C'\fR turns the \f(CW\*(C`compile\*(C'\fR idea inside out.
.PP
Instead of this:
.PP
.Vb 5
\& sub foobar {
\&   state $check = compile(Int, Str);
\&   my ($foo, $bar) = @_;
\&   ...;
\& }
.Ve
.PP
You do this:
.PP
.Vb 5
\& sub foobar {
\&   my ($foo, $bar) = @_;
\&   ...;
\& }
\& wrap_subs foobar => [ Int, Str ];
.Ve
.PP
Or this:
.PP
.Vb 5
\& sub foobar {
\&   my ($foo, $bar) = @_;
\&   ...;
\& }
\& wrap_subs foobar => compile( Int, Str );
.Ve
.SS "Mixed Named and Positional Parameters"
.IX Subsection "Mixed Named and Positional Parameters"
This can be faked using positional parameters and a slurpy dictionary.
.PP
.Vb 8
\& state $check = compile(
\&   Int,
\&   slurpy Dict[
\&     foo => Int,
\&     bar => Optional[Int],
\&     baz => Optional[Int],
\&   ],
\& );
\& 
\& @_ = (42, foo => 21);                 # ok
\& @_ = (42, foo => 21, bar  => 84);     # ok
\& @_ = (42, foo => 21, bar  => 10.5);   # not ok
\& @_ = (42, foo => 21, quux => 84);     # not ok
.Ve
.PP
From Type::Params 1.009_002, \f(CW\*(C`head\*(C'\fR and \f(CW\*(C`tail\*(C'\fR options are accepted, which
provide another option for mixed named and positional arguments:
.PP
.Vb 7
\& state $check = compile_named(
\&   { head => [ Int ] },
\&   foo => Int,
\&   bar => Optional[Int],
\&   baz => Optional[Int],
\&   ],
\& );
.Ve
.PP
The \f(CW\*(C`head\*(C'\fR is shifted off \f(CW@_\fR before \f(CW@_\fR is considered as a hash.
The \f(CW\*(C`tail\*(C'\fR is popped off \f(CW@_\fR before \f(CW@_\fR is considered as a hash.
.SS "Proper Signatures"
.IX Subsection "Proper Signatures"
Don't you wish your subs could look like this?
.PP
.Vb 3
\&  sub set_name (Object $self, Str $name) {
\&    $self\->{name} = $name;
\&  }
.Ve
.PP
Well; here are a few solutions for sub signatures that work with
Type::Tiny...
.PP
\fIZydeco\fR
.IX Subsection "Zydeco"
.PP
Zydeco is a Perl \s-1OO\s0 syntax toolkit with Type::Tiny support baked in
throughout.
.PP
.Vb 2
\&  package MyApp {
\&    use Zydeco;
\&    
\&    class Person {
\&      has name ( type => Str );
\&      
\&      method rename (Str $new_name) {
\&        printf("%s will now be called %s\en", $self\->name, $new_name);
\&        $self\->name($new_name);
\&      }
\&      
\&      coerce from Str via {
\&        $class\->new(name => $_)
\&      }
\&    }
\&    
\&    class Company {
\&      has owner ( type => \*(AqPerson\*(Aq );
\&    }
\&  }
\&  
\&  my $acme = MyApp\->new_company(owner => "Robert");
\&  $acme\->owner\->rename("Bob");
.Ve
.PP
\fIKavorka\fR
.IX Subsection "Kavorka"
.PP
Kavorka is a sub signatures implementation written to natively use
Type::Utils' \f(CW\*(C`dwim_type\*(C'\fR for type constraints, and take advantage
of Type::Tiny's features such as inlining, and coercions.
.PP
.Vb 3
\&  method set_name (Str $name) {
\&    $self\->{name} = $name;
\&  }
.Ve
.PP
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.)
.PP
Kavorka also includes support for type checking of the returned value.
.PP
Kavorka can also be used as part of Moops, a larger framework for
object oriented programming in Perl.
.PP
\fIFunction::Parameters\fR
.IX Subsection "Function::Parameters"
.PP
Function::Parameters offers support for Type::Tiny and MooseX::Types.
.PP
.Vb 2
\&  use Types::Standard qw( Str );
\&  use Function::Parameters;
\&  
\&  method set_name (Str $name) {
\&      $self\->{name} = $name;
\&  }
.Ve
.PP
\fIAttribute::Contract\fR
.IX Subsection "Attribute::Contract"
.PP
Both Kavorka and Function::Parameters require a relatively recent
version of Perl. Attribute::Contract supports older versions by
using a lot less magic.
.PP
You want Attribute::Contract 0.03 or above.
.PP
.Vb 1
\&  use Attribute::Contract \-types => [qw/Object Str/];
\&  
\&  sub set_name :ContractRequires(Object, Str) {
\&      my ($self, $name) = @_;
\&      $self\->{name} = $name;
\&  }
.Ve
.PP
Attribute::Contract also includes support for type checking of the
returned value.
.SS "Type::Params versus X"
.IX Subsection "Type::Params versus X"
\fIParams::Validate\fR
.IX Subsection "Params::Validate"
.PP
Type::Params is not really a drop-in replacement for Params::Validate;
the \s-1API\s0 differs far too much to claim that. Yet it performs a similar task,
so it makes sense to compare them.
.IP "\(bu" 4
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.
.IP "\(bu" 4
Params::Validate doesn't appear to have a particularly natural way of
validating a mix of positional and named parameters.
.IP "\(bu" 4
Type::Utils allows you to coerce parameters. For example, if you expect
a Path::Tiny object, you could coerce it from a string.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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 \f(CW\*(C`ArrayRef[Int]\*(C'\fR (an arrayref of integers), while the closest from
Params::Validate is \f(CW\*(C`ARRAYREF\*(C'\fR, which you'd need to supplement with
additional callbacks if you wanted to check that the arrayref contained
integers.
.Sp
Whatsmore, Type::Params doesn't just work with Types::Standard, but also
any other Type::Tiny type constraints.
.PP
\fIParams::ValidationCompiler\fR
.IX Subsection "Params::ValidationCompiler"
.PP
Params::ValidationCompiler does basically the same thing as
Type::Params.
.IP "\(bu" 4
Params::ValidationCompiler and Type::Params are likely to perform fairly
similarly. In most cases, recent versions of Type::Params seem to be
\&\fIslightly\fR 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.
.IP "\(bu" 4
Type::Params's syntax is more compact:
.Sp
.Vb 1
\&   state $check = compile(Object, Optional[Int], slurpy ArrayRef);
.Ve
.Sp
Versus:
.Sp
.Vb 7
\&   state $check = validation_for(
\&      params => [
\&         { type => Object },
\&         { type => Int,      optional => 1 },
\&         { type => ArrayRef, slurpy => 1 },
\&      ],
\&   );
.Ve
.IP "\(bu" 4
Params::ValidationCompiler probably has slightly better exceptions.
.SH "NEXT STEPS"
.IX Header "NEXT STEPS"
Here's your next step:
.IP "\(bu" 4
Type::Tiny::Manual::NonOO
.Sp
Type::Tiny in non-object-oriented code.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013\-2014, 2017\-2021 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0