.\" 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 "Params::ValidationCompiler 3"
.TH Params::ValidationCompiler 3 "2018-07-31" "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"
Params::ValidationCompiler \- Build an optimized subroutine parameter validator once, use it forever
.SH "VERSION"
.IX Header "VERSION"
version 0.30
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Types::Standard qw( Int Str );
\& use Params::ValidationCompiler qw( validation_for );
\&
\& {
\& my $validator = validation_for(
\& params => {
\& foo => { type => Int },
\& bar => {
\& type => Str,
\& optional => 1,
\& },
\& baz => {
\& type => Int,
\& default => 42,
\& },
\& },
\& );
\&
\& sub foo {
\& my %args = $validator\->(@_);
\& }
\& }
\&
\& {
\& my $validator = validation_for(
\& params => [
\& { type => Int },
\& {
\& type => Str,
\& optional => 1,
\& },
\& ],
\& );
\&
\& sub bar {
\& my ( $int, $str ) = $validator\->(@_);
\& }
\& }
\&
\& {
\& my $validator = validation_for(
\& params => [
\& foo => { type => Int },
\& bar => {
\& type => Str,
\& optional => 1,
\& },
\& ],
\& named_to_list => 1,
\& );
\&
\& sub baz {
\& my ( $foo, $bar ) = $validator\->(@_);
\& }
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module creates a customized, highly efficient parameter checking
subroutine. It can handle named or positional parameters, and can return the
parameters as key/value pairs or a list of values.
.PP
In addition to type checks, it also supports parameter defaults, optional
parameters, and extra \*(L"slurpy\*(R" parameters.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
This module has two options exports, \f(CW\*(C`validation_for\*(C'\fR and \f(CW\*(C`source_for\*(C'\fR. Both
of these subs accept the same options:
.SS "params"
.IX Subsection "params"
An arrayref or hashref containing a parameter specification.
.PP
If you pass a hashref then the generated validator sub will expect named
parameters. The \f(CW\*(C`params\*(C'\fR value should be a hashref where the parameter names
are keys and the specs are the values.
.PP
If you pass an arrayref and \f(CW\*(C`named_to_list\*(C'\fR is false, the validator will
expect positional params. Each element of the \f(CW\*(C`params\*(C'\fR arrayref should be a
parameter spec.
.PP
If you pass an arrayref and \f(CW\*(C`named_to_list\*(C'\fR is true, the validator will
expect named params, but will return a list of values. In this case the
arrayref should contain a \fIlist\fR of key/value pairs, where parameter names
are the keys and the specs are the values.
.PP
Each spec can contain either a boolean or hashref. If the spec is a boolean,
this indicates required (true) or optional (false).
.PP
The spec hashref accepts the following keys:
.IP "\(bu" 4
type
.Sp
A type object. This can be a Moose type (from Moose or
MooseX::Types), a Type::Tiny type, or a Specio type.
.Sp
If the type has coercions, those will always be used.
.IP "\(bu" 4
default
.Sp
This can either be a simple (non-reference) scalar or a subroutine
reference. The sub ref will be called without any arguments (for now).
.IP "\(bu" 4
optional
.Sp
A boolean indicating whether or not the parameter is optional. By default,
parameters are required unless you provide a default.
.SS "slurpy"
.IX Subsection "slurpy"
If this is a simple true value, then the generated subroutine accepts
additional arguments not specified in \f(CW\*(C`params\*(C'\fR. By default, extra arguments
cause an exception.
.PP
You can also pass a type constraint here, in which case all extra arguments
must be values of the specified type.
.SS "named_to_list"
.IX Subsection "named_to_list"
If this is true, the generated subroutine will expect a list of key-value
pairs or a hashref and it will return a list containing only values. The
\&\f(CW\*(C`params\*(C'\fR you pass must be a arrayref of key-value pairs. The order of these
pairs determines the order in which values are returned.
.PP
You cannot combine \f(CW\*(C`slurpy\*(C'\fR with \f(CW\*(C`named_to_list\*(C'\fR as there is no way to know
how to order the extra return values.
.SS "return_object"
.IX Subsection "return_object"
If this is true, the generated subroutine will return an object instead of a
hashref. You cannot set this option to true if you set either or \f(CW\*(C`slurpy\*(C'\fR or
\&\f(CW\*(C`named_to_list\*(C'\fR.
.PP
The object's methods correspond to the parameter names passed to the
subroutine. While calling methods on an object is slower than accessing a
hashref, the advantage is that if you typo a parameter name you'll get a
helpful error.
.PP
If you have Class::XSAccessor installed then this will be used to create
the class's methods, which makes it fairly fast.
.PP
The returned object is in a generated class. Do not rely on this class name
being anything in specific, and don't check this object using \f(CW\*(C`isa\*(C'\fR, \f(CW\*(C`DOES\*(C'\fR,
or anything similar.
.PP
When \f(CW\*(C`return_object\*(C'\fR is true, the parameter spec hashref also accepts to the
following additional keys:
.IP "\(bu" 4
getter
.Sp
Use this to set an explicit getter method name for the parameter. By default
the method name will be the same as the parameter name. Note that if the
parameter name is not a valid sub name, then you will get an error compiling
the validation sub unless you specify a getter for the parameter.
.IP "\(bu" 4
predicate
.Sp
Use this to ask for a predicate method to be created for this parameter. The
predicate method returns true if the parameter was passed and false if it
wasn't. Note that this is only useful for optional parameters, but you can ask
for a predicate for any parameter.
.SH "EXPORTS"
.IX Header "EXPORTS"
The exported subs are:
.SS "validation_for(...)"
.IX Subsection "validation_for(...)"
This returns a subroutine that implements the specific parameter
checking. This subroutine expects to be given the parameters to validate in
\&\f(CW@_\fR. If all the parameters are valid, it will return the validated
parameters (with defaults as appropriate), either as a list of key-value pairs
or as a list of just values. If any of the parameters are invalid it will
throw an exception.
.PP
For validators expected named params, the generated subroutine accepts either
a list of key-value pairs or a single hashref. Otherwise the validator expects
a list of values.
.PP
For now, you must shift off the invocant yourself.
.PP
This subroutine accepts the following additional parameters:
.IP "\(bu" 4
name
.Sp
If this is given, then the generated subroutine will be named using
Sub::Util. This is strongly recommended as it makes it possible to
distinguish different check subroutines when profiling or in stack traces.
.Sp
This name will also be used in some exception messages, even if Sub::Util
is not available.
.Sp
Note that you must install Sub::Util yourself separately, as it is not
required by this distribution, in order to avoid requiring a compiler.
.IP "\(bu" 4
name_is_optional
.Sp
If this is true, then the name is ignored when \f(CW\*(C`Sub::Util\*(C'\fR is not
installed. If this is false, then passing a name when Sub::Util cannot be
loaded causes an exception.
.Sp
This is useful for \s-1CPAN\s0 modules where you want to set a name if you can, but
you do not want to add a prerequisite on Sub::Util.
.IP "\(bu" 4
debug
.Sp
Sets the \f(CW\*(C`EVAL_CLOSURE_PRINT_SOURCE\*(C'\fR environment variable to true before
calling \f(CW\*(C`Eval::Closure::eval_closure()\*(C'\fR. This causes the source of the
subroutine to be printed before it's \f(CW\*(C`eval\*(C'\fR'd.
.SS "source_for(...)"
.IX Subsection "source_for(...)"
This returns a two element list. The first is a string containing the source
code for the generated sub. The second is a hashref of \*(L"environment\*(R" variables
to be used when generating the subroutine. These are the arguments that are
passed to Eval::Closure.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/Params\-ValidationCompiler/issues>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Params-ValidationCompiler can be found at <https://github.com/houseabsolute/Params\-ValidationCompiler>.
.SH "DONATIONS"
.IX Header "DONATIONS"
If you'd like to thank me for the work I've done on this module, please
consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of free time
creating free software, and would appreciate any support you'd care to offer.
.PP
Please note that \fBI am not suggesting that you must do this\fR in order for me
to continue working on this particular software. I will continue to do so,
inasmuch as I have in the past, for as long as it interests me.
.PP
Similarly, a donation made in this way will probably not make me work on this
software much more, unless I get so many donations that I can consider working
on free software full time (let's all have a chuckle at that together).
.PP
To donate, log into PayPal and send money to autarch@urth.org, or use the
button at <http://www.urth.org/~autarch/fs\-donation.html>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Gregory Oschwald <goschwald@maxmind.com>
.IP "\(bu" 4
Gregory Oschwald <oschwald@gmail.com>
.IP "\(bu" 4
Tomasz Konojacki <me@xenu.pl>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2016 \- 2018 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\& The Artistic License 2.0 (GPL Compatible)
.Ve
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.