/ 
Class-Tangram-1.04
River stage one • 1 direct dependent • 1 total dependent
/ Class::Tangram

NAME

Class::Tangram - create constructors, accessor and update methods for objects from a Tangram-compatible object specification.

SYNOPSIS

package Orange;

use base qw(Class::Tangram);
use vars qw($schema);
use Tangram::Ref;

# define the schema (ie, allowed attributes) of this object.  See the
# Tangram::Schema man page for more information on the syntax here.
$schema = {
    table => "oranges",

    fields => {
        int => {
            juiciness => undef,
            segments => {
                # here is a new one - this code reference is called
                # when this attribute is set; it should die() on
                # error, as it is wrapped in an eval { } block
                check_func => sub {
                    die "too many segments"
                        if ($ {$_[0]} > 30);
                },
                # the default for this attribute.
                init_default => 7,
            },
        },
        ref => {
            grower => undef,
        },
    },
};
Class::Tangram::import_schema("Orange");

package Project;
# here's where we build the individual object schemas into a
# Tangram::Schema object, which the Tangram::Storage class uses to
# know which tables and columns to find objects.
use Tangram::Schema;

my $dbschema = Tangram::Schema->new
    ({ classes => [ 'Orange' => $Orange::schema ]});

sub schema { $dbschema };

package main;

# See Tangram::Relational for instructions on using "deploy" to
# create the database this connects to.  You only have to do this if
# you want to write the objects to a database.
use Tangram::Relational;
my ($dsn, $u, $p);
my $storage = Tangram::Relational->connect(Project->schema,
                                           $dsn, $u, $p);

# OK
my $orange = Orange->new(juiciness => 8);
my $juiciness = $orange->juiciness;   # returns 8

# a "ref" must be set to a blessed object
my $grower = bless { name => "Joe" }, "Farmer";
$orange->set_grower ($grower);

# these are all illegal
eval { $orange->set_juiciness ("Yum"); }; print $@;
eval { $orange->set_segments (31); }; print $@;
eval { $orange->set_grower ("Mr. Nice"); }; print $@;

# if you prefer
$orange->get( "juiciness" );
$orange->set( juiciness => 123 );

DESCRIPTION

Class::Tangram is a base class originally intended for use with Tangram objects, that gives you free constructors, access methods, update methods, and a destructor that should help in breaking circular references for you. Type checking is achieved by parsing the schema for the object, which is contained within the object class in an exported variable $schema.

After writing this I found that it was useful for merely adding type checking and validation to arbitrary objects. There are several modules on CPAN to do that already, but many don't have finely grained type checking, and none of them integrated with Tangram.

METHODS

Class->new (attribute1 => value, attribute2 => value)

sets up a new object of type Class, with attributes set to the values supplied.

Can also be used as an object method, in which case it returns a copy of the object, without any deep copying.

$instance->set(attribute => $value, ...)

Sets the attributes of the given instance to the given values. croaks if there is a problem with the values.

$instance->get($attribute)

Gets the value of $attribute. If the attribute in question is a set, and this method is called in list context, then it returns the MEMBERS of the set (if called in scalar context, it returns the Set::Object container).

$instance->attribute($value)

If $value is not given, then this is equivalent to $instance->get("attribute")

If $value is given, then this is equivalent to $instance->set("attribute", $value). This usage issues a warning; you should change your code to use the set_attribute syntax for better readability.

$instance->get_attribute
$instance->set_attribute($value)

Equivalent to $instance->get("attribute") and $instance->set(attribute => $value), respectively.

$instance->attribute_includes(@objects)
$instance->attribute_insert(@objects)
$instance->attribute_size
$instance->attribute_clear
$instance->attribute_remove(@objects)

Equivalent to calling $instance->attribute->includes(@objects), etc. This only works if the attribute in question is a Set::Object.

$instance->getset($attribute, $value)

If you're replacing the AUTOLOAD function in your Class::Tangram derived class, but would still like to use the behaviour for one or two fields, then you can define functions for them to fall through to the Class::Tangram method, like so:

sub attribute { $_[0]->SUPER::getset("attribute", $_[1]) }
check_X (\$value)

This series of functions checks that $value is of the type X, and within applicable bounds. If there is a problem, then it will croak() the error. These functions are not called from the code, but by the set() method on a particular attribute.

Available functions are:

check_string - checks that the supplied value is less
               than 255 characters long.
check_int    - checks that the value is a (possibly
               signed) integer
check_real   - checks that the value is a real number
               (m/^\d*(\.\d*)?(e\d*)?$/)
check_obj    - checks that the supplied variable is a
               reference to a blessed object
