NAME
Data::Type::RFC - request for comments on the design of Data::Type
REVISION
$Revision: 1.1 $
SYNOPSIS
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' }
DESCRIPTION
This is the API documentation. Every candidate datatype must be sustain the following conventions before it should be released. Comments are requested.
CONVENTIONS
- HANDLING REGEXPS
-
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. - PACKAGE NAMING
-
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.[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:verify 123123, MY::ANY;
- COLLECTION ID
-
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.
- THROWING EXCEPTIONS
-
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.
INTERFACE Data::Type::Object::Interface
The abstract interface for all Data::Type::Object
s. Is inherited by the collection interface Data::Type::Collection::*::Interface.
SYNOPSIS
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] ) );
}
}
VARIABLES
our @ISA
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.
our $VERSION
Data::Type version at the last modification of that type.
METHODS
$dt->desc
$str = $dt->desc
$str
is a text describing the purpose of the type.
$dt->doc
$str = $dt->doc
$str
with some sort of "manpage" for this type.
$dt->pod
$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->summary( [ ARGS ] )
$str = $dt->summary( [ ARGS ] )
@entries = $dt->summary( [ ARGS ] )
This method is inherited from Data::Type::Object::Interface.
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).
$dt->info
$str = $dt->info
$str
is a text containg add-on information to that from $dt->doc
or $dt->desc
.
$dt->usage
$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.
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
}
$dt->_test
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()
.
[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.
$dt->_filters
$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:
sub _filters { ( [ 'chomp' ], [ 'strip', '\s' ] ) }
The names are valid filter ids as elaborated in Data::Type::Filter.
$dt->choice
$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 );
$dt->choice_as_text
$str = $dt->choice_as_text
$str
is a text formatted for direct output:
printf 'Please select [choice: %s ]', $dt->choice_as_text;
$dt->param
$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.
$dt->default
If some default value for $dt->param
exists, they should be returned by this function.
$dt->basic_depends
@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.
Array of required modules for a collection of types (for instance CPAN modules).
[Note] Used to build a dependency tree.
$dt->depends
@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.
Array of required modules for a single type (for instance CPAN modules).
$dt->to_text
$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->cast( $dt )
$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.
$dt->prefix
$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
.
This method can be used to overload the automatic export name scheme with some individual.
[Note] Only used if absolutely needed.
$dt->export
@aliases = $dt->export
If not implemented it generates an automatic name via uppercasing the packagenames last part (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.
$dt->exported
@aliases = $dt->exported
Array of alias's for that type, including a prefix if this type is part of a collection.
INTERFACE Data::Type::Collection::<ID>::Interface
SYNOPSIS
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' }
VARIABLES
our @ISA
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.
our $VERSION
Should hold the value of the Data::Type version at the last modification.
METHODS
$dtc->prefix
$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.
$dtc->pkg_prefix
$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.
$dtc->desc
$str = $dtc->desc
A representative short headline for the collection.
$dtc->doc
$str = $dtc->doc
A complete documentation for the collection.
[Note] Used by the authors automatic documentation system.
INTERFACE Data::Type::Facet::Interface
VARIABLES
our $VERSION
Should hold the value of the Data::Type version at the last modification.
METHODS
$dtf->test
This method throws a Data::Type::Exception.
Holds the logic of type validation. Must use Data::Type::ok() to dispatch public and private facets.
$dtf->desc
$str = $dtf->desc
A scalar describing the purpose of the facet.
$dtf->info
$str = $dtf->info
$str
should be a static string with supportive information.
$dtf->usage
$str = $dtf->usage
Shell commando like usage. Must precisly describe every argument in the text $str
. See $dt->usage for explicit instructions.
CONTACT
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.
AUTHOR
Murat Uenalan, <muenalan@cpan.org>
3 POD Errors
The following errors were encountered while parsing the POD:
- Around line 162:
Unterminated C<...> sequence
- Around line 223:
Nested L<> are illegal. Pretending inner one is X<...> so can continue looking for other errors.
- Around line 294:
Unterminated C<...> sequence