NAME

Value - base class for value types for the Oryx object persistence tool

SYNOPSIS

 # constructor - this is what you should do
 tie $obj->{some_field}, 'Oryx::Value::SomeType', ($meta, $owner);
  
 # this is if you really must call these methods on the tied object
 # although normally these are called by the tied object on $self
 tied($obj->{some_field})->deflate($value);
 tied($obj->{some_field})->inflate($value);
 tied($obj->{some_field})->check($value);
 tied($obj->{some_field})->check_required($value);
 tied($obj->{some_field})->check_type($value);
 tied($obj->{some_field})->check_size($value);
 tied($obj->{some_field})->meta;
 tied($obj->{some_field})->owner;

DESCRIPTION

This module is considered abstract and should be sublcassed to create the actual Value types.

The purpose of these Value types is to validate input and to prepare field values for storage in the database via the "deflate" method and to prepare the values for consumption after retrieval via the "inflate" method.

The tie constructor is passed the associated Oryx::Attribute instance which can be accessed via "meta", along with the Oryx::Class instance to which the Attribute - and therefore the value - belongs. The Oryx::Class instance can be accessed with the "owner" accessor.

SUBCLASSING

The "tie" related methods: "TIESCALAR", "STORE" and "FETCH", as well as "VALUE" should not be overridden when subclassing - they are documented here for the sake of completeness.

The "inflate", "deflate", "check_thing", and "primitive" methods are usually overloaded when subclassing.

METHODS

TIESCALAR( $meta, $owner )

takes two arguments: $meta and $owner - $meta is the Oryx::Attribute instance with which this value is associated, and $owner is the Oryx::Class instance (or persistent object).

This method should not be called directly, instead use

 my $attr_name = $attrib->name;
 tie $object->{$attr_name}, 'Oryx::Value::String', $attrib, $object;
    

FETCH

automatically called by Perl when the field to which this Value is tied is retrieved. You should not normally need to call this directly.

STORE( $value )

automatically called by Perl when the field to which this Value is tied is set via assignment. You should not normally need to call this directly.

VALUE

mutator to the internal raw value held in this tied object instance

deflate( $value )

hook to modify the value before it is stored in the db. $value is the raw value associated with the attribute as it is in the live object. This is not neccessarily the same as its representation in the database. Take Oryx::Value::Complex for example. Complex serializes its value using YAML before it saves it to the database. "deflate" does the serialization in this case. It is passed the value in the live object which could be a hash ref or array ref (or anything else that could be serialized using YAML) and returns the serialized YAML string representation of that value.

inflate( $value )

hook to modify the value as it is loaded from the db. This is the complement to "deflate" in that it takes the value loaded from the database and cooks it before it is associated with the attribute of the live "Oryx::Class" object.

In the case of Oryx::Value::Complex $value is a YAML string which is deserialized using YAML and the result returned.

check( $value )

hook for checking the value before it is set. You should consider carefully if you need to override this method as this one calls the other "check_thing" methods and sets "$self->errstr" if any of them fail.

check_type( $value )

hook for doing type checking on the passed $value. Should return 1 if successful and 0 if not.

check_size( $value )

hook for doing size checking on the passed $value. Should return 1 if successful and 0 if not.

check_required( $value )

hook for checking if the passed $value is required. Should return 1 if the value is required and defined and 0 if required and not defined. If the value is not required, return 1.

errstr

returns the error string if input checks failed.

meta

simple accessor to meta data for this value type, in this case, a reference to the Oryx::Attribute with which this Value instance is associated.

owner

returns the Oryx::Class which owns the Oryx::Attribute instance with which this Value instance is associated.

primitive

Returns a string representing the underlying primitive type. This is used by the storage driver to determine how to pick the data type to use to store the value. The possible values include:

AUTHOR

Copyright (C) 2005 Richard Hundt <richard NO SPAM AT protea-systems.com>

LICENCE

This library is free software and may be used under the same terms as Perl itself.