oracular (3) Data::Validate::Type.3pm.gz
NAME
Data::Validate::Type - Data type validation functions.
VERSION
Version 1.6.0
SYNOPSIS
# Call with explicit package name.
use Data::Validate::Type;
if ( Data::Validate::Type::is_string( 'test' ) )
{
# ...
}
# Import specific functions.
use Data::Validate::Type qw( is_string );
if ( is_string( 'test' ) )
{
# ...
}
# Import functions for a given paradigm.
use Data::Validate::Type qw( :boolean_tests );
if ( is_string( 'test' ) )
{
# ...
}
DESCRIPTION
Params::Util is a wonderful module, but suffers from a few drawbacks:
• Function names start with an underscore, which is usually used to indicate private functions.
• Function names are uppercase, which is usually used to indicate file handles or constants.
• Function names don't pass PerlCritic's validation, making them problematic to import.
• Functions use by default the convention that collection that collections need to not be empty to be
valid (see _ARRAY0/_ARRAY for example), which is counter-intuitive.
• In Pure Perl mode, the functions are created via eval, which causes issues for Devel::Cover in taint
mode.
Those drawbacks are purely cosmetic and don't affect the usefulness of the functions, except for the last
one. This module used to encapsulate Params::Util, but I had to refactor it out to fix the issues with
Devel::Cover.
Please note that I prefer long function names that are descriptive, to arcane short ones. This increases
readability, and the bulk of the typing can be spared with the use of a good IDE like Padre.
Also, this is work in progress - There is more functions that should be added here, if you need one in
particular feel free to contact me.
BOOLEAN TEST FUNCTIONS
Functions in this group return a boolean to indicate whether the parameters passed match the test(s)
specified by the functions or not.
All the boolean functions can be imported at once in your namespace with the following line:
use Data::Validate::Type qw( :boolean_tests );
is_string()
Return a boolean indicating if the variable passed is a string.
my $is_string = Data::Validate::Type::is_string( $variable );
Note: 0 and '' (empty string) are valid strings.
Parameters:
• allow_empty
Boolean, default 1. Allow the string to be empty or not.
is_arrayref()
Return a boolean indicating if the variable passed is an arrayref that can be dereferenced into an array.
my $is_arrayref = Data::Validate::Type::is_arrayref( $variable );
my $is_arrayref = Data::Validate::Type::is_arrayref(
$variable,
allow_empty => 1,
no_blessing => 0,
);
# Check if the variable is an arrayref of hashrefs.
my $is_arrayref = Data::Validate::Type::is_arrayref(
$variable,
allow_empty => 1,
no_blessing => 0,
element_validate_type =>
sub
{
return Data::Validate::Type::is_hashref( $_[0] );
},
);
Parameters:
• allow_empty
Boolean, default 1. Allow the array to be empty or not.
• no_blessing
Boolean, default 0. Require that the variable is not blessed.
• element_validate_type
None by default. Set it to a coderef to validate the elements in the array. The coderef will be
passed the element to validate as first parameter, and it must return a boolean indicating whether
the element was valid or not.
is_hashref()
Return a boolean indicating if the variable passed is a hashref that can be dereferenced into a hash.
my $is_hashref = Data::Validate::Type::is_hashref( $variable );
my $is_hashref = Data::Validate::Type::is_hashref(
$variable,
allow_empty => 1,
no_blessing => 0,
);
Parameters:
• allow_empty
Boolean, default 1. Allow the array to be empty or not.
• no_blessing
Boolean, default 0. Require that the variable is not blessed.
is_coderef()
Return a boolean indicating if the variable passed is an coderef that can be dereferenced into a block of
code.
my $is_coderef = Data::Validate::Type::is_coderef( $variable );
is_number()
Return a boolean indicating if the variable passed is a number.
my $is_number = Data::Validate::Type::is_number( $variable );
my $is_number = Data::Validate::Type::is_number(
$variable,
positive => 1,
);
my $is_number = Data::Validate::Type::is_number(
$variable,
strictly_positive => 1,
);
Parameters:
• strictly_positive
Boolean, default 0. Set to 1 to check for a strictly positive number.
• positive
Boolean, default 0. Set to 1 to check for a positive number.
is_instance()
Return a boolean indicating if the variable is an instance of the given class.
Note that this handles inheritance properly, so it will return true if the variable is an instance of a
subclass of the class given.
my $is_instance = Data::Validate::Type::is_instance(
$variable,
class => $class,
);
Parameters:
• class
Required, the name of the class to check the variable against.
is_regex()
Return a boolean indicating if the variable is a regular expression.
my $is_regex = Data::Validate::Type::is_regex( $variable );
ASSERTION-BASED FUNCTIONS
Functions in this group do not return anything, but will die when the parameters passed don't match the
test(s) specified by the functions.
All the assertion test functions can be imported at once in your namespace with the following line:
use Data::Validate::Type qw( :assertions );
assert_string()
Die unless the variable passed is a string.
Data::Validate::Type::assert_string( $variable );
Note: 0 and '' (empty string) are valid strings.
Parameters:
• allow_empty
Boolean, default 1. Allow the string to be empty or not.
assert_arrayref()
Die unless the variable passed is an arrayref that can be dereferenced into an array.
Data::Validate::Type::assert_arrayref( $variable );
Data::Validate::Type::assert_arrayref(
$variable,
allow_empty => 1,
no_blessing => 0,
);
# Require the variable to be an arrayref of hashrefs.
Data::Validate::Type::assert_arrayref(
$variable,
allow_empty => 1,
no_blessing => 0,
element_validate_type =>
sub
{
return Data::Validate::Type::is_hashref( $_[0] );
},
);
Parameters:
• allow_empty
Boolean, default 1. Allow the array to be empty or not.
• no_blessing
Boolean, default 0. Require that the variable is not blessed.
• element_validate_type
None by default. Set it to a coderef to validate the elements in the array. The coderef will be
passed the element to validate as first parameter, and it must return a boolean indicating whether
the element was valid or not.
assert_hashref()
Die unless the variable passed is a hashref that can be dereferenced into a hash.
Data::Validate::Type::assert_hashref( $variable );
Data::Validate::Type::assert_hashref(
$variable,
allow_empty => 1,
no_blessing => 0,
);
Parameters:
• allow_empty
Boolean, default 1. Allow the array to be empty or not.
• no_blessing
Boolean, default 0. Require that the variable is not blessed.
assert_coderef()
Die unless the variable passed is an coderef that can be dereferenced into a block of code.
Data::Validate::Type::assert_coderef( $variable );
assert_number()
Die unless the variable passed is a number.
Data::Validate::Type::assert_number( $variable );
Data::Validate::Type::assert_number(
$variable,
positive => 1,
);
Data::Validate::Type::assert_number(
$variable,
strictly_positive => 1,
);
Parameters:
• strictly_positive
Boolean, default 0. Set to 1 to check for a strictly positive number.
• positive
Boolean, default 0. Set to 1 to check for a positive number.
assert_instance()
Die unless the variable is an instance of the given class.
Note that this handles inheritance properly, so it will not die if the variable is an instance of a
subclass of the class given.
Data::Validate::Type::assert_instance(
$variable,
class => $class,
);
Parameters:
• class
Required, the name of the class to check the variable against.
assert_regex()
Die unless the variable is a regular expression.
Data::Validate::Type::assert_regex( $variable );
FILTERING FUNCTIONS
Functions in this group return the variable tested against when it matches the test(s) specified by the
functions.
All the filtering functions can be imported at once in your namespace with the following line:
use Data::Validate::Type qw( :filters );
filter_string()
Return the variable passed if it is a string, otherwise return undef.
Data::Validate::Type::filter_string( $variable );
Note: 0 and '' (empty string) are valid strings.
Parameters:
• allow_empty
Boolean, default 1. Allow the string to be empty or not.
filter_arrayref()
Return the variable passed if it is an arrayref that can be dereferenced into an array, otherwise undef.
Data::Validate::Type::filter_arrayref( $variable );
Data::Validate::Type::filter_arrayref(
$variable,
allow_empty => 1,
no_blessing => 0,
);
# Only return the variable if it is an arrayref of hashrefs.
Data::Validate::Type::filter_arrayref(
$variable,
allow_empty => 1,
no_blessing => 0,
element_validate_type =>
sub
{
return Data::Validate::Type::is_hashref( $_[0] );
},
);
Parameters:
• allow_empty
Boolean, default 1. Allow the array to be empty or not.
• no_blessing
Boolean, default 0. Require that the variable is not blessed.
• element_validate_type
None by default. Set it to a coderef to validate the elements in the array. The coderef will be
passed the element to validate as first parameter, and it must return a boolean indicating whether
the element was valid or not.
filter_hashref()
Return the variable passed if it is a hashref that can be dereferenced into a hash, otherwise return
undef.
Data::Validate::Type::filter_hashref( $variable );
Data::Validate::Type::filter_hashref(
$variable,
allow_empty => 1,
no_blessing => 0,
);
Parameters:
• allow_empty
Boolean, default 1. Allow the array to be empty or not.
• no_blessing
Boolean, default 0. Require that the variable is not blessed.
filter_coderef()
Return the variable passed if it is a coderef that can be dereferenced into a block of code, otherwise
return undef.
Data::Validate::Type::filter_coderef( $variable );
filter_number()
Return the variable passed if it is a number, otherwise return undef.
Data::Validate::Type::filter_number( $variable );
Data::Validate::Type::filter_number(
$variable,
positive => 1,
);
Data::Validate::Type::filter_number(
$variable,
strictly_positive => 1,
);
Parameters:
• strictly_positive
Boolean, default 0. Set to 1 to check for a strictly positive number.
• positive
Boolean, default 0. Set to 1 to check for a positive number.
filter_instance()
Return the variable passed if it is an instance of the given class.
Note that this handles inheritance properly, so it will return the variable if it is an instance of a
subclass of the class given.
Data::Validate::Type::filter_instance(
$variable,
class => $class,
);
Parameters:
• class
Required, the name of the class to check the variable against.
filter_regex()
Return the variable passed if it is a regular expression.
Data::Validate::Type::filter_regex( $variable );
BUGS
Please report any bugs or feature requests through the web interface at
<https://github.com/guillaumeaubert/Data-Validate-Type/issues>. I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Data::Validate::Type
You can also look for information at:
• GitHub (report bugs there)
<https://github.com/guillaumeaubert/Data-Validate-Type/issues>
• AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Data-Validate-Type>
• CPAN Ratings
<http://cpanratings.perl.org/d/Data-Validate-Type>
• MetaCPAN
<https://metacpan.org/release/Data-Validate-Type>
AUTHOR
Guillaume Aubert <https://metacpan.org/author/AUBERTG>, "<aubertg at cpan.org>".
ACKNOWLEDGEMENTS
Thanks to Adam Kennedy for writing Params::Util. This module started as an encapsulation for Params::Util
and I learnt quite a bit from it.
COPYRIGHT & LICENSE
Copyright 2012-2017 Guillaume Aubert.
This code is free software; you can redistribute it and/or modify it under the same terms as Perl 5
itself.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for
more details.