/ 
Data-Type-0.01.04
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 $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 $server_ip4	, IP('v4');
		verify $server_ip6	, IP('v6');

		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 '0'			, DEFINED;
		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;
		
		verify '80'         , PORT;
		verify 'www.cpan.org', DOMAIN;
	}
	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 $_->param;					# 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;
	};
	   
    dverify( $email, EMAIL ) or die $!;

	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.04 supports 39 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
DEFINED         0.01.04  - a defined (not undef) value
DK::YESNO                - a simple answer (ja, nein)
BIO::DNA        0.01.03  - a dna sequence
DOMAIN          0.01.04  - a network domain name
EMAIL                    - an email address
ENUM                     - a member of an enumeration
GENDER                   - a gender male, female
HEX                      - hexadecimal code
INT                      - an integer
IP              0.01.04  - an IP (V4, V6, 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 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
PORT            0.01.04  - a network port 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, DEFINED, DOMAIN, EMAIL, IP, LANGCODE, LANGNAME, PORT, REF, URI

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, GENDER, QUOTED, VARCHAR, WORD, YESNO

INTERFACE

FUNCTIONS

verify( $s, $type, [ .. ] )

Verifies a 'value' against (one ore more) types or facets.

dverify( $s, EMAIL ) or die $!

Dies instead of throwing exceptions.

overify( { member => TYPE, .. }, $object, [ .. ] )

Verifys members of objects against multiple 'types' or CODEREFS.

Class Data::Type::Guard

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

allow => $ref_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 => $ref_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( $blessed )

Accepts a blessed reference as a parameter. It returns 0 if a guard test or type constrain will fail, otherwise 1. In future it should return a more appropriate report what failed and what not.

TYPE BINDING

Tie was employed to create something strict on variables. When a variable is typ'ed, everytime it is accessed a type-check (verify) is applied.

typ EMAIL( 1 ), \( my $typed_var, my $typed_etc, .. );

EMAIL is a placeholder for any type of this library. Once an invalid value was assigned to a var an exception gets thrown, so place your code in a try+catch block to handle that correctly.

$typed_var = 'faked&fake.de'; # throws exception

istyp( $typed_var )

Because tie'd variables are obscuring themself, istyp() helps here. It reveals $typed_var 's type.

if( $what = istyp( $a ) )
{
	print "a is typed to $what";
}

untyp

Takes the typ constrains from a variable (like untie).

untyp( $alias );

Exceptions

Exceptions are implemented via the 'Error' module. Type::Exception is the base class inheriting from 'Error' and beeing the anchestor of any exception used within this module.

Failure::Type

This exception has following members:

was_file

The filename where the exception was thrown.

was_line

The line number.

type

The type 'object' used for verification.

value

Reference to the data subjected to verification.

Failure::Facet

This exception is thrown in the verification process if a facet (which is a subelement of the verification process) fails. It is for no use, unless you are planning to create custom types.

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 -MData::Type -e "print Data::Type::catalog()"

toc()

Returns a static string containing a grouped listing of all know types.

perl -MData::Type -e "print Data::Type::toc()"

testplan( $type )

Returns the entry-objects how the type is verified. This may be used to create a textual description how the type verification process is driven. This could give clues to a web user, when he should get an error report, how his form submission would accepted.

depends()

Type:: package supports a method sub depends {qw(CPAN::aModule)}. It helps building a dependency tree classified for types. This function an an array reference, like this example:

[
	{
	'module' => 'Net::IPv6Addr',
	'version' => '0.2',
	'types' => [
					{
					'name' => 'IP'
					}
				]
	},
	{
	'module' => 'Locale::Language',
	'version' => '2.02',
	'types' => [
					{
					'name' => 'LANGCODE'
					},
					{
					'name' => 'LANGNAME'
					}
				],
	},
];

Note: This can be easily stuffed into HTML::Template's loops or in future helps implementing clever runtime module loading for only types really used.

EXPORT

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

None by default.

PREREQUISITES

Standard Class::Maker (0.05.10), Error (0.15), IO::Extended (0.05), Tie::ListKeyedHash (0.41), Iter (0)

And for types

Business::ISSN 0.90 by ISSN
Net::IPv6Addr 0.2 by IP
Locale::Language 2.02 by LANGCODE, LANGNAME
Business::CINS 1.13 by CINS
Email::Valid 0.14 by EMAIL
Date::Parse 2.23 by DATE
Business::CreditCard 0.27 by CREDITCARD
Regexp::Common 1.20 by INT, IP, QUOTED, REAL, URI
Business::UPC 0.02 by UPC

LAST CHANGES 0.01.04

  * added dverify( ) which is die'ing instead of throwing exceptions to the people:
  
        dverify( $email, EMAIL ) or die $!;
	
  * renamed 'choice' method for Type:: types to 'param'.
  
  * Some minor changes
    - Type::* package now supports new method C< sub depends {qw(CPAN::aModule)} > for retrieval of
	a dependency tree, which type made Data::Type require what.
	- added Data::Verify::depends() which returns a dependency list for types requiring other modules.
	
  * New (or updated) types:

  DEFINED         0.01.04  - a defined (not undef) value
  DOMAIN          0.01.04  - a network domain name
  IP              0.01.04  - an IP (V4, V6, MAC) network address
  PORT            0.01.04  - a network port number

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

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