The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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::Objects. 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