1Params::ValidationCompiUlseerr(3C)ontributed Perl DocumePnatraatmiso:n:ValidationCompiler(3)
2
3
4

NAME

6       Params::ValidationCompiler - Build an optimized subroutine parameter
7       validator once, use it forever
8

VERSION

10       version 0.30
11

SYNOPSIS

13           use Types::Standard qw( Int Str );
14           use Params::ValidationCompiler qw( validation_for );
15
16           {
17               my $validator = validation_for(
18                   params => {
19                       foo => { type => Int },
20                       bar => {
21                           type     => Str,
22                           optional => 1,
23                       },
24                       baz => {
25                           type    => Int,
26                           default => 42,
27                       },
28                   },
29               );
30
31               sub foo {
32                   my %args = $validator->(@_);
33               }
34           }
35
36           {
37               my $validator = validation_for(
38                   params => [
39                       { type => Int },
40                       {
41                           type     => Str,
42                           optional => 1,
43                       },
44                   ],
45               );
46
47               sub bar {
48                   my ( $int, $str ) = $validator->(@_);
49               }
50           }
51
52           {
53               my $validator = validation_for(
54                   params => [
55                       foo => { type => Int },
56                       bar => {
57                           type     => Str,
58                           optional => 1,
59                       },
60                   ],
61                   named_to_list => 1,
62               );
63
64               sub baz {
65                   my ( $foo, $bar ) = $validator->(@_);
66               }
67           }
68

DESCRIPTION

70       This module creates a customized, highly efficient parameter checking
71       subroutine. It can handle named or positional parameters, and can
72       return the parameters as key/value pairs or a list of values.
73
74       In addition to type checks, it also supports parameter defaults,
75       optional parameters, and extra "slurpy" parameters.
76

PARAMETERS

78       This module has two options exports, "validation_for" and "source_for".
79       Both of these subs accept the same options:
80
81   params
82       An arrayref or hashref containing a parameter specification.
83
84       If you pass a hashref then the generated validator sub will expect
85       named parameters. The "params" value should be a hashref where the
86       parameter names are keys and the specs are the values.
87
88       If you pass an arrayref and "named_to_list" is false, the validator
89       will expect positional params. Each element of the "params" arrayref
90       should be a parameter spec.
91
92       If you pass an arrayref and "named_to_list" is true, the validator will
93       expect named params, but will return a list of values. In this case the
94       arrayref should contain a list of key/value pairs, where parameter
95       names are the keys and the specs are the values.
96
97       Each spec can contain either a boolean or hashref. If the spec is a
98       boolean, this indicates required (true) or optional (false).
99
100       The spec hashref accepts the following keys:
101
102       ·   type
103
104           A type object. This can be a Moose type (from Moose or
105           MooseX::Types), a Type::Tiny type, or a Specio type.
106
107           If the type has coercions, those will always be used.
108
109       ·   default
110
111           This can either be a simple (non-reference) scalar or a subroutine
112           reference. The sub ref will be called without any arguments (for
113           now).
114
115       ·   optional
116
117           A boolean indicating whether or not the parameter is optional. By
118           default, parameters are required unless you provide a default.
119
120   slurpy
121       If this is a simple true value, then the generated subroutine accepts
122       additional arguments not specified in "params". By default, extra
123       arguments cause an exception.
124
125       You can also pass a type constraint here, in which case all extra
126       arguments must be values of the specified type.
127
128   named_to_list
129       If this is true, the generated subroutine will expect a list of key-
130       value pairs or a hashref and it will return a list containing only
131       values. The "params" you pass must be a arrayref of key-value pairs.
132       The order of these pairs determines the order in which values are
133       returned.
134
135       You cannot combine "slurpy" with "named_to_list" as there is no way to
136       know how to order the extra return values.
137
138   return_object
139       If this is true, the generated subroutine will return an object instead
140       of a hashref. You cannot set this option to true if you set either or
141       "slurpy" or "named_to_list".
142
143       The object's methods correspond to the parameter names passed to the
144       subroutine. While calling methods on an object is slower than accessing
145       a hashref, the advantage is that if you typo a parameter name you'll
146       get a helpful error.
147
148       If you have Class::XSAccessor installed then this will be used to
149       create the class's methods, which makes it fairly fast.
150
151       The returned object is in a generated class. Do not rely on this class
152       name being anything in specific, and don't check this object using
153       "isa", "DOES", or anything similar.
154
155       When "return_object" is true, the parameter spec hashref also accepts
156       to the following additional keys:
157
158       ·   getter
159
160           Use this to set an explicit getter method name for the parameter.
161           By default the method name will be the same as the parameter name.
162           Note that if the parameter name is not a valid sub name, then you
163           will get an error compiling the validation sub unless you specify a
164           getter for the parameter.
165
166       ·   predicate
167
168           Use this to ask for a predicate method to be created for this
169           parameter. The predicate method returns true if the parameter was
170           passed and false if it wasn't. Note that this is only useful for
171           optional parameters, but you can ask for a predicate for any
172           parameter.
173

