1Data::Validate::Type(3)User Contributed Perl DocumentatioDnata::Validate::Type(3)
2
3
4

NAME

6       Data::Validate::Type - Data type validation functions.
7

VERSION

9       Version 1.6.0
10

SYNOPSIS

12               # Call with explicit package name.
13               use Data::Validate::Type;
14               if ( Data::Validate::Type::is_string( 'test' ) )
15               {
16                       # ...
17               }
18
19               # Import specific functions.
20               use Data::Validate::Type qw( is_string );
21               if ( is_string( 'test' ) )
22               {
23                       # ...
24               }
25
26               # Import functions for a given paradigm.
27               use Data::Validate::Type qw( :boolean_tests );
28               if ( is_string( 'test' ) )
29               {
30                       # ...
31               }
32

DESCRIPTION

34       Params::Util is a wonderful module, but suffers from a few drawbacks:
35
36       •   Function names start with an underscore, which is usually used to
37           indicate private functions.
38
39       •   Function names are uppercase, which is usually used to indicate
40           file handles or constants.
41
42       •   Function names don't pass PerlCritic's validation, making them
43           problematic to import.
44
45       •   Functions use by default the convention that collection that
46           collections need to not be empty to be valid (see _ARRAY0/_ARRAY
47           for example), which is counter-intuitive.
48
49       •   In Pure Perl mode, the functions are created via eval, which causes
50           issues for Devel::Cover in taint mode.
51
52       Those drawbacks are purely cosmetic and don't affect the usefulness of
53       the functions, except for the last one. This module used to encapsulate
54       Params::Util, but I had to refactor it out to fix the issues with
55       Devel::Cover.
56
57       Please note that I prefer long function names that are descriptive, to
58       arcane short ones. This increases readability, and the bulk of the
59       typing can be spared with the use of a good IDE like Padre.
60
61       Also, this is work in progress - There is more functions that should be
62       added here, if you need one in particular feel free to contact me.
63

BOOLEAN TEST FUNCTIONS

65       Functions in this group return a boolean to indicate whether the
66       parameters passed match the test(s) specified by the functions or not.
67
68       All the boolean functions can be imported at once in your namespace
69       with the following line:
70
71               use Data::Validate::Type qw( :boolean_tests );
72
73   is_string()
74       Return a boolean indicating if the variable passed is a string.
75
76               my $is_string = Data::Validate::Type::is_string( $variable );
77
78       Note: 0 and '' (empty string) are valid strings.
79
80       Parameters:
81
82       •   allow_empty
83
84           Boolean, default 1. Allow the string to be empty or not.
85
86   is_arrayref()
87       Return a boolean indicating if the variable passed is an arrayref that
88       can be dereferenced into an array.
89
90               my $is_arrayref = Data::Validate::Type::is_arrayref( $variable );
91
92               my $is_arrayref = Data::Validate::Type::is_arrayref(
93                       $variable,
94                       allow_empty => 1,
95                       no_blessing => 0,
96               );
97
98               # Check if the variable is an arrayref of hashrefs.
99               my $is_arrayref = Data::Validate::Type::is_arrayref(
100                       $variable,
101                       allow_empty           => 1,
102                       no_blessing           => 0,
103                       element_validate_type =>
104                               sub
105                               {
106                                       return Data::Validate::Type::is_hashref( $_[0] );
107                               },
108               );
109
110       Parameters:
111
112       •   allow_empty
113
114           Boolean, default 1. Allow the array to be empty or not.
115
116       •   no_blessing
117
118           Boolean, default 0. Require that the variable is not blessed.
119
120       •   element_validate_type
121
122           None by default. Set it to a coderef to validate the elements in
123           the array.  The coderef will be passed the element to validate as
124           first parameter, and it must return a boolean indicating whether
125           the element was valid or not.
126
127   is_hashref()
128       Return a boolean indicating if the variable passed is a hashref that
129       can be dereferenced into a hash.
130
131               my $is_hashref = Data::Validate::Type::is_hashref( $variable );
132
133               my $is_hashref = Data::Validate::Type::is_hashref(
134                       $variable,
135                       allow_empty => 1,
136                       no_blessing => 0,
137               );
138
139       Parameters:
140
141       •   allow_empty
142
143           Boolean, default 1. Allow the array to be empty or not.
144
145       •   no_blessing
146
147           Boolean, default 0. Require that the variable is not blessed.
148
149   is_coderef()
150       Return a boolean indicating if the variable passed is an coderef that
151       can be dereferenced into a block of code.
152
153               my $is_coderef = Data::Validate::Type::is_coderef( $variable );
154
155   is_number()
156       Return a boolean indicating if the variable passed is a number.
157
158               my $is_number = Data::Validate::Type::is_number( $variable );
159               my $is_number = Data::Validate::Type::is_number(
160                       $variable,
161                       positive => 1,
162               );
163               my $is_number = Data::Validate::Type::is_number(
164                       $variable,
165                       strictly_positive => 1,
166               );
167
168       Parameters:
169
170       •   strictly_positive
171
172           Boolean, default 0. Set to 1 to check for a strictly positive
173           number.
174
175       •   positive
176
177           Boolean, default 0. Set to 1 to check for a positive number.
178
179   is_instance()
180       Return a boolean indicating if the variable is an instance of the given
181       class.
182
183       Note that this handles inheritance properly, so it will return true if
184       the variable is an instance of a subclass of the class given.
185
186               my $is_instance = Data::Validate::Type::is_instance(
187                       $variable,
188                       class => $class,
189               );
190
191       Parameters:
192
193       •   class
194
195           Required, the name of the class to check the variable against.
196
197   is_regex()
198       Return a boolean indicating if the variable is a regular expression.
199
200               my $is_regex = Data::Validate::Type::is_regex( $variable );
201

