Data::Type::RFC - request for comments on the design of Data::Type
$Revision: 1.1 $
package Data::Type::Object::std_myfirst; our @ISA = qw(Data::Type::Collection::Std::Interface::Numeric); # interface of the Collection (one or many of many) our $VERSION = '0.01.25'; # last modified in version of Data::Type sub desc : method { 'boolean value' } sub info : method { $this = shift; # @$this are the arguments return sprintf '%s value', $this->[0] || 'true or false'; } sub _test : method { $this = shift; # @$this are the arguments throw Data::Type::Exception->new( text => 'demo exception' ) if $Data::Type::value =~ /throwme/; if( $this->[0] eq 'true' ) { Data::Type::ok( 1, Data::Type::Facet::bool( $this->[0] ) ); } else { Data::Type::ok( 0, Data::Type::Facet::bool( $this->[0] ) ); } } package Data::Type::Collection::Std::Interface; our @ISA = qw(Data::Type::Object::Interface); our $VERSION = '0.01.25'; sub prefix : method {'Std::'} sub pkg_prefix : method {'std_'} sub desc : method { 'Standard' } sub doc : method { 'The standard numeric interface' }
This is the API documentation. Every candidate datatype must be sustain the following conventions before it should be released. Comments are requested.
All regexps are handles by Regexp::Box. Data::Type has $Data::Type::rebox where all must be registered if they should be available to the match facet (see Data::Type::Facet). One is really encourages to use the box for all regexps so they are available to Data::Type::Query and to the facets. Just the really trivial/private one which just make sense in its very singular context should be used as plain regexps.
$Data::Type::rebox
All datatypes live in the Data::Type::Object::<name> namespace. To prevent namespace conflicts between collections, the <name> part should be formated like $collection_id.'_'.$datatype_name. Example: bio_dna.
$collection_id.'_'.$datatype_name
[Note] Per convention <name> must be lowercased and the collection id uppercased. For example Data::Type::Object::any in the MY collection would later called as:
Data::Type::Object::any
verify 123123, MY::ANY;
The collection id should be arround 3 characters.
[Note] Carefull with reserved or used ids! Public discussion (at the mailing-list/sourceforge site below) is recommended.
It is from primary importance that at documented exceptions are thrown. Mostly this is in the $dt-test()> method. Otherwise nothing will work as expected.
The abstract interface for all Data::Type::Objects. Is inherited by the collection interface Data::Type::Collection::*::Interface.
Data::Type::Object
package Data::Type::Object::std_myfirst; our @ISA = qw(Data::Type::Collection::Std::Interface::Numeric); # interface of the Collection (one or many of many) our $VERSION = '0.01.25'; # last modified in version of Data::Type sub desc : method { 'boolean value' } sub info : method { $this = shift; # @$this are the arguments return sprintf '%s value', $this->[0] || 'true or false'; } sub _test : method { $this = shift; # @$this are the arguments throw Data::Type::Exception->new( text => 'demo exception' ) if $Data::Type::value =~ /throwme/; if( $this->[0] eq 'true' ) { Data::Type::ok( 1, Data::Type::Facet::bool( $this->[0] ) ); } else { Data::Type::ok( 0, Data::Type::Facet::bool( $this->[0] ) ); } }
Normal inheritance mechanism. So a collection can inherit from another collection. The isa tree is also used to build a comprehensive hierarchy chart for the documentation.
Data::Type version at the last modification of that type.
$str = $dt->desc
$str is a text describing the purpose of the type.
$str
$str = $dt->doc
$str with some sort of "manpage" for this type.
$str = $dt->pod
This method is inherited from Data::Type::Object::Interface.
$str is a text pod of $dt->doc. Constructs a string assembled by the information from other methods like usage etc.
$dt->doc. Constructs a string assembled by the information from other methods like usage etc.
$str = $dt->summary( [ ARGS ] ) @entries = $dt->summary( [ ARGS ] )
Dispatches the summary() function as a method. In scalar context it returns a complete paragraph of plain text.
In list context @entries are returned. Is is an array of Data::Type::Entry objects (as the summary() does in general).
@entries
$str = $dt->info
$str is a text containg add-on information to that from $dt->doc or $dt->desc.
$dt->doc
$dt->desc
$str = $dt->usage
Similar to a shell command usage with options and instructions how to invoke it. Use following annotation for arguments:
[...] - arguments inside the brackets are optional (...|...|...) - choose one of the arguments separated by the bars {...} - you can specify the braced argument ZERO or more times {...}+ - you can specify the braced argument ONE or more times
[Note] Arguments may be given an ID which just identifies it within the scope of the usage documentation. If the argument shall be give a datatype constrain it is followed by an as MY::TYPE idiom.
as MY::TYPE
In the line below the usage states that STD::VARCHAR has the optional argument SIZE (which requires to be STD::NUM:
STD::VARCHAR( [SIZE as STD::NUM] )
That means that following valid perl lines will not raise an usage exception:
die unless is STD::VARCHAR; # default is 8 die unless is STD::VARCHAR( 90 ) # 90 is valid, because it is a STD::NUM
Return a string containing the usage documenation en block. This is a complete usage:
sub usage : method { return <<END_HERE; STD::VARCHAR( [SIZE as STD::NUM] ) SIZE sets the upper limit for the string. END_HERE }
This method throws a Data::Type::Exception.
Genereally implements the main logic of a datatype. Must use Data::Type::ok() to dispatch public and private facets. See also Data::Type::ok().
Data::Type::ok()
[Important] $Data::Type::value is a global containing the first argument given to valid() (i.e. the test value). It is not delived as an argument.
$aref = $dt->_filters
$aref is the list of filters applied to the value in question before subjected to the testing ($dt->_test method). For example:
$aref
$dt->_test
sub _filters { ( [ 'chomp' ], [ 'strip', '\s' ] ) }
The names are valid filter ids as elaborated in Data::Type::Filter.
$aref = $dt->choice
$aref is data of alternativ choices when an inputfield is generated for this type. An inputfield is still ill defined, but Data::Type::Field is planned to generate on-the-fly shell- or webform input fields.
printf 'Please select [choice: %s ]', join( ', ', $aref );
$str = $dt->choice_as_text
$str is a text formatted for direct output:
printf 'Please select [choice: %s ]', $dt->choice_as_text;
$aref = $dt->param
Must be called within any other of this methods to access default arguments. Any static parts of a test (like locale information) should be return by this method. This helps porting and extending a type.
Returns a data structure used for the configuration/parameterization of the datatype.
If some default value for $dt->param exists, they should be returned by this function.
$dt->param
@modules = $dt->basic_depends
This method should be implemented only by the Data::Type::Collection::*::Interface interface. The @modules returned by this function are loaded at runtime during access of any collection member.
@modules
Array of required modules for a collection of types (for instance CPAN modules).
[Note] Used to build a dependency tree.
@modules = $dt->depends
@modules are loaded at runtime during first access to its type.
[Note] This information is used to bundle Data::Type with the right Makefile.PL information. In future this could be also exploited for runtime loading of modules only for actually used types.
Data::Type
Makefile.PL
Array of required modules for a single type (for instance CPAN modules).
$str = $dt->to_text
Should generate a string $str which could be evalled and would revive the state of the type. This would be usefull for some sort of simple and readable persistance (ie. in config files or web forms).
$scalar = STD::VARCHAR(80)->to_string; # should return "STD::VARCHAR( 80 )" eval $scalar;
[Note] The state is a mix of $dt->param and $dt->default. Currently no datatype supports it.
$dt->param and $dt->default. Currently no datatype supports it.
$dt->default
$now_b_was_a = $dt_a->cast( $dt_b );
API for casting of types.
[Note] Class::Multimethods may be used for dispatching multiple cast methods.
Returns the casted destination type $now_b_was_a or undef if cast wasnt possible.
$now_b_was_a
$str = $dt->prefix
This should be implemented by an Data::Type::Collection::*::Interface class which is then used when generating the final exportname with exported.
exported
This method can be used to overload the automatic export name scheme with some individual.
[Note] Only used if absolutely needed.
@aliases = $dt->export
If not implemented it generates an automatic name via uppercasing the packagenames last part (Data::Type::_package_to_name).
Data::Type::_package_to_name
package Data::Type::Object::bio_atom; sub export { qw(ATOM ELEMENT) } # part of the BIO collection, would make this type available as BIO::ATOM and BIO::ELEMENT
Returns an array of alias's for that type.
@aliases = $dt->exported
Array of alias's for that type, including a prefix if this type is part of a collection.
package Data::Type::Collection::Std::Interface; our @ISA = qw(Data::Type::Object::Interface); our $VERSION = '0.01.25'; sub prefix : method {'Std::'} sub pkg_prefix : method {'std_'} sub desc : method { 'Standard' } sub doc : method { 'The standard numeric interface' }
Should hold the value of the Data::Type version at the last modification.
$str = $dtc->prefix
The heading part of the package name. Prefixed to all types of that collection.
STD::NUM
where 'STD::' was the prefix added to the 'NUM' type.
$str = $dtc->pkg_prefix
Because all types, no matter which collection, are living the in the same namespace the require a unique name. So it is required practice to put a prefix to the package name.
package Data::Type::Object::db_set; package Data::Type::Object::std_set;
So here the 'set' datatype is protected from ambiguity via prefixing it with the collection pkg_prefix.
$str = $dtc->desc
A representative short headline for the collection.
$str = $dtc->doc
A complete documentation for the collection.
[Note] Used by the authors automatic documentation system.
Holds the logic of type validation. Must use Data::Type::ok() to dispatch public and private facets.
$str = $dtf->desc
A scalar describing the purpose of the facet.
$str = $dtf->info
$str should be a static string with supportive information.
$str = $dtf->usage
Shell commando like usage. Must precisly describe every argument in the text $str. See $dt->usage for explicit instructions.
Sourceforge http://sf.net/projects/datatype is hosting a project dedicated to this module. And I enjoy receiving your comments/suggestion/reports also via http://rt.cpan.org or http://testers.cpan.org.
Murat Uenalan, <muenalan@cpan.org>
3 POD Errors
The following errors were encountered while parsing the POD:
Unterminated C<...> sequence
Nested L<> are illegal. Pretending inner one is X<...> so can continue looking for other errors.
To install Data::Type, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Type
CPAN shell
perl -MCPAN -e shell install Data::Type
For more information on module installation, please visit the detailed CPAN module installation guide.