1MooseX::Params::ValidatUes(e3r)Contributed Perl DocumentMaotoisoenX::Params::Validate(3)
2
3
4

NAME

6       MooseX::Params::Validate - an extension of Params::Validate using
7       Moose's types
8

VERSION

10       version 0.21
11

SYNOPSIS

13         package Foo;
14         use Moose;
15         use MooseX::Params::Validate;
16
17         sub foo {
18             my ( $self, %params ) = validated_hash(
19                 \@_,
20                 bar => { isa => 'Str', default => 'Moose' },
21             );
22             return "Hooray for $params{bar}!";
23         }
24
25         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

DESCRIPTION

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
41       You might also want to explore "MooseX::Method::Signatures" and
42       "MooseX::Declare".
43

CAVEATS

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

EXPORTS

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
57           The values in @_ can either be a set of name-value pairs or a
58           single hash reference.
59
60           The %parameter_spec accepts the following options:
61
62           isa The "isa" option can be either; class name, Moose type
63               constraint name or an anon Moose type constraint.
64
65           does
66               The "does" option can be either; role name or an anon Moose
67               type constraint.
68
69           default
70               This is the default value to be used if the value is not
71               supplied.
72
73           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
78           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
84           depends
85               Another parameter that this one depends on. See the
86               Params::Validate documentation for more details.
87
88           This function is also available under its old name, "validate".
89
90       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
95             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
104           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
108           The values in @_ can either be a set of name-value pairs or a
109           single hash reference.
110
111           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
115           This function is also available under its old name, "validatep".
116
117       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
121             sub foo {
122                 my $self = shift;
123                 my ( $foo, $bar ) = pos_validated_list(
124                     \@_,
125                     { isa => 'Foo' },
126                     { isa => 'Bar' },
127                 );
128
129                 ...
130             }
131
132           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
136           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
140           If a parameter is marked as optional and is not present, it will
141           simply not be returned.
142
143           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
147             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
156                 ...
157             }
158

EXCEPTION FOR FAILED VALIDATION

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
166       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

ALLOWING EXTRA PARAMETERS

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
177       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

EXPORTS

184       By default, this module exports the "validated_hash", "validated_list",
185       and "pos_validated_list".
186
187       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

IMPORTANT NOTE ON CACHING

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
198       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
202       •   Passing in the "MX_PARAMS_VALIDATE_NO_CACHE" flag in the parameter
203           spec this will prevent the parameter spec from being cached.
204
205             sub foo {
206                 my ( $self, %params ) = validated_hash(
207                     \@_,
208                     foo                         => { isa => 'Foo' },
209                     MX_PARAMS_VALIDATE_NO_CACHE => 1,
210                 );
211
212             }
213
214       •   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
217             sub foo {
218                 my ( $self, %params ) = validated_hash(
219                     \@_,
220                     foo                          => { isa => 'Foo' },
221                     MX_PARAMS_VALIDATE_CACHE_KEY => 'foo-42',
222                 );
223
224             }
225

MAINTAINER

227       Dave Rolsky <autarch@urth.org>
228

BUGS

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

AUTHORS

235       •   Stevan Little <stevan@cpan.org>
236
237       •   Dave Rolsky <autarch@urth.org>
238

CONTRIBUTORS

240       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
241
242       •   Hans Staugaard <h.staugaard@tweakker.com>
243
244       •   Karen Etheridge <ether@cpan.org>
245
247       This software is copyright (c) 2013 - 2015 by Stevan Little
248       <stevan@cpan.org>.
249
250       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.
252
253
254
255perl v5.36.0                      2023-01-20       MooseX::Params::Validate(3)
Impressum