Current File : /home/opti/perl/usr/man/man3/Type::Tiny::Manual::Params.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Type::Tiny::Manual::Params 3"
.TH Type::Tiny::Manual::Params 3 "2018-07-29" "perl v5.16.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 \- coerce and validate arguments to functions and methods
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
There is a module called 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...
.PP
.Vb 4
\& 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\->(@_);
\&
\& ...;
\& }
.Ve
.PP
See the \s-1COOKBOOK\s0 section of Type::Params for further information.
.SS "The Somewhat More Manual Way..."
.IX Subsection "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 \f(CW\*(C`format_string\*(C'\fR
takes an optional hashref of formatting instructions, followed by a
required string. You might expect to be able to handle it like this:
.PP
.Vb 4
\& sub format_string
\& {
\& state $check = compile(Optional[HashRef], Str);
\& my ($instructions, $string) = $check\->(@_);
\&
\& ...;
\& }
.Ve
.PP
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.
.PP
In these cases, bear in mind that for any type constraint object you
have several useful checking methods available:
.PP
.Vb 4
\& Str\->check($var) # returns a boolean
\& is_Str($var) # ditto
\& Str\->($var) # returns $var or dies
\& assert_Str($var) # ditto
.Ve
.PP
Here's how you might handle the \f(CW\*(C`format_string\*(C'\fR function:
.PP
.Vb 4
\& sub format_string
\& {
\& my $instructions;
\& $instructions = shift if HashRef\->check($_[0]);
\&
\& my $string = Str\->(shift);
\&
\& ...;
\& }
.Ve
.PP
Alternatively, you could manipulate \f(CW@_\fR before passing it to the compiled
check:
.PP
.Vb 4
\& sub format_string
\& {
\& state $check = compile(HashRef, Str);
\& my ($instructions, $str) = $check\->(@_==1 ? ({}, @_) : @_);
\&
\& ...;
\& }
.Ve
.SS "Signatures"
.IX Subsection "Signatures"
Don't you wish your subs could look like this?
.PP
.Vb 4
\& 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
\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 4
\& 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
The following should work with Function::Parameters 1.0201 or above:
.PP
.Vb 7
\& 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;
\& }
.Ve
.PP
Note that by default, Function::Parameters uses Moose's type
constraints. The \f(CW\*(C`reify_type\*(C'\fR option above (introduced in
Function::Parameters 1.0201) allows you to \*(L"divert\*(R" type constraint
lookups. Using Type::Tiny constraints will gain you about a 7%
speed-up in function signature checks.
.PP
An alternative way to use Function::Parameter with Type::Tiny is to
provide type constraint expressions in parentheses:
.PP
.Vb 2
\& use Types::Standard;
\& use Function::Parameters \*(Aq:strict\*(Aq;
\&
\& 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.
.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\-2018 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
Mini Shell