package Data::Validate::Type;

use warnings;
use strict;

use base 'Exporter';

use Carp;
use Data::Dump qw();
use Scalar::Util qw();

my @boolean_functions_list = qw(
	is_string
	is_arrayref
	is_hashref
	is_coderef
	is_number
	is_instance
	is_regex
);

my @assertion_functions_list = qw(
	assert_string
	assert_arrayref
	assert_hashref
	assert_coderef
	assert_number
	assert_instance
	assert_regex
);

my @filtering_functions_list = qw(
	filter_string
	filter_arrayref
	filter_hashref
	filter_coderef
	filter_number
	filter_instance
	filter_regex
);

our @EXPORT_OK =
(
	@boolean_functions_list,
	@assertion_functions_list,
	@filtering_functions_list,
);
our %EXPORT_TAGS =
(
	boolean_tests => \@boolean_functions_list,
	assertions    => \@assertion_functions_list,
	filters       => \@filtering_functions_list,
	all           =>
	[
		@boolean_functions_list,
		@assertion_functions_list,
		@filtering_functions_list,
	],
);


=head1 NAME

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


=head1 VERSION

Version 1.6.0

=cut

our $VERSION = '1.6.0';


=head1 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' ) )
	{
		# ...
	}


=head1 DESCRIPTION

L<Params::Util> is a wonderful module, but suffers from a few drawbacks:

=over 4

=item * Function names start with an underscore, which is usually used to
indicate private functions.

=item * Function names are uppercase, which is usually used to indicate file
handles or constants.

=item * Function names don't pass PerlCritic's validation, making them
problematic to import.

=item * 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.

=item * In Pure Perl mode, the functions are created via eval, which causes
issues for L<Devel::Cover> in taint mode.

=back

Those drawbacks are purely cosmetic and don't affect the usefulness of the
functions, except for the last one. This module used to encapsulate
L<Params::Util>, but I had to refactor it out to fix the issues with
L<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.


=head1 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 );


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the string to be empty or not.

=back

=cut

sub is_string
{
	my ( $variable, %args ) = @_;

	# Check parameters.
	my $allow_empty = delete( $args{'allow_empty'} );
	$allow_empty = 1 unless defined( $allow_empty );
	croak 'Arguments not recognized: ' . Data::Dump::dump( %args )
		unless scalar( keys %args ) == 0;

	# Check variable.
	return 0 if !defined( $variable ) || ref( $variable );

	# Check length if we don't allow empty strings.
	return 0 if !$allow_empty && length( $variable ) == 0;

	return 1;
}


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the array to be empty or not.

=item * no_blessing

Boolean, default 0. Require that the variable is not blessed.

=item * 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.

=back

=cut

sub is_arrayref
{
	my ( $variable, %args ) = @_;

	# Check parameters.
	my $allow_empty = delete( $args{'allow_empty'} );
	$allow_empty = 1 unless defined( $allow_empty );
	my $no_blessing = delete( $args{'no_blessing'} ) || 0;
	my $element_validate_type = delete( $args{'element_validate_type'} );
	croak '"element_validate_type" must be a coderef'
		if defined( $element_validate_type ) && !is_coderef( $element_validate_type );
	croak 'Arguments not recognized: ' . Data::Dump::dump( %args )
		unless scalar( keys %args ) == 0;

	# Check variable.
	return 0 if !defined( $variable ) || !ref( $variable );

	if ( $no_blessing )
	{
		# The variable must be a standard arrayref.
		return 0 if ref( $variable ) ne 'ARRAY';
	}
	else
	{
		# Check that the variable is either an array or allows
		# dereferencing as one.
		return 0 if !
			(
				( Scalar::Util::reftype( $variable ) eq 'ARRAY' )
				|| overload::Method( $variable, '@{}' )
			);
	}

	# Check size of the array if we require a non-empty array.
	return 0 if !$allow_empty && scalar( @$variable ) == 0;

	# If we have an element validator specified, now that we know that we have
	# an array, it's a good time to test the individual elements.
	if ( defined( $element_validate_type ) )
	{
		foreach my $element ( @$variable )
		{
			return 0 if !$element_validate_type->( $element );
		}
	}

	return 1;
}


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the array to be empty or not.

