Alzabo::MethodMaker - Auto-generate useful methods based on an existing schema


Alzabo::MethodMaker - Auto-generate useful methods based on an existing schema


  use Alzabo::MethodMaker ( schema => 'schema_name', all => 1 );


This module can take an existing schema and generate a number of useful methods for this schema and its tables and rows. The method making is controlled by the parameters given along with the use statement, as seen in the SYNOPSIS section.


schema => $schema_name

This parameter is required.

class_root => $class_name

If given, this will be used as the root of the class names generated by this module. This root should not end in '::'. If none is given, then the calling module's name is used as the root. See Class Names for more information.

all => $bool

This tells this module to make all of the methods it possibly can. See METHOD CREATION OPTIONS for more details.

name_maker => \&naming_sub

If this option is given, then this callback will be called any time a method name needs to be generated. This allows you to have full control over the resulting names. Otherwise names are generated as described in the documentation.

The callback will receive a hash containing the following parameters:

The following parameters vary from case to case:

When the type is table:

When the type is table_column or row_column:

When the type is foreign_key, linking_table, lookup_table, or self_relation:

When the type is foreign_key:

When the type is linking_table:

When the type is self_relation:


Using this module has several effects on your schema's objects.

New Class Names

Using this module causes your schema, table, and row objects to be blessed into subclasses of Alzabo::Runtime::Schema, Alzabo::Runtime::Table, Alzabo::Runtime::Row, respectively. These subclasses contain the various methods created by this module. The new class names are formed by using the class_root parameter and adding to it.


<class root>::Schema


<class root>::Table::<table name>


<class root>::Row::<table name>, subclassed by <class root>::CachedRow::<table name> and <class rootE<gt>::UncachedRow::<table nameE<gt>

With a root of 'My::Stuff', and a schema with only two tables, 'movie' and 'image', this would result in the following class names:


Loading Classes

For each class into which an object is blessed, this module will attempt to load that class via a use statement. If there is no module found this will not cause an error. If this class defines any methods that have the same name as those this module generates, then this module will not attempt to generate them.

validate_insert and validate_update methods

These methods can be defined in the relevant table and row class, respectively. If they are defined then they will be called before any actual inserts or updates are done.

The validate_update method should be defined in the <class rootE<gt>::Row::<table nameE<gt> class, not its subclasses.

They both should expect to receive a hash of column names to values as their parameters. For validate_insert, this will represent the new row to be inserted. For validate_update, this will represent the changes to the existing row.

These methods should throw exceptions if there are errors with this data.

For this to work, you must specify the insert and/or update parameters as true when loading the module. This causes these methods to be overridden in the generated subclasses.


Schema object methods

tables ($bool)

Creates methods for the schema that return the table object matching the name of the method.

For example, given a schema containing tables named 'movie' and 'image', this would create methods that could be called as $schema->movie and $schema->image.

Table object methods.

table_columns ($bool)

Creates methods for the tables that return the column object matching the name of the method. This is quite similar to the tables option for schemas.


Create an insert method overriding the one in Alzabo::Runtime::Table. See Loading Classes for more details. Unless you have already defined a validate_insert method for the generated table class this method will not be overridden.

Row object methods


Create an update method overriding the one in Alzabo::Runtime::Row. See Loading Classes for more details. Unless you have already defined a validate_update method for the generated row class this method will not be overridden.

foreign_keys ($bool)

Creates methods in row objects named for the table to which the relationship exists. These methods return either a single Alzabo::Runtime::Row object or a single Alzabo::Runtime::RowCursor object, depending on the cardinality of the relationship.

Take these tables as an example.

  movie                     credit
  ---------                 --------
  movie_id                  movie_id
  title                     person_id
NOTE: This option must be true if you want any of the following
options to be used.

linking_tables ($bool)

A linking table, as defined here, is a table with a two column primary key that, with each column being a foreign key to another table's primary key. These tables exist to facilitate n..n logical relationships. If both foreign_keys and linking_tables are true, then methods will be created that skip the intermediate linking tables

lookup_tables ($bool)

A lookup table is defined as a two column table with a one column primary key. It is assumed that the interesting part of this table is the table is the column that is not the primary key. Therefore, this module can create methods for these relationships that returns the data in this column. As an example, take the following tables:

  restaurant                cuisine
  ---------                 --------
  restaurant_id             cuisine_id
  name                      description

When given a restaurant table row, we already know its cuisine_id value. However, what we really want in most contexts is the value of cuisine.description.

self_relations ($bool)

A self relation is when a table has a parent/child relationship with itself. Here is an example:


NOTE: If the relationship has a cardinality of 1..1 then no methods will be created, as this option is really intended for parent/child relationships. This may change in the future.


Here is an example that covers all of the possible options:

 use Lingua::EN::Inflect;
 sub namer
     my %p = @_;
     # Table object can be returned from the schema via methods such as $schema->User_t;
     return $p{table}->name . '_t' if $p{type} eq 'table';
     # Column objects are returned similarly, via $schema->User_t->username_c;
     return $p{column}->name . '_c' if $p{type} eq 'table_column';
     # If I have a row object, I can get at the columns via their names, for example $user->username;
     return $p{column}->name if $p{type} eq 'row_column';
     # This manipulates the table names a bit to generate names.  For
     # example, if I have a table called UserRating and a 1..n
     # relationship from User to UserRating, I'll end up with a method
     # on rows in the User table called ->Ratings which returns a row
     # cursor of rows from the UserRating table.
     if ( $p{type} eq 'foreign_key' )
         my $name = $p{foreign_key}->table_to->name;
         my $from = $p{foreign_key}->table_from->name;
         $name =~ s/$from//;
         if ($p{plural})
             return my_PL( $name );
             return $name;
     # This is very similar to how foreign keys are handled.  Assume
     # we have the tables Restaurant, Cuisine, and RestaurantCuisine.
     # If we are generating a method for the link from Restaurant
     # through to Cuisine, we'll have a method on Restaurant table
     # rows called ->Cuisines, which will return a cursor of rows from
     # the Cuisine table.
     if ( $p{type} eq 'linking_table' )
         my $method = $p{foreign_key}->table_to->name;
         my $tname = $p{foreign_key}->table_from->name;
         $method =~ s/$tname//;
         return my_PL($method);
     # A lookup table is a 2 column table with a single column primary
     # key.  The method we generate is the name of the column that is
     # _not_ a primary key.  With a table named Location with columns
     # location_id and location, we could have a relationship from our
     # Restaurant table to the Location table.  This would give all
     # Restaurant table rows a ->location method which returned the
     # _value_ from the Location table that matched the location_id in
     # the Restaurant row.
     return (grep { ! $_->is_primary_key } $p{foreign_key}->table_to->columns)[0]->name
         if $p{type} eq 'lookup_table';
     # This should be fairly self-explanatory.
     return $p{parent} ? 'parent' : 'children'
         if $p{type} eq 'self_relation';
     # As should this.
     return $p{type} if grep { $p{type} eq $_ } qw( insert update );
     # And just to make sure that nothing slips by us we do this.
     die "unknown type in call to naming sub: $p{type}\n";
 # Lingua::EN::Inflect did not handle the word 'hours' properly when this was written
 sub my_PL
     my $name = shift;
     return $name if $name =~ /hours$/i;
     return Lingua::EN::Inflect::PL($name);


Dave Rolsky, <>

 Alzabo::MethodMaker - Auto-generate useful methods based on an existing schema