ASSERTION-BASED FUNCTIONS

203       Functions in this group do not return anything, but will die when the
204       parameters passed don't match the test(s) specified by the functions.
205
206       All the assertion test functions can be imported at once in your
207       namespace with the following line:
208
209               use Data::Validate::Type qw( :assertions );
210
211   assert_string()
212       Die unless the variable passed is a string.
213
214               Data::Validate::Type::assert_string( $variable );
215
216       Note: 0 and '' (empty string) are valid strings.
217
218       Parameters:
219
220       •   allow_empty
221
222           Boolean, default 1. Allow the string to be empty or not.
223
224   assert_arrayref()
225       Die unless the variable passed is an arrayref that can be dereferenced
226       into an array.
227
228               Data::Validate::Type::assert_arrayref( $variable );
229
230               Data::Validate::Type::assert_arrayref(
231                       $variable,
232                       allow_empty => 1,
233                       no_blessing => 0,
234               );
235
236               # Require the variable to be an arrayref of hashrefs.
237               Data::Validate::Type::assert_arrayref(
238                       $variable,
239                       allow_empty           => 1,
240                       no_blessing           => 0,
241                       element_validate_type =>
242                               sub
243                               {
244                                       return Data::Validate::Type::is_hashref( $_[0] );
245                               },
246               );
247
248       Parameters:
249
250       •   allow_empty
251
252           Boolean, default 1. Allow the array to be empty or not.
253
254       •   no_blessing
255
256           Boolean, default 0. Require that the variable is not blessed.
257
258       •   element_validate_type
259
260           None by default. Set it to a coderef to validate the elements in
261           the array.  The coderef will be passed the element to validate as
262           first parameter, and it must return a boolean indicating whether
263           the element was valid or not.
264
265   assert_hashref()
266       Die unless the variable passed is a hashref that can be dereferenced
267       into a hash.
268
269               Data::Validate::Type::assert_hashref( $variable );
270
271               Data::Validate::Type::assert_hashref(
272                       $variable,
273                       allow_empty => 1,
274                       no_blessing => 0,
275               );
276
277       Parameters:
278
279       •   allow_empty
280
281           Boolean, default 1. Allow the array to be empty or not.
282
283       •   no_blessing
284
285           Boolean, default 0. Require that the variable is not blessed.
286
287   assert_coderef()
288       Die unless the variable passed is an coderef that can be dereferenced
289       into a block of code.
290
291               Data::Validate::Type::assert_coderef( $variable );
292
293   assert_number()
294       Die unless the variable passed is a number.
295
296               Data::Validate::Type::assert_number( $variable );
297               Data::Validate::Type::assert_number(
298                       $variable,
299                       positive => 1,
300               );
301               Data::Validate::Type::assert_number(
302                       $variable,
303                       strictly_positive => 1,
304               );
305
306       Parameters:
307
308       •   strictly_positive
309
310           Boolean, default 0. Set to 1 to check for a strictly positive
311           number.
312
313       •   positive
314
315           Boolean, default 0. Set to 1 to check for a positive number.
316
317   assert_instance()
318       Die unless the variable is an instance of the given class.
319
320       Note that this handles inheritance properly, so it will not die if the
321       variable is an instance of a subclass of the class given.
322
323               Data::Validate::Type::assert_instance(
324                       $variable,
325                       class => $class,
326               );
327
328       Parameters:
329
330       •   class
331
332           Required, the name of the class to check the variable against.
333
334   assert_regex()
335       Die unless the variable is a regular expression.
336
337               Data::Validate::Type::assert_regex( $variable );
338

FILTERING FUNCTIONS

