The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Class-Tangram-1.06
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.

DEPENDENCIES

The following modules are required to be installed to use Class::Tangram:

   Set::Object => 1.02
   Pod::Constants => 0.11
   Test::Simple => 0.18

Test::Simple is only required to run the test suite.

MODULE RELEASE

This is Class::Tangram version 1.06.

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.

Run-time type information

It is possible to access the data structures that Class::Tangram uses internally to verify attributes, create objects and so on.

Class::Tangram keeps six internal hashes:

%types

$types{$class}->{$attribute} is the tangram type of each attribute, ie "ref", "iset", etc. See Tangram::Type.

%attribute_options

$attribute_options{$class}->{$attribute} is the options hash for a given attribute.

%check

$check{$class}->{$attribute} is a function that will be passed a reference to the value to be checked and either throw an exception (die) or return true.

%cleaners

$attribute_options{$class}->{$attribute} is a reference to a destructor function for that attribute. It is called as an object method on the object being destroyed, and should ensure that any circular references that this object is involved in get cleared.

%abstract

$abstract->{$class} is set if the class is abstract

%init_defaults

$init_defaults{$class}->{$attribute} represents what an attribute is set to automatically if it is not specified when an object is created. If this is a scalar value, the attribute is set to the value. If it is a function, then that function is called (as a method) and should return the value to be placed into that attribute. If it is a hash ref or an array ref, then that structure is COPIED in to the new object. If you don't want that, you can do something like this:

   [...]
    flat_hash => {
        attribute => {
            init_default => sub { { key => "value" } },
        },
    },
   [...]

Now, every new object will share the same hash for that attribute.

There are currently four functions that allow you to access parts of this information.

attribute_options($class)

Returns a hash ref to a data structure from attribute names to the option hash for that attribute.

attribute_types($class)

Returns a hash ref from attribute names to the tangram type for that attribute.

known_classes

This function returns a list of all the classes that have had their object schema imported by Class::Tangram.

is_abstract($class)

This function returns true if the supplied class is abstract.

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>