EXPORTS

175       The exported subs are:
176
177   validation_for(...)
178       This returns a subroutine that implements the specific parameter
179       checking. This subroutine expects to be given the parameters to
180       validate in @_. If all the parameters are valid, it will return the
181       validated parameters (with defaults as appropriate), either as a list
182       of key-value pairs or as a list of just values. If any of the
183       parameters are invalid it will throw an exception.
184
185       For validators expected named params, the generated subroutine accepts
186       either a list of key-value pairs or a single hashref. Otherwise the
187       validator expects a list of values.
188
189       For now, you must shift off the invocant yourself.
190
191       This subroutine accepts the following additional parameters:
192
193       ·   name
194
195           If this is given, then the generated subroutine will be named using
196           Sub::Util. This is strongly recommended as it makes it possible to
197           distinguish different check subroutines when profiling or in stack
198           traces.
199
200           This name will also be used in some exception messages, even if
201           Sub::Util is not available.
202
203           Note that you must install Sub::Util yourself separately, as it is
204           not required by this distribution, in order to avoid requiring a
205           compiler.
206
207       ·   name_is_optional
208
209           If this is true, then the name is ignored when "Sub::Util" is not
210           installed. If this is false, then passing a name when Sub::Util
211           cannot be loaded causes an exception.
212
213           This is useful for CPAN modules where you want to set a name if you
214           can, but you do not want to add a prerequisite on Sub::Util.
215
216       ·   debug
217
218           Sets the "EVAL_CLOSURE_PRINT_SOURCE" environment variable to true
219           before calling "Eval::Closure::eval_closure()". This causes the
220           source of the subroutine to be printed before it's "eval"'d.
221
222   source_for(...)
223       This returns a two element list. The first is a string containing the
224       source code for the generated sub. The second is a hashref of
225       "environment" variables to be used when generating the subroutine.
226       These are the arguments that are passed to Eval::Closure.
227

SUPPORT

229       Bugs may be submitted at
230       <https://github.com/houseabsolute/Params-ValidationCompiler/issues>.
231
232       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
233

SOURCE

235       The source code repository for Params-ValidationCompiler can be found
236       at <https://github.com/houseabsolute/Params-ValidationCompiler>.
237

DONATIONS

239       If you'd like to thank me for the work I've done on this module, please
240       consider making a "donation" to me via PayPal. I spend a lot of free
241       time creating free software, and would appreciate any support you'd
242       care to offer.
243
244       Please note that I am not suggesting that you must do this in order for
245       me to continue working on this particular software. I will continue to
246       do so, inasmuch as I have in the past, for as long as it interests me.
247
248       Similarly, a donation made in this way will probably not make me work
249       on this software much more, unless I get so many donations that I can
250       consider working on free software full time (let's all have a chuckle
251       at that together).
252
253       To donate, log into PayPal and send money to autarch@urth.org, or use
254       the button at <http://www.urth.org/~autarch/fs-donation.html>.
255

AUTHOR

257       Dave Rolsky <autarch@urth.org>
258

CONTRIBUTORS

260       ·   Gregory Oschwald <goschwald@maxmind.com>
261
262       ·   Gregory Oschwald <oschwald@gmail.com>
263
264       ·   Tomasz Konojacki <me@xenu.pl>
265
267       This software is Copyright (c) 2016 - 2018 by Dave Rolsky.
268
269       This is free software, licensed under:
270
271         The Artistic License 2.0 (GPL Compatible)
272
273       The full text of the license can be found in the LICENSE file included
274       with this distribution.
275
276
277
278perl v5.28.0                      2018-07-31     Params::ValidationCompiler(3)
Impressum