check_flat_array
             - checks that $value is a ref ARRAY
check_array  - checks that $value is a ref ARRAY, and that
               each element in the array is a reference to
               a blessed object.
check_set    - checks that $value->isa("Set::Object")
check_rawdatetime 
             - checks that $value is of the form
               YYYY-MM-DD HH:MM:SS
check_time
            - checks that $value is of the form
              HH:MM(:SS)?
check_timestamp
            - checks that $value is of the form
              (YYYY-MM-DD )?HH:MM(:SS)?
check_flat_hash
             - checks that $value is a ref HASH
check_hash   - checks that $value is a ref HASH, that
               every key in the hash is a scalar, and that
               every value is a blessed object.
check_nothing - checks whether Australians like sport
destroy_X ($instance, $attr)

Similar story with the check_X series of functions, these are called during object destruction on every attribute that has a reference that might need breaking. Note: these functions all assume that attributes belonging to an object that is being destroyed may be destroyed also. In other words, do not allow distinct objects to share Set::Object containers or hash references in their attributes, otherwise when one gets destroyed the others will lose their data.

Available functions are:

destroy_array - empties an array
destroy_set   - calls Set::Object::clear to clear the set
destroy_hash  - empties a hash
destroy_ref   - destroys a reference.  Contains a hack for
                Tangram so that if this ref is not loaded,
                it will not be autoloaded when it is
                attempted to be accessed.
parse_X ($attribute, { schema option })

Parses the schema option field, and returns one or two closures that act as a check_X and a destroy_X function for the attribute.

This is currently a very ugly hack, parsing the SQL type definition of an object. But it was bloody handy in my case for hacking this in quickly. This is unmanagably unportable across databases. This should be replaced by primitives that go the other way, building the SQL type definition from a more abstract definition of the type.

Available functions:

parse_string  - parses SQL types of:
CHAR(N), VARCHAR(N)
    closure checks length of string is less
    than N characters
TINYBLOB, BLOB, LONGBLOB
TINYTEXT, TEXT, LONGTEXT
    checks max. length of string to be 255,
    65535 or 16777215 chars respectively
SET("members", "of", "set")
    checks that the value passed is valid as
    a SQL set type, and that all of the 
    passed values are allowed to be a member
    of that set
ENUM("possible", "values")
    checks that the value passed is one of
    the allowed values.
import_schema($class)

Parses a tangram object schema, in "\$${class}::schema" to the internal representation used to check types values by set(). Called automatically on the first get(), set(), or new() for an object of a given class.

This function updates Tangram schema option hashes, with the following keys:

check_func   - supply/override the check_X function for
               this attribute.

destroy_func - supply/override the destroy_X function for
               this attribute

See the SYNOPSIS section for an example of supplying a check_func in an object schema.

$instance->quickdump

Quickly show the blessed hash of an object, without descending into it. Primarily useful when you have a large interconnected graph of objects so don't want to use the x command within the debugger. It also doesn't have the side effect of auto-vivifying members.

This function returns a string, suitable for print()ing. It does not currently escape unprintable characters.

$instance->DESTROY

This function ensures that all of your attributes have their destructors called. It calls the destroy_X function for attributes that have it defined, if that attribute exists in the instance that we are destroying. It calls the destroy_X functions as destroy_X($self, $k)

$instance->clear_refs

This clears all references from this object, ie exactly what DESTROY normally does, but calling an object's destructor method directly is bad form. Also, this function has no qualms with loading the class' schema with import_schema() as needed.

This is useful for breaking circular references, if you know you are no longer going to be using an object then you can call this method, which in many cases will end up cleaning up most of the objects you want to get rid of.

However, it still won't do anything about Tangram's internal reference to the object, which must still be explicitly unlinked with the Tangram::Storage->unload method.

SEE ALSO

Tangram::Schema

A guided tour of Tangram, by Sound Object Logic.

http://www.soundobjectlogic.com/tangram/guided_tour/fs.html

BUGS/TODO

More datetime types. I originally avoided the DMDateTime type because Date::Manip is self-admittedly the most bloated module on CPAN, and I didn't want to be seen encouraging it. Then I found out about autosplit :-}.

More AUTOLOAD methods, in particular for container types such as array, hash, etc.

This documentation should be easy enough for a fool to understand.

There should be more functions for breaking loops; in particular, a standard function called drop_refs($obj), which replaces references to $obj with the appropriate Tangram::RefOnDemand so that an object can be unloaded via Tangram::Storage->unload() and actually have a hope of being reclaimed. Another function that would be handy would be a deep "mark" operation for mark & sweep garbage collection.

AUTHOR

Sam Vilain, <sam@vilain.net>