/ 
Data-Type-0.01.02
River stage zero No dependents
/ Data::Type

NAME

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

SYNOPSIS

use Data::Type 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::Type::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).

Backend was realized with 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::Type qw(:all); print catalog()" lists all supported types:

Data::Type 0.01.02 supports 28 types:

BINARY             - binary code
BOOL               - a true or false value
CREDITCARD         - is one of a set of creditcard type (DINERS, BANKCARD, VISA, ..
DATE               - a date (mysql or Date::Parse conform)
DATETIME           - a date and time combination
DK::YESNO          - a simple answer (mand, kvinde)
EMAIL              - an email address
ENUM               - a member of an enumeration
GENDER             - a gender male, female
HEX                - hexadecimal code
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 (mysql)
TIMESTAMP          - a timestamp (mysql)
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
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

W3C
  String
     BINARY, HEX

Numeric
 BOOL, INT, NUM, REAL

String
 DK::YESNO, 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::Type::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 (via Tie)

typ/untyp/istyp

typ and untyp are simlar to perl's tie/untie, but they are for Data::Type's. They tie a Data::Type to a variable, so each time it gets assigned a new value, it gots verified if its matching the datatypes constrains.

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::Facet (Internal use only)

This exception is thrown in the verification process if a Facet (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::Type 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', $entry->[0]->info();
}

EXPORT

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

None by default.

LAST CHANGES 0.01.02

  * Introduced various changes, thanks to https://rt.cpan.org/Ticket/Display.html?id=1930
    posted by Henrik Tougaard via RT

    - 'DATE' type now accepts parameters DATE( [ 'MYSQL','DATEPARSE' ] ) where MYSQL (default) is the
	mysql builtin data type behaviour and DATAPARSE leads to Data::Parse's str2time function use.
	- Introduced locale support (added empty package Data::Type::Locale)
	- separated localizable type parameters to methods, so they are overridable through inheriting
	localized types:
	
	Example Type::dk_yesno vs Type::yesno (snipped sourcecode):

	{
	package Type::yesno;

		our @ISA = qw(IType::String);
	
		sub info 
		{	
			my $this = shift;
					
			return sprintf q{a simple answer (%s)}, join( ', ', $this->choice ) ;
		}
	
		sub choice { qw(yes no) }
	
	package Type::dk_yesno;

		our @ISA = qw(Type::yesno);
		
		sub export { qw(DK::YESNO) };
			
		sub choice { qw(mand kvinde) }
	}
	
  * Export names for types are now accessible via 'export' method ( dk_yesno => DK::YESNO for instance ).
	
  * Types now have their own $VERSION
  
  * Some minor changes
    - rename IType:: info() to desc() for better distinguishing in toc(), because of a bug during
      @ISA traversal and IType:: identification (added _unique_ordered for using only unique desc's). 
    - toc() now lists also export alias's
    - regex's are now centralized and accessible via Regex::list( 'key' );

AUTHOR

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

SEE ALSO

http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 2221:

Non-ASCII character seen before =encoding in 'Ünalan,'. Assuming CP1252