/ 
Class-PINT-0.01
River stage zero No dependents
/ Class::PINT

NAME

Class::PINT - A Class::DBI package providing Tangram and other OOPF features

DESCRIPTION

Class::PINT is an implementation of selected Tangram, and other OOPF related features on top of Class::DBI.

The goal of PINT is to provide some of the power and flexibility of Tangram with the maturity, transparency and extensibility of CDBI. I also hope we can provide a place where more useful and adventurous patchs, subclasses and plugins can be organised and integrated into a usable package.

Class::PINT uses CDBI to generate general purpose accessors, mutators and constructor methods. CDBI also provides simple relationships. Additional Accessors/Mutators and relationships are added to handle more complex types of attributes and relationships.

SYNOPSIS

Class

package Address;

use base qw(Class::PINT);

__PACKAGE__->connection('dbi:mysql:database', 'username', 'password');

__PACKAGE__->column_types(array => qw/StreetAddress/);

__PACKAGE__->columns(All => qw/addressid StreetNumber StreetAddress Town City County/);

...

Application

use Address;

my $address = Address->create({StreetNumber => 108,
                               StreetAddress => ['Rose Court','Cross St'],
                               Town=>'Berkhamsted',
                               County=>'Hertfordshire'});

my $county_string = $address->get_County; # read-only 'pure' accessor

$address->set_City('Watford'); # write only mutator

my $streetaddress_1 = $address->get_StreetAddress(0); # access array attribute

my $attribute_foo = $object->get_Attribute('foo'); # element of hash attribute

METHODS

CLASS METHODS

Inherited from Class::DBI, doesn't support compound attributes. This method will be over-ridden to handle complex attributes and relationships later. Boolean Attributes should still work with this method.

see Class::DBI

search_like

Inherited from Class::DBI, doesn't support compound attributes. This method will be over-ridden to handle complex attributes and relationships later.

see Class::DBI

search_where

Inherited from Class::DBI::AbstractSearch, doesn't support compound attributes yet, but will be over-ridden to handle them later.

see Class::DBI::AbstractSearch

column_types

You need to specifiy the details of the connection and the names of the attributes using the connection and columns methods respectively - see Class::DBI for more details - before setting the column types

You can specify the type of attributes using column_types class method, which takes the column type and the attributes of that type much like the CDBI columns method.

__PACKAGE__->column_types(array => qw/StreetAddress/);

supported attribute types are :

array

Array attributes are ordered lists that can be accessed in their entirety, using normal accessors/mutators or individual elements or groups of elements.

hash

Hash attributes are keyed lists that can be accessed in their entirety, using normal accessors/mutators or individual elements or groups of elements using a key.

boolean

Boolean attributes are a single integer of 0 or 1. The attribute can then be set or read using normal accessors/mutators or additional methods such as Attribute_is_False or is_Attribute.

column_rules

The column_rules method allows you to specify rules for attributes for validation, etc. This also enables you to add behaviour for events called by triggers in the accessor and mutators. You need to specify any column_types before specifying any column rules.

You can specify default behaviour by specifying the datatype of an attribute, such as an integer. This method attempts to provide some of the benefits of Tangram style schema as seen in Class::Tangram.

Specifying rules explicitly, and commenting them, make the objects behaviour much clearer while reducing the ammount of code written for sundry tasks.

Address->column_rules( integer => [qw/count .. /] );

or

Address->column_rules( integer => { count => { required => 1 }, .. );

You can also specify more detailed rules yourself :

GeometricShape->column_rules( custom => {
                                          theta => {
                                                     check => $coderef,
                                                     required => 1,
                                                     ...
                                                    },
                                        }, .. );

Rules can be any of string, integer, float, reference, or object. Each with simple, and hopefully, sensible default rules that can be over-ridden individually.

string

The default validation for strings is to check that it is a scalar and not a reference to something.

integer

The default validation for an integer is that it is a string made up purely of digits, none of those greek symbols or other beardy-wierdy, white socks and sandals nonsense. OK, you can have a + or - at the start, but thats it.

float

A floating point number, thats some digits possibly with a decimal point in between them or at the start, again you can start with a + or - but none of that scientific notation with a mantissa and all that malarky.

reference

A reference to something, it can even be a reference to another reference, just so long as its a reference, you can specify the type of reference with reference_to - see below.

object

An object, which is essentially a blessed reference, you can specify that the object is of a particular type, inherits from or implements a method - see below.

All rules allow you to specify particular behavour for each attribute, these behaviours include validation, defaults, requirements and triggered actions.

check

Allows you to provide a sub or coderef that will be called to validate the value of this attribute. The sub is passed the object and the new value for that attribute.

required

Allows you to specify if an attribute is a required value, it can be passed 1, 0 or a hashref specifying whether to die or warn and the message to output to stderr.

default

Allows you to provide a default value for an attribute, this can be a value, sub or coderef that populates the attribute. Subs are passed the object.

before_update

Allows you to provide a sub or coderef that is called before a value is updated, handy for tracking changes.

after_update

Allows you to provide a sub or coderef that is called after a value is updated, handy for something, surely.

object_can

When used in the object rule, allows you to require that an attribute is set to an object that implements the method named

object_isa

When used in the object rule, allows you to require that an attribute is set to an object that inherits from the class named

reference_to

When used in the reference or object rule, allows you to require that an attribute is a reference to something.

NOTE: when applying rules to compound or complex attributes, the rules apply to each applicable part of the attributes values.

CONSTRUCTORS

my $object = Address->create({StreetNumber=>108,
                              StreetAddress=>['Rose Court','Cross St'],
                              Town=>'Berkhamsted',
                              County=>'Hertfordshire'});

ACCESSORS

This superclass attempts to make accessing and modifying object attributes as clear and predictable as possible.

my $county_string = $address->get_County; # read-only 'pure' accessor

my $first_line_of_streetaddress = $address->get_StreetAddress(0);

to get elements 0 to 8 of attribute Foo

$object->get_Foo(0..8);

MUTATORS

Class::PINT provides 2 forms of Mutator - get/set and write-only. get/set is the default method named after the attribute such as :

$object->AttributeName($newvalue)

The write-only method is explictly named as set_AttributeName :

$object->set_AttributeName($newvalue)

You can also delete an attribute using

$object->delete($attribute_name) or $object->delete_AttributeName()

ADDITIONAL ATTRIBUTE METHODS

When you have specified an attributes type using column_types() there are additional ways to access them.

Array attribute methods

Array or Ordered List attributes support get,set and get/set accessor/mutators, as well as: insert_AttributeName, delete_AttributeName, push_AttributeName, pop_AttributeName. These attributes also have provide additional behaviour to the get/set and set methods.

see Class::PINT::DataTypes::Array (todo)

Hash attribute methods

Hash or Keyed List attributes support get,set and get/set accessor/mutators, as well as: insert_AttributeName, delete_AttributeName, includes_AttributeName.

see Class::PINT::DataTypes::Hash (todo)

Boolean attribute methods

Boolean attributes support get,set and get/set accessor/mutators, as well as: is_AttributeName, AttributeName_is_true, AttributeName_is_false, AttributeName_is_defined.

see Class::PINT::DataTypes::Boolean (todo)

SEE ALSO

perl

Class::DBI

Tangram

Class::Tangram

Class::PINT::DataTypes

AUTHOR

Aaron J. Trevena, <aaron@droogs.org>

COPYRIGHT

Licensed for use, modification and distribution under the Artistic and GNU GPL licenses.

Copyright (C) 2004 by Aaron J Trevena <aaron@droogs.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.