NAME

Data::Type - robust, extensible data- and valuetype system

SYNOPSIS

use Data::Type qw(:all +W3C)  # or +BIO, +DB

PROCEDURAL

warn 'invalid email' unless is STD::EMAIL;

dvalid( $email, STD::EMAIL ) or die $Data::Type::err;                # Exceptions are stored in $Data::Type::err

OBJECT-ORIENTED

try
{
  valid '01001001110110101', STD::BINARY;
}
catch Data::Type::Exception with
{
  my $dte = shift;

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

foreach my $dt ( STD::EMAIL, STD::WORD, STD::CREDITCARD( 'MASTERCARD', 'VISA' ), STD::BIO::DNA, STD::HEX )
{
  print $dt->$_ for qw(VERSION info usage export param)

  print "belongs to DB collection" if $dt->isa( 'Data::Type::Collection::DB::Interface' ); # is it a Database related type ?
}

DESCRIPTION

A lot of CPAN modules have a common purpose: reporting if data has some "characteristics". Email::Valid is an illustrous example: reporting if a string has characteristics of an email address. The address() method reports this via returning 'yes' or 'no'. Another module, another behaviour: Business::ISSN tests for the characteristics of an International Standard Serial Number and does this via an is_valid method returning true or false. And so on and so on.

The key concept:

• a unified interface to type related CPAN modules

• generic but simple API (fun to extend)

• paremeterized types

• alternativly exception-based or functional problem reports

• localization via Locale::Maketext

• a lot of syntactic sugar ( die unless is BIO::DNA )

• generic access through DBI to catalog of data types and more

This module relies, as much as its plausible, on CPAN modules doing the job in the backend. For instance Regexp::Common is doing a lot of the regular expression testing. Email::Valid takes care of the EMAIL type. Data::Parse can be exploited for doing the backwork for the DATE type.

DOCUMENTATION

You find a gentle introduction at Data::Type::Docs. It also navigates you through the rest of the documentation. Advanced users should keep on reading here.

SUPPORTED TYPES

All types are grouped and though belong to a collection. The collection is identified by a short id. All members are living in a namespace that is prefixed with it (uppercased).

Standard Collection ('STD')

This is a heterogenous collection of datatypes which is loaded by default. It contains various issues from CPAN modules (i.e. business, creditcard, email, markup, regexps and etc.) and some everyday things.

Biochemical Collection ('BIO')

Everything that is related to biochemical matters.

Database Collection ('DB')

Common types from databases.

Perl5 Collection ('PERL')

Reserved. Ane day should be filled with things like language elements and name constrains (i.e. a package name).

Perl6 Apocalypse Collection ('PERL6')

Reserved. Placeholder for the Apocalypse and Synopsis 6 suggested datatypes for perl6.

[NOTE] Please consider the same constrains as for CPAN namespaces when using/suggesting a new ID. A short discussion on the sf.net mailinglist is rewarded with gratefullness and respect.

API

FUNCTIONS

valid( $value, @types )

Verifies a 'value' against (one ore more) types or facets. If it isn't belonging to the type a Data::Type::Exception object is thrown (see Data::Type::Exception).

try
{
  valid( 'muenalan<haaar..harr>cpan.org', EMAIL );
}
catch Data::Type::Exception with
{
  dump( $e ) foreach @_;
};

dvalid( $value, @types )

Returns true or false instead of throwing exceptions. This is for the exception haters. For reporting, the exceptions are stored in $Data::Type::err aref.

dvalid( 'muenalan<haaar..harr>cpan.org', EMAIL ) or die dump($Data::Type::err);

is( $type )

Same as dvalid(), but uses $_ instead of $value. This is for syntactic sugar like:

foreach( @nucleotide_samples )
{
  email_to( $SETI ) unless is BIO::DNA;      # Sends "Non terrestric genome found. Suspected sequence '$_'.
}

[Note] Dont take that example to serious. It also could have been simple RNA. Better would have been unless is (BIO::DNA, BIO::RNA).

summary( $value, @types )

Returns the textual representation of the facet set used while the type is verified. Gives you a clou how the type verification process is driven. You can use that to prompt the web user to correct invalid form fields.

print summary( $cc , CREDITCARD( 'VISA' ) );

CLASS METHODS

Data::Type->set_locale( 'id' )

If there is an implemented locale package under Data::Type::L18N::<id>, then you can switch to that langue with this method. Only text that may be promted to an end user are seriously exposed to localization. Developers must live with english.

[Note] Visit the LOCALIZATION section below for extensive information.

LOCALIZATION

All localization is done via Locale::Maketext. The package Data::Type::L18N is the base class, while Data::Type::L18N::<id> is a concrete implementation.

LOCALES

Data::Type::L18N::de

German. Not very complete.

Data::Type::L18N::eng

Complete English dictionary.

And to set to your favorite locale during runtime use the set_locale method of Data::Type (Of course the locale must be implemented).

use Data::Type qw(:all +DB);

  Data::Type->set_locale( 'de' );  # set to german texts

  ...

Visit the "LOCALIZATION" in Data::Type::Docs::Howto section for more on adding your own language.

[Note] Localization is only used for texts which somehow will be prompted to the user vis the summary() functions or an exception. This should help developing, for example, web applications with Data::Type and you simply forward problems to the user in the correct language.

EXPORT

None per default.

FUNCTIONS

is, isnt, valid, dvalid, catalog, toc, summary, try and with.

Exporter sets are:

':all' [qw(is isnt valid dvalid catalog toc summary try with)]

':valid' [qw(is isnt valid dvalid)]

':inspect' [qw(catalog toc summary)]

':try' [qw(try with)]

DATATYPES

You can control the datatypes to be exported with following parameter.

+Uppercase Collection Id (i.e. BIO, DB, ... )

The STD is loaded everytime (And you cannot unload it currently). Currently following collections are available DB, BIO, PERL, PERL6 (see above).

Example:

use Data::Type qw(:all +BIO);	# loads all functions and all datatypes belonging to the BIO collection

use Data::Type qw(:all +DB);	# ..and all datatypes belonging to the DB collection

DATATYPES BY GROUP

PREREQUISITES

• Standard

  Class::Maker (0.05.17)

  Error (0.15)

  IO::Extended (0.05)

  Tie::ListKeyedHash (0.41)

  Data::Iter (0)

  Class::Multimethods (1.70)

  Attribute::Abstract (0.01)

  DBI (1.30)

  Text::TabularDisplay (1.18)

  String::ExpandEscapes (0.01)

• Sorted by type

  /maslib/delayed.mas, comp => '/maslib/prerequisites.mas:type_list'

EXAMPLES

Some examples reside in the t/ and contrib/ directory.

CONTACT

Also http://sf.net/projects/datatype is hosting a projects dedicated to this module. And I enjoy receiving your comments/suggestion/reports also via http://rt.cpan.org or http://testers.cpan.org.

AUTHOR

Murat Uenalan, <muenalan@cpan.org>

SEE ALSO

All the basic are described at Data::Type::Docs. It also navigates you through the rest of the documentation.

Data::Type::Docs::FAQ, Data::Type::Docs::FOP, Data::Type::Docs::Howto, Data::Type::Docs::RFC, Data::Type::Facet, Data::Type::Filter, Data::Type::Query, Data::Type::Collection::Std

And these CPAN modules:

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, WWW::Form

W3C XML Schema datatypes

http://www.w3.org/TR/xmlschema-2/

Synopsis 6 by Damian Conway, Allison Randal

http://www.perl.com/pub/a/2003/04/09/synopsis.html?page=3

cpanm Data::Type

perl -MCPAN -e shell
install Data::Type