340       Functions in this group return the variable tested against when it
341       matches the test(s) specified by the functions.
342
343       All the filtering functions can be imported at once in your namespace
344       with the following line:
345
346               use Data::Validate::Type qw( :filters );
347
348   filter_string()
349       Return the variable passed if it is a string, otherwise return undef.
350
351               Data::Validate::Type::filter_string( $variable );
352
353       Note: 0 and '' (empty string) are valid strings.
354
355       Parameters:
356
357       •   allow_empty
358
359           Boolean, default 1. Allow the string to be empty or not.
360
361   filter_arrayref()
362       Return the variable passed if it is an arrayref that can be
363       dereferenced into an array, otherwise undef.
364
365               Data::Validate::Type::filter_arrayref( $variable );
366
367               Data::Validate::Type::filter_arrayref(
368                       $variable,
369                       allow_empty => 1,
370                       no_blessing => 0,
371               );
372
373               # Only return the variable if it is an arrayref of hashrefs.
374               Data::Validate::Type::filter_arrayref(
375                       $variable,
376                       allow_empty           => 1,
377                       no_blessing           => 0,
378                       element_validate_type =>
379                               sub
380                               {
381                                       return Data::Validate::Type::is_hashref( $_[0] );
382                               },
383               );
384
385       Parameters:
386
387       •   allow_empty
388
389           Boolean, default 1. Allow the array to be empty or not.
390
391       •   no_blessing
392
393           Boolean, default 0. Require that the variable is not blessed.
394
395       •   element_validate_type
396
397           None by default. Set it to a coderef to validate the elements in
398           the array.  The coderef will be passed the element to validate as
399           first parameter, and it must return a boolean indicating whether
400           the element was valid or not.
401
402   filter_hashref()
403       Return the variable passed if it is a hashref that can be dereferenced
404       into a hash, otherwise return undef.
405
406               Data::Validate::Type::filter_hashref( $variable );
407
408               Data::Validate::Type::filter_hashref(
409                       $variable,
410                       allow_empty => 1,
411                       no_blessing => 0,
412               );
413
414       Parameters:
415
416       •   allow_empty
417
418           Boolean, default 1. Allow the array to be empty or not.
419
420       •   no_blessing
421
422           Boolean, default 0. Require that the variable is not blessed.
423
424   filter_coderef()
425       Return the variable passed if it is a coderef that can be dereferenced
426       into a block of code, otherwise return undef.
427
428               Data::Validate::Type::filter_coderef( $variable );
429
430   filter_number()
431       Return the variable passed if it is a number, otherwise return undef.
432
433               Data::Validate::Type::filter_number( $variable );
434               Data::Validate::Type::filter_number(
435                       $variable,
436                       positive => 1,
437               );
438               Data::Validate::Type::filter_number(
439                       $variable,
440                       strictly_positive => 1,
441               );
442
443       Parameters:
444
445       •   strictly_positive
446
447           Boolean, default 0. Set to 1 to check for a strictly positive
448           number.
449
450       •   positive
451
452           Boolean, default 0. Set to 1 to check for a positive number.
453
454   filter_instance()
455       Return the variable passed if it is an instance of the given class.
456
457       Note that this handles inheritance properly, so it will return the
458       variable if it is an instance of a subclass of the class given.
459
460               Data::Validate::Type::filter_instance(
461                       $variable,
462                       class => $class,
463               );
464
465       Parameters:
466
467       •   class
468
469           Required, the name of the class to check the variable against.
470
471   filter_regex()
472       Return the variable passed if it is a regular expression.
473
474               Data::Validate::Type::filter_regex( $variable );
475

BUGS

477       Please report any bugs or feature requests through the web interface at
478       <https://github.com/guillaumeaubert/Data-Validate-Type/issues>.  I will
479       be notified, and then you'll automatically be notified of progress on
480       your bug as I make changes.
481

SUPPORT

483       You can find documentation for this module with the perldoc command.
484
485               perldoc Data::Validate::Type
486
487       You can also look for information at:
488
489       •   GitHub (report bugs there)
490
491           <https://github.com/guillaumeaubert/Data-Validate-Type/issues>
492
493       •   AnnoCPAN: Annotated CPAN documentation
494
495           <http://annocpan.org/dist/Data-Validate-Type>
496
497       •   CPAN Ratings
498
499           <http://cpanratings.perl.org/d/Data-Validate-Type>
500
501       •   MetaCPAN
502
503           <https://metacpan.org/release/Data-Validate-Type>
504

AUTHOR

506       Guillaume Aubert <https://metacpan.org/author/AUBERTG>, "<aubertg at
507       cpan.org>".
508

ACKNOWLEDGEMENTS

510       Thanks to Adam Kennedy for writing Params::Util. This module started as
511       an encapsulation for Params::Util and I learnt quite a bit from it.
512

COPYRIGHT & LICENSE

514       Copyright 2012-2017 Guillaume Aubert.
515
516       This code is free software; you can redistribute it and/or modify it
517       under the same terms as Perl 5 itself.
518
519       This program is distributed in the hope that it will be useful, but
520       WITHOUT ANY WARRANTY; without even the implied warranty of
521       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE
522       file for more details.
523
524
525
526perl v5.36.0                      2022-07-22           Data::Validate::Type(3)