/ 
Data-Type-0.01.15
River stage zero No dependents
/ Data::Type::Docs

NAME

Data::Type::Docs - the manual overview

MANUALS

Data::Type::Docs::FAQ

Frequently asked questions.

Data::Type::Docs::FOP

Frequently occuring problems.

Data::Type::Docs::Howto

Point to point recipes how to get things done.

Data::Type::Docs::RFC

Exact API description. Startpoint for datatype developers.

NAVIGATION

First read the following paragraphs and then you may start study the Data::Type API.

CONCEPTS & TERMINOLOGY

Because the subject is so stuffed with uncommon or not entry level 'keywords', here a short list of what is what.

COMMON
'facade' or 'wrapper'

Sometimes classes have a weird API (of course, because personal taste). Unfortunately the logic behind is highly usefull (thats what CPAN is strong in) and you want invest time to rework everything. Then you can write a cleaner API for that class that just use the original class in it. Or this may be usefull to easily switch the "worker" class behind your newly one (thats a facade then).

'exception'

An alternativ "problem encounter" strategie. Instead of returning undef from you subroutine, you throw an exception. Not the strongest point of perl5. But there are some modules on CPAN which try to do the best of it. The one with the nicest syntactic sugar is Error and i use the derived Class::Maker::Exception here.

'interface'

A collection of methods which are coupled to a package. Some methods have the attribute abstract. This means there is just the name (and idea of what it should do in general) of the method, but you are forced to program the subroutine to fill it with logic. Then you "implemented" the abstract method.

SPECIFIC
'valuetype'

A candidate value is tested whether it fits within in a certain range of values (the value space). The thing/objects/class/package that represents and implements the logic of the value space is the valuetype.

'datatype'

This is something more abstract. Within this documentation i refer to datatypes, but mostly mean valuetypes. From a practical point of view one could propagate that a datatype excels over a valuetype when it has the ability to be cast()ed from one datatype into another. Some say a datatype should relate to physical boundaries of the computer (like bits, bytes, etc.). In fact the old datatypes were more usefull for a compilers optimizer then for the programmer.

[Note] Apocalypse 6 (Larry Wall) and Synopsis 6 (Damian Conway, Allison Randal) issue this intensivly.

'facet'

A value space can contain many facets. Facets are the building blocks of any value space. Matching a regex, beeing not undef, the size of a string can be a facet. Sticking to this concept, you have high level of code reuse and it helps to debug problem during testing a value against a value space. Because many datatypes share a common set of characterstics, facets can be reused. The implementation of the summary() function requires facets (summary()).

'anonymous or private facet' The implemention of summary required use of facets. Even they arent very reusable by other datatypes. For this you should create <anonymous facets> or private facets. Per convention there names start with '__'. Example:
{
  package Data::Type::Object::email;

  {
    package Data::Type::Facet::__email;
  
  }

  sub test : method
  {
     Data::Type::ok( 1, Data::Type::Facet::__email() );
  }
}

[Note] I really recommend this.

'filter'

This is just a cleanser. It reformats or removes insignficant parts of the initial value. Like stripping whitespaces or modifying cases.

'collection'

Within this distribution a collection is just a namespace. They reside undes Data::Type::Collection::<name>. They group certain datatypes into a homogeneous collection with an unified interface and behaviour. It has also a common prefix for the datatype qualification i.e. Datatypes belonging to the W3C collection begin with W3C::. With use Data::Type ':all +W3C' (note: unimplemented yet) you can load additional collections which arent loaded by default (Only the 'Std' collection is loaded by default).

[Note] This module should have been Value::Type, but i stick to Data::Type until i get doomed.

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>