NAME

Data::Verify - versatile data/type verification, validation and testing

SYNOPSIS

use Data::Verify qw(:all); use Error qw(:try);

# EMAIL, URI, IP('V4') are standard types

try
{
	verify( $cgi->param( 'email' ),    EMAIL  );
	verify( $cgi->param( 'homepage' ), URI('http') );
	verify( $cgi->param( 'serverip' ), IP('v4') );
	verify( $cgi->param( 'cc' ),       CREDITCARD( 'MASTERCARD', 'VISA' ) );
}
catch Type::Exception with
{	
	printf "Expected '%s' %s at %s line %s\n", $_->value, $_->type->info, $_->was_file, $_->was_line foreach @_;
};

my $h = Human->new( email => 'j@d.de', firstname => 'john', lastname => 'doe', sex => 'male', countrycode => '123123', age => 12 );

$h->contacts( { lucy => '110', john => '123' } );

my $g = Data::Verify::Guard->new( 

	types => [ 'Human', 'Others' ],
	
	tests =>
	{
		email		=> EMAIL( 1 ),		# mxcheck ON ! see Email::Valid
		firstname	=> WORD,
		contacts	=> sub { my %args = @_; exists $args{lucy} },				
	}
);

$g->inspect( $h );

DESCRIPTION

This module supports types. Out of the ordinary it supports parameterised types (like databases have i.e. VARCHAR(80) ). When you try to feed a typed variable against some odd data, this module explains what he would have expected. It doesnt support casting (yet).

Functionality was utilised amongst others by Regexp::Common, Email::Valid and Business::CreditCard.

KEYWORDS

data types, data manipulation, data patterns, form data, user input, tie

TYPES and FILTERS

perl -e "use Data::Verify qw(:all); print catalog()" lists all supported types:

Data::Verify 0.01.24 supports 25 types:

BOOL               - a true or false value
CREDITCARD         - is one of a set of creditcard type (DINERS, BANKCARD, VISA, ..
DATE               - a date
DATETIME           - a date and time combination
EMAIL              - an email address
ENUM               - a member of an enumeration
GENDER             - a gender (male|female)
INT                - an integer
IP                 - an IP (V4, MAC) network address
LONGTEXT           - text with a max length of 4294967295 (2^32 - 1) characters (..
MEDIUMTEXT         - text with a max length of 16777215 (2^24 - 1) characters (al..
NUM                - a number
QUOTED             - a quoted string
REAL               - a real
REF                - a reference to a variable
SET                - a set (can have a maximum of 64 members (mysql))
TEXT               - blob with a max length of 65535 (2^16 - 1) characters (alias..
TIME               - a time
TIMESTAMP          - a timestamp
TINYTEXT           - text with a max length of 255 (2^8 - 1) characters (alias my..
URI                - an http uri
VARCHAR            - a string with limited length of choice (default 60)
WORD               - a word (without spaces)
YEAR               - a year in 2- or 4-digit format
YESNO              - a simple answer (yes|no)

And 4 filters:

chomp              - chomps
lc                 - lower cases
strip              - strip whitespaces
uc                 - upper cases

GROUPED TYPES TOC

Logic
 CREDITCARD, REF

Database
  Logic
     ENUM, SET

  Time or Date related
     DATE, DATETIME, TIME, TIMESTAMP, YEAR

  String
     LONGTEXT, MEDIUMTEXT, TEXT, TINYTEXT

Numeric
 BOOL, INT, NUM, REAL

String
 EMAIL, GENDER, IP, QUOTED, URI, VARCHAR, WORD, YESNO

INTERFACE

FUNCTIONS

verify( $teststring, $type, [ .. ] ) - Verifies a 'value' against a 'type'.

overify( { member => TYPE, .. }, $object, [ .. ] ) - Verifies members of objects against multiple 'types' or CODEREFS.

Data::Verify::Guard class

This is something like a Bouncer. He inspect 'object' members for a specific type. The class has two attributes and one member.

'types' attribute (Array)

If empty isn't selective for special references ( HASH, ARRAY, "CUSTOM", .. ). If is set then "inspect" will fail if the object is not a reference of the listed type.

'tests' attribute (Hash)

Keys are the members names (anything that can be called via the $o->member syntax) and the type(s) as value. When a member should match multple types, they should be contained in an array reference ( i.e. 'fon' => [ qw(NUM TELEPHONE) ] ).

'inspect' member

Accepts a blessed reference as a parameter. It returns 0 if a guard test or type constrain will fail, otherwise 1.

TYPE BINDING

typ/untyp/istyp

Example

try { typ ENUM( qw(Murat mo muri) ), \( my $alias );

$alias = 'Murat';

$alias = 'mo';

$alias = 'XXX';
}
catch Type::Exception ::with
{
printf "Expected '%s' %s at %s line %s\n", $_->value, $_->type->info, $_->was_file, $_->was_line foreach @_;
};

Exceptions

Exceptions are implemented via the 'Error' module.

Type::Exception

This is a base class inheriting 'Error'.

Failure::Type

Is a 'Type::Exception' and has following additional members:

bool: 
	expected	- reserved for future use 
	returned	- reserved for future use
string: 
	was_file	- the filename where the exception was thrown
int: 
	was_line	- the line number
ref: 
	type 		- the type 'object' used for verification
	value		- a reference to the data given for verification against the type

Failure::Function (Internal use only)

This exception is thrown in the verification process if a Function (which is a subelement of the verification process) fails.

Is a 'Type::Exception' and has following additional members.

bool: 
	expected 	- reserved for future use
	returned	- reserved for future use
ref: 
	type		- the type 'object' used for verification

Retrieving Type Information

catalog()

returns a static string containing a listing of all know types (and a short information). This may be used to get an overview via:

perl -e "use Data::Verify qw(:all); print catalog()"

toc()

returns a string containing a grouped listing of all know types.

testplan( $type )

Returns the entry-objects how the type is verified. This may be used to create a textual description how a type is verified.

foreach my $entry ( testplan( $type ) )
{
	printf "\texpecting it %s %s ", $entry->[1] ? 'is' : 'is NOT', strlimit( $entry->[0]->info() );
}

EXPORT

all = (typ untyp istyp verify catalog testplan), map { uc } @types

None by default.

LAST CHANGES 0.01.24

added Tie::ListKeyedHash (0.41) to the Makefile.PL prerequisites
cleaned some of the pod documentation
added new type CREDITCARD (uses Business::CreditCard for LUHN mod10)
supported types are: DINERS, BANKCARD, VISA, DISCOVER, JCB, MASTERCARD, BLACHE, AMEX

AUTHOR

Murat Ünalan, <murat.uenalan@cpan.org>

SEE ALSO

Data::Types, String::Checker, Regexp::Common, Data::FormValidator, HTML::FormValidator, CGI::FormMagick::Validator, CGI::Validate, Email::Valid::Loose, Embperl::Form::Validate, Attribute::Types

cpanm Type::Exception

perl -MCPAN -e shell
install Type::Exception