=item * no_blessing

Boolean, default 0. Require that the variable is not blessed.

=back

=cut

sub is_hashref
{
	my ( $variable, %args ) = @_;

	# Check parameters.
	my $allow_empty = delete( $args{'allow_empty'} );
	$allow_empty = 1 unless defined( $allow_empty );
	my $no_blessing = delete( $args{'no_blessing'} ) || 0;
	croak 'Arguments not recognized: ' . Data::Dump::dump( %args )
		unless scalar( keys %args ) == 0;

	# Check variable.
	return 0 if !defined( $variable ) || !ref( $variable );

	if ( $no_blessing )
	{
		# The variable must be a standard hashref.
		return 0 if ref( $variable ) ne 'HASH';
	}
	else
	{
		# Check that the variable is either a hashref or allows dereferencing
		# as one.
		return 0 if !
			(
				( Scalar::Util::reftype( $variable ) eq 'HASH' )
				|| overload::Method( $variable, '%{}' )
			);
	}

	# If we don't allow empty hashes, check keys.
	return 0 if !$allow_empty && scalar( keys %$variable ) == 0;

	return 1;
}


=head2 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 );

=cut

sub is_coderef
{
	my ( $variable, %args ) = @_;

	# Check parameters.
	croak 'Arguments not recognized: ' . Data::Dump::dump( %args )
		unless scalar( keys %args ) == 0;

	# Check variable.
	return 0 if !defined( $variable ) || !ref( $variable );
	return 0 if ref( $variable ) ne 'CODE';

	return 1;
}


=head2 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:

=over 4

=item * strictly_positive

Boolean, default 0. Set to 1 to check for a strictly positive number.

=item * positive

Boolean, default 0. Set to 1 to check for a positive number.

=back

=cut

sub is_number
{
	my ( $variable, %args ) = @_;

	# Check parameters.
	my $positive = delete( $args{'positive'} ) || 0;
	my $strictly_positive = delete( $args{'strictly_positive'} ) || 0;
	croak 'Arguments not recognized: ' . Data::Dump::dump( %args )
		unless scalar( keys %args ) == 0;

	# Check variable.
	return 0 if !defined( $variable ) || ref( $variable );

	# Requires Scalar::Util v1.18 or higher.
	return 0 if !Scalar::Util::looks_like_number( $variable );

	# Check extra restrictions.
	return 0 if $positive && $variable < 0;
	return 0 if $strictly_positive && $variable <= 0;

	return 1;
}


=head2 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:

=over 4

=item * class

Required, the name of the class to check the variable against.

=back

=cut

sub is_instance
{
	my ( $variable, %args ) = @_;

	# Check parameters.
	my $class = delete( $args{'class'} );
	croak 'A class argument is required'
		if !defined( $class ) || $class eq '';
	croak 'Arguments not recognized: ' . Data::Dump::dump( %args )
		unless scalar( keys %args ) == 0;

	# Check variable.
	return 0 if !defined( $variable ) || !Scalar::Util::blessed( $variable );

	# Test that the object is a member if the class.
	return 0 if !$variable->isa( $class );

	return 1;
}


=head2 is_regex()

Return a boolean indicating if the variable is a regular expression.

	my $is_regex = Data::Validate::Type::is_regex( $variable );

=cut

sub is_regex
{
	my ( $variable ) = @_;

	# Check variable.
	return defined( $variable ) && ( ref( $variable ) eq 'Regexp' )
		? 1
		: 0;
}


=head1 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 );


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the string to be empty or not.

=back

=cut

sub assert_string
{
	my ( $variable, %args ) = @_;

	croak 'Not a string'
		unless is_string( $variable, %args );

	return;
}


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the array to be empty or not.

=item * no_blessing

Boolean, default 0. Require that the variable is not blessed.

=item * 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.

=back

=cut

