/ 
Data-Verify-0.01_01
/ Data::Verify

NAME

Data::Verify - object oriented data verification, validation and testing

SYNOPSIS

use Data::Verify qw(assess verify);

{
	package Data::Verify::Type;

	our $digit_not_0 = Data::Verify::Type->new(

		desc => 'a number or digit, but not 0',

		extends => [qw(limited)],

		pass => { match => qr/[\d]+/ },

		fail => { match => qr/^0+$/ }

	);

	our $german_zip = Data::Verify::Type->new(

		desc => 'a german zip code',

		extends => [qw(number)],

		pass => { less => 7 },

		fail => { less => 4 }
	);
}

verify( label => 'my personal digit', value => '12', type => 'digit_not_0' );

verify( label => 'an foreign zip', value => '999-233', type => 'german_zip' );

DESCRIPTION

A sceptic programmer never trusts somebody else his input (web forms, config files, etc.). He verifys if the data is in the right format. With this module he can do it in a very elegant and efficient way. Using object oriented techniques, you can create a hierarchy of tests for verifying almost everything.

The verification procedure is like a simple program. The building blocks are called tests. Multiple tests result into a 'test program'. While some tests may be expected to fail, and some to pass to result into a valid verification. I call every data which passes the complete program as expected belonging to a 'data type' (So i use this term instead of 'test program').

Here an example in pseudo-code:

DATA_TYPE A (extends DATA_TYPE B)
{
	PASS
	{
		TEST 5
		TEST 6
	}

	FAIL
	{
		TEST 1
		TEST 2
		TEST 3
		TEST 4
	}
}

This means: Data is (belonging to) 'DATA TYPE' when it is passing test 5 and 6 with success, and is failing tests 1,2,3 and 4. It also EXTENDS 'DATA_TYPE B', that means that "DATA_TYPE A" inherits all "DATA_TYPE A" PASS+FAIL tests.

TESTS

Tests are simply subroutines in the Data::Verify::Test package. Per definition a test receives: 1) the test value 2) the test arguments. Then it simply returns true or false.

Here a very simple example:

sub my_test { $_[0] > $_[1] }	# my_test( 12300, 100 ) would test if 12300 is bigger than 100

PREDEFINED TESTS

Following tests are always instantly available.

range 	- takes two arguments where the value has to be inbetween (ie. range => [1,800] )

lines 	- counts the lines (\n) (ie. lines => 5 )

less 	- lesser than the length in characters (ie. less => 3)

match 	- takes a regex to match (ie. match => qr/^0+$/ )

is 		- exact string comparision (ie. is => 'follow' )

bool 	- transformation of the value into bool (ie. bool => undef)

NULL 	- exact string match 'NULL' (ie. NULL => 1)

exists_in - checks whether the <var> is in a list. if list is an

	Array:	look if exact string is a member

	Hash:	look if the <var> key exists

	Example:

		pass => { exists_in => { firstname => 1, lastname => 1, email => 1 } },

		fail => { exists_in => [qw(blabla)] }

DATA TYPES

A data can be simply instanciated by creation of a new Data::Verify::Type object.

Example (how to create a new data type):

package Data::Verify::Type;

	our $number_notnull = new Data::Verify::Type(

		desc => 'a number or digit, but not 0',

		extends => [qw(number)],

		fail => { match => qr/^0+$/ }
	);

Normally we should have added 'pass => { match => qr/\d+/ },', but we dont explicitly need to add it
because we inherit that from 'number'. Note: A regex-guru would have written simply a better regex which
would had done it with just one match, but this example is for education purposes.

PREDEFINED DATA TYPES

Following types are always instantly available.

true 		- a boolean true value

false		- a boolean false value

not_null	- not the string "NULL"

null		- must be the string "NULL"

limited	- a word longer than 1 character

text		- a standard length text ( 1-800 characters )

word		- a word ( match => qr/[a-zA-Z\-]+[0-9]*/ } )

name		- a first- or lastnames

login     - a login- or nickname

email		- an email address

number	- a number or digit

number_notnull 	- a number or digit, but not 0

zip_ger	- a german zip code

phone_ger - a german phone number

creditcard	- a credit-card number (not implemented yet)

FUNCTIONS

verify( $teststring, $data_type )

Verifies a 'value' against a 'type'.

Example:

my $verify_result = verify( label => 'Config.Author.Level', value => 'NULL', type => 'not_null' );

assess( $verify_result ) # this would fail

Because verify returns a hashref containing information about the test result, you must use 'assess' (below) to transform it to a simple boolean value.

assess( $verify_result )

Use 'assess' to process the result of 'verify' to a simple boolean value.

Example:

assess( verify( value => 0, type => 'false' );	# would return true

EXPORT

:all = assess, verify

None by default.

AUTHOR

Murat Uenalan, muenalan@cpan.org

SEE ALSO

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