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

NAME

Data::Type - versatile data and value types

SYNOPSIS

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

try
{
	verify $email		, EMAIL;
	verify $homepage	, URI('http');
	verify $server_ip	, IP('v4');
	verify $cc			, CREDITCARD( 'MASTERCARD', 'VISA' );
	verify $answer_a	, YESNO;
	verify $gender		, GENDER;
	verify 'one'		, ENUM( qw(one two three) );
	verify [qw(two six)], SET( qw(one two three four five six) ) );

	verify 'A35231AH1'	, CINS;
	verify '14565935'	, ISSN;		
	verify 'DE'			, LANGCODE;		
	verify 'German'		, LANGNAME;
	
	verify '012345678905', UPC();
	verify '5276440065421319', CREDITCARD( 'MASTERCARD' ) );

	verify 'ATGCAAAT'	, BIO::DNA;				
	verify 'AUGGGAAAU'	, BIO::RNA;		

	verify '01001001110110101', BINARY;
	verify '0F 0C 0A', HEX;

	verify '234'		, NUM( 20 );
	verify '1' 			, BOOL( 'true' );
	verify '100'		, INT;
	verify '1.1'		, REAL;

	my $foo = bless( \'123', 'SomeThing' );
		
	verify $foo 		, REF;
	verify $foo			, REF( qw(SomeThing Else) );
	verify [ 'bar' ]	, REF( 'ARRAY' );

	verify ' ' x 20		, VARCHAR( 20 );
	verify '2001-01-01'	, DATE( 'MYSQL' );
	verify '16 Nov 94 22:28:20 PST'	, DATE( 'DATEPARSE' );
	verify '9999-12-31 23:59:59', DATETIME;
	verify '1970-01-01 00:00:00', TIMESTAMP;
	verify '-838:59:59'	, TIME;
	verify '2155'		, YEAR;
	verify '69'			, YEAR(2);
	verify '0' x 20		, TINYTEXT;
	verify '0' x 20		, MEDIUMTEXT;
	verify '0' x 20		, LONGTEXT;
	verify '0' x 20		, TEXT;
}
catch Type::Exception with
{	
	my $e = shift;
	
	printf "Expected '%s' %s at %s line %s\n",
		$e->value, 
		$e->type->info, 
		$e->was_file, 
		$e->was_line;

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

	# believe it or not, this really works
	
foreach ( EMAIL, WORD, CREDITCARD( 'MASTERCARD', 'VISA' ), BIO::DNA, HEX )
{
	print $_->info;						
	print $_->usage;					
	print $_->export;					# does it have other names
	print $_->choice;					# what are my choice i.e. [yes,no]
	print $_->isa( 'IType::Business' ); # is it a Business related type ?
	print $_->VERSION;					# first apperance in Data::Type release
}
	
	# tied interface (alias 'typ')
	
try
{			
	typ ENUM( qw(DNA RNA) ), \( my $a, my $b );

	print "a is typ'ed" if istyp( $a );

	$a = 'DNA';		# $alias only accepts 'DNA' or 'RNA'
	$a = 'RNA';		
	$a = 'xNA';		# throws exception 
	
	untyp( $alias );
}
catch Type::Exception ::with
{
	printf "Expected '%s' %s at %s line %s\n",
		$e->value, 
		$e->type->info, 
		$e->was_file, 
		$e->was_line;
};
	
my $g = Data::Type::Guard->new( 

	allow => [ 'Human', 'Others' ],		# blessed objects of that type
	
	tests =>
	{
		email		=> EMAIL( 1 ),		# mxcheck ON ! see Email::Valid
		firstname	=> WORD,
		social_id	=> [ NUM, VARCHAR( 10 ) ],
		contacts	=> sub { my %args = @_; exists $args{lucy} },				
	}
);

$g->inspect( $h );

	# compact version
	
overify { email => EMAIL( 1 ), firstname => WORD }, $object_a, $object_b;

print toc();

print catalog();

DESCRIPTION

This module supports versatile data and value 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.

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.03 supports 36 types:

BINARY                   - binary code
BOOL                     - a true or false value
CINS            0.01.03  - a CUSIP International Numbering System Number
BIO::CODON      0.01.03  - a DNA (default) or RNA nucleoside triphosphates triplet
CREDITCARD               - is one of a set of creditcard type (DINERS, BANKCARD, VISA, ..
DATE            0.01.01  - a date (mysql or Date::Parse conform)
DATETIME                 - a date and time combination
DK::YESNO                - a simple answer (ja, nein)
BIO::DNA        0.01.03  - a dna sequence
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
ISSN            0.01.03  - an International Standard Serial Number
LANGCODE        0.01.03  - a Locale::Language language code
LANGNAME        0.01.03  - a Locale::Language language name
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
BIO::RNA        0.01.03  - a rna sequence
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..
UPC             0.01.03  - standard (type-A) Universal Product Code
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

TYPES BY GROUP

Logic
 BIO::CODON, BIO::DNA, BIO::RNA, LANGCODE, LANGNAME, REF

Database
  Logic
     ENUM, SET

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

  String
     LONGTEXT, MEDIUMTEXT, TEXT, TINYTEXT

Business
 CINS, CREDITCARD, ISSN, UPC

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.

'allow' 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.

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.

EXPORT

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

None by default.

LAST CHANGES 0.01.03

* Changed the Data::Type::Guard attribute 'types' to 'allow', because was ambiguous with types per se.

* New group IType::Business (see toc).

* Some minor changes
 - toc() now sorts types alphanumeretically
 - IType:: Groups also get version
 - added type version number to catalog() output

* New (or updated) types:

CINS            0.01.03  - a CUSIP International Numbering System Number
BIO::CODON      0.01.03  - a DNA (default) or RNA nucleoside triphosphates triplet
BIO::DNA        0.01.03  - a dna sequence
ISSN            0.01.03  - an International Standard Serial Number
LANGCODE        0.01.03  - a Locale::Language language code
LANGNAME        0.01.03  - a Locale::Language language name
BIO::RNA        0.01.03  - a rna sequence
UPC             0.01.03  - standard (type-A) Universal Product Code

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 2576:

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