sub assert_arrayref
{
	my ( $variable, %args ) = @_;

	croak 'Not an arrayref'
		unless is_arrayref( $variable, %args );

	return;
}


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the array to be empty or not.

=item * no_blessing

Boolean, default 0. Require that the variable is not blessed.

=back

=cut

sub assert_hashref
{
	my ( $variable, %args ) = @_;

	croak 'Not a hashref'
		unless is_hashref( $variable, %args );

	return;
}


=head2 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 );

=cut

sub assert_coderef
{
	my ( $variable, %args ) = @_;

	croak 'Not a coderef'
		unless is_coderef( $variable, %args );

	return;
}


=head2 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:

=over 4

=item * strictly_positive

Boolean, default 0. Set to 1 to check for a strictly positive number.

=item * positive

Boolean, default 0. Set to 1 to check for a positive number.

=back

=cut

sub assert_number
{
	my ( $variable, %args ) = @_;

	croak 'Not a number'
		unless is_number( $variable, %args );

	return;
}


=head2 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:

=over 4

=item * class

Required, the name of the class to check the variable against.

=back

=cut

sub assert_instance
{
	my ( $variable, %args ) = @_;

	croak 'Not an instance of the class'
		unless is_instance( $variable, %args );

	return;
}


=head2 assert_regex()

Die unless the variable is a regular expression.

	Data::Validate::Type::assert_regex( $variable );

=cut

sub assert_regex
{
	my ( $variable ) = @_;

	croak 'Not a regular expression'
		unless is_regex( $variable );

	return;
}


=head1 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 );


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the string to be empty or not.

=back

=cut

sub filter_string
{
	my ( $variable, %args ) = @_;

	return is_string( $variable, %args )
		? $variable
		: undef;
}


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the array to be empty or not.

=item * no_blessing

Boolean, default 0. Require that the variable is not blessed.

=item * 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.

=back

=cut

sub filter_arrayref
{
	my ( $variable, %args ) = @_;

	return is_arrayref( $variable, %args )
		? $variable
		: undef;
}


=head2 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:

=over 4

=item * allow_empty

Boolean, default 1. Allow the array to be empty or not.

=item * no_blessing

Boolean, default 0. Require that the variable is not blessed.

=back

=cut

sub filter_hashref
{
	my ( $variable, %args ) = @_;

	return is_hashref( $variable, %args )
		? $variable
		: undef;
}


=head2 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 );

=cut

sub filter_coderef
{
	my ( $variable, %args ) = @_;

	return is_coderef( $variable, %args )
		? $variable
		: undef;
}


=head2 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:

=over 4

=item * strictly_positive

Boolean, default 0. Set to 1 to check for a strictly positive number.

=item * positive

Boolean, default 0. Set to 1 to check for a positive number.

=back

=cut

sub filter_number
{
	my ( $variable, %args ) = @_;

	return is_number( $variable, %args )
		? $variable
		: undef;
}


=head2 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:

=over 4

=item * class

Required, the name of the class to check the variable against.

=back

=cut

sub filter_instance
{
	my ( $variable, %args ) = @_;

	return is_instance( $variable, %args )
		? $variable
		: undef;
}


=head2 filter_regex()

Return the variable passed if it is a regular expression.

	Data::Validate::Type::filter_regex( $variable );

=cut

sub filter_regex
{
	my ( $variable ) = @_;

	return is_regex( $variable )
		? $variable
		: undef;
}


=head1 BUGS

Please report any bugs or feature requests through the web interface at
L<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.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

	perldoc Data::Validate::Type


You can also look for information at:

=over 4

=item * GitHub (report bugs there)

L<https://github.com/guillaumeaubert/Data-Validate-Type/issues>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Data-Validate-Type>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Data-Validate-Type>

=item * MetaCPAN

L<https://metacpan.org/release/Data-Validate-Type>

=back


=head1 AUTHOR

L<Guillaume Aubert|https://metacpan.org/author/AUBERTG>,
C<< <aubertg at cpan.org> >>.


=head1 ACKNOWLEDGEMENTS

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


=head1 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.

=cut

1;