1MooseX::Params::ValidatUes(e3r)Contributed Perl DocumentMaotoisoenX::Params::Validate(3)
2
6 MooseX::Params::Validate - an extension of Params::Validate using
7 Moose's types
8
10 version 0.21
11
13 package Foo;
14 use Moose;
15 use MooseX::Params::Validate;
16 sub foo {
18 my ( $self, %params ) = validated_hash(
19 \@_,
20 bar => { isa => 'Str', default => 'Moose' },
21 );
22 return "Hooray for $params{bar}!";
23 }
24 sub bar {
26 my $self = shift;
27 my ( $foo, $baz, $gorch ) = validated_list(
28 \@_,
29 foo => { isa => 'Foo' },
30 baz => { isa => 'ArrayRef | HashRef', optional => 1 },
31 gorch => { isa => 'ArrayRef[Int]', optional => 1 }
32 );
33 [ $foo, $baz, $gorch ];
34 }
35
37 This module fills a gap in Moose by adding method parameter validation
38 to Moose. This is just one of many developing options, it should not be
39 considered the "official" one by any means though.
40 You might also want to explore "MooseX::Method::Signatures" and
42 "MooseX::Declare".
43
45 It is not possible to introspect the method parameter specs; they are
46 created as needed when the method is called and cached for subsequent
47 calls.
48
50 validated_hash( \@_, %parameter_spec )
51 This behaves similarly to the standard Params::Validate "validate"
52 function and returns the captured values in a HASH. The one
53 exception is where if it spots an instance in the @_, then it will
54 handle it appropriately (unlike Params::Validate which forces you
55 to shift you $self first).
56 The values in @_ can either be a set of name-value pairs or a
58 single hash reference.
59 The %parameter_spec accepts the following options:
61 isa The "isa" option can be either; class name, Moose type
63 constraint name or an anon Moose type constraint.
64 does
66 The "does" option can be either; role name or an anon Moose
67 type constraint.
68 default
70 This is the default value to be used if the value is not
71 supplied.
72 optional
74 As with Params::Validate, all options are considered required
75 unless otherwise specified. This option is passed directly to
76 Params::Validate.
77 coerce
79 If this is true and the parameter has a type constraint which
80 has coercions, then the coercion will be called for this
81 parameter. If the type does have coercions, then this parameter
82 is ignored.
83 depends
85 Another parameter that this one depends on. See the
86 Params::Validate documentation for more details.
87 This function is also available under its old name, "validate".
89 validated_list( \@_, %parameter_spec )
91 The %parameter_spec accepts the same options as above, but returns
92 the parameters as positional values instead of a HASH. This is best
93 explained by example:
94 sub foo {
96 my ( $self, $foo, $bar ) = validated_list(
97 \@_,
98 foo => { isa => 'Foo' },
99 bar => { isa => 'Bar' },
100 );
101 $foo->baz($bar);
102 }
103 We capture the order in which you defined the parameters and then
105 return them as a list in the same order. If a param is marked
106 optional and not included, then it will be set to "undef".
107 The values in @_ can either be a set of name-value pairs or a
109 single hash reference.
110 Like "validated_hash", if it spots an object instance as the first
112 parameter of @_, it will handle it appropriately, returning it as
113 the first argument.
114 This function is also available under its old name, "validatep".
116 pos_validated_list( \@_, $spec, $spec, ... )
118 This function validates a list of positional parameters. Each $spec
119 should validate one of the parameters in the list:
120 sub foo {
122 my $self = shift;
123 my ( $foo, $bar ) = pos_validated_list(
124 \@_,
125 { isa => 'Foo' },
126 { isa => 'Bar' },
127 );
128 ...
130 }
131 Unlike the other functions, this function cannot find $self in the
133 argument list. Make sure to shift it off yourself before doing
134 validation.
135 The values in @_ must be a list of values. You cannot pass the
137 values as an array reference, because this cannot be distinguished
138 from passing one value which is itself an array reference.
139 If a parameter is marked as optional and is not present, it will
141 simply not be returned.
142 If you want to pass in any of the cache control parameters
144 described below, simply pass them after the list of parameter
145 validation specs:
146 sub foo {
148 my $self = shift;
149 my ( $foo, $bar ) = pos_validated_list(
150 \@_,
151 { isa => 'Foo' },
152 { isa => 'Bar' },
153 MX_PARAMS_VALIDATE_NO_CACHE => 1,
154 );
155 ...
157 }
158
160 If a type constraint check for a parameter fails, then the error is
161 thrown as a
162 MooseX::Params::Validate::Exception::ValidationFailedForTypeConstraint
163 object. When stringified, this object will use the error message
164 generated by the type constraint that failed.
165 Other errors are simply percolated up from Params::Validate as-is, and
167 are not turned into exception objects. This may change in the future
168 (or more likely, Params::Validate may start throwing objects of its
169 own).
170
172 By default, any parameters not mentioned in the parameter spec cause
173 this module to throw an error. However, you can have this module simply
174 ignore them by setting "MX_PARAMS_VALIDATE_ALLOW_EXTRA" to a true value
175 when calling a validation subroutine.
176 When calling "validated_hash" or "pos_validated_list" the extra
178 parameters are simply returned in the hash or list as appropriate.
179 However, when you call "validated_list" the extra parameters will not
180 be returned at all. You can get them by looking at the original value
181 of @_.
182
184 By default, this module exports the "validated_hash", "validated_list",
185 and "pos_validated_list".
186 If you would prefer to import the now deprecated functions "validate"
188 and "validatep" instead, you can use the ":deprecated" tag to import
189 them.
190
192 When a validation subroutine is called the first time, the parameter
193 spec is prepared and cached to avoid unnecessary regeneration. It uses
194 the fully qualified name of the subroutine (package + subname) as the
195 cache key. In 99.999% of the use cases for this module, that will be
196 the right thing to do.
197 However, I have (ab)used this module occasionally to handle dynamic
199 sets of parameters. In this special use case you can do a couple things
200 to better control the caching behavior.
201 • Passing in the "MX_PARAMS_VALIDATE_NO_CACHE" flag in the parameter
203 spec this will prevent the parameter spec from being cached.
204 sub foo {
206 my ( $self, %params ) = validated_hash(
207 \@_,
208 foo => { isa => 'Foo' },
209 MX_PARAMS_VALIDATE_NO_CACHE => 1,
210 );
211 }
213 • Passing in "MX_PARAMS_VALIDATE_CACHE_KEY" with a value to be used
215 as the cache key will bypass the normal cache key generation.
216 sub foo {
218 my ( $self, %params ) = validated_hash(
219 \@_,
220 foo => { isa => 'Foo' },
221 MX_PARAMS_VALIDATE_CACHE_KEY => 'foo-42',
222 );
223 }
225
227 Dave Rolsky <autarch@urth.org>
228
230 Please submit bugs to the CPAN RT system at
231 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=moosex-params-validate
232 or via email at bug-moosex-params-validate@rt.cpan.org.
233
235 • Stevan Little <stevan@cpan.org>
236 • Dave Rolsky <autarch@urth.org>
238
240 • Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
241 • Hans Staugaard <h.staugaard@tweakker.com>
243 • Karen Etheridge <ether@cpan.org>
245
247 This software is copyright (c) 2013 - 2015 by Stevan Little
248 <stevan@cpan.org>.
249 This is free software; you can redistribute it and/or modify it under
251 the same terms as the Perl 5 programming language system itself.
252perl v5.36.0 2023-01-20 MooseX::Params::Validate(3)