1Params::ValidationCompiUlseerr(3C)ontributed Perl DocumePnatraatmiso:n:ValidationCompiler(3)
2
6 Params::ValidationCompiler - Build an optimized subroutine parameter
7 validator once, use it forever
8
10 version 0.31
11
13 use Types::Standard qw( Int Str );
14 use Params::ValidationCompiler qw( validation_for );
15 {
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 sub foo {
32 my %args = $validator->(@_);
33 }
34 }
35 {
37 my $validator = validation_for(
38 params => [
39 { type => Int },
40 {
41 type => Str,
42 optional => 1,
43 },
44 ],
45 );
46 sub bar {
48 my ( $int, $str ) = $validator->(@_);
49 }
50 }
51 {
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 sub baz {
65 my ( $foo, $bar ) = $validator->(@_);
66 }
67 }
68
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 In addition to type checks, it also supports parameter defaults,
75 optional parameters, and extra "slurpy" parameters.
76
78 This module has two options exports, "validation_for" and "source_for".
79 Both of these subs accept the same options:
80 params
82 An arrayref or hashref containing a parameter specification.
83 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 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 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 Each spec can contain either a boolean or hashref. If the spec is a
98 boolean, this indicates required (true) or optional (false).
99 The spec hashref accepts the following keys:
101 • type
103 A type object. This can be a Moose type (from Moose or
105 MooseX::Types), a Type::Tiny type, or a Specio type.
106 If the type has coercions, those will always be used.
108 • default
110 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 • optional
116 A boolean indicating whether or not the parameter is optional. By
118 default, parameters are required unless you provide a default.
119 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 You can also pass a type constraint here, in which case all extra
126 arguments must be values of the specified type.
127 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 You cannot combine "slurpy" with "named_to_list" as there is no way to
136 know how to order the extra return values.
137 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 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 If you have Class::XSAccessor installed then this will be used to
149 create the class's methods, which makes it fairly fast.
150 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 When "return_object" is true, the parameter spec hashref also accepts
156 to the following additional keys:
157 • getter
159 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 • predicate
167 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
175 The exported subs are:
176 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 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 For now, you must shift off the invocant yourself.
190 This subroutine accepts the following additional parameters:
192 • name
194 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 This name will also be used in some exception messages, even if
201 Sub::Util is not available.
202 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 • name_is_optional
208 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 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 • debug
217 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 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
229 Bugs may be submitted at
230 <https://github.com/houseabsolute/Params-ValidationCompiler/issues>.
231
233 The source code repository for Params-ValidationCompiler can be found
234 at <https://github.com/houseabsolute/Params-ValidationCompiler>.
235
237 If you'd like to thank me for the work I've done on this module, please
238 consider making a "donation" to me via PayPal. I spend a lot of free
239 time creating free software, and would appreciate any support you'd
240 care to offer.
241 Please note that I am not suggesting that you must do this in order for
243 me to continue working on this particular software. I will continue to
244 do so, inasmuch as I have in the past, for as long as it interests me.
245 Similarly, a donation made in this way will probably not make me work
247 on this software much more, unless I get so many donations that I can
248 consider working on free software full time (let's all have a chuckle
249 at that together).
250 To donate, log into PayPal and send money to autarch@urth.org, or use
252 the button at <https://houseabsolute.com/foss-donations/>.
253
255 Dave Rolsky <autarch@urth.org>
256
258 • Gregory Oschwald <goschwald@maxmind.com>
259 • Gregory Oschwald <oschwald@gmail.com>
261 • Tomasz Konojacki <me@xenu.pl>
263
265 This software is Copyright (c) 2016 - 2023 by Dave Rolsky.
266 This is free software, licensed under:
268 The Artistic License 2.0 (GPL Compatible)
270 The full text of the license can be found in the LICENSE file included
272 with this distribution.
273perl v5.36.0 2023-01-20 Params::ValidationCompiler(3)