Alzabo (version 0.64) - Alzabo::MethodMaker

Index



NAME

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


SYNOPSIS

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


DESCRIPTION

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.


PARAMETERS

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 New 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.

If individual method creation options are set as false, then that setting will be respected, so you could use

  use Alzabo::MethodMaker( schema => 'foo', all => 1, tables => 0 );

to turn on all of the regular options except for tables.

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 is expected to return a name for the method to be used. This name should not be fully qualified or contain any class designation as this will be handled by MethodMaker.

It is important that none of the names returned conflict with existing methods for the object the method is being added to.

For example, when adding methods that return column objects to a table, if you have a column called 'name' and try to use that as the method name, it won't work. Alzabo::Table objects already have such a method, which returns the name of the table. See the relevant documentation of the schema, table, and row objects for a list of methods they contain.

The Naming Sub Parameters section contains the details of what parameters are passed to this callback.


EFFECTS

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

New Class Names

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 onto it.

Schema

<class root>::Schema

Tables

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

Rows

<class root>::Row::<table name>, subclassed by <class root>::CachedRow::<table name>, <class root>::UncachedRow::, and <class root>::PotentialRow::

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

 My::Stuff::Schema
 My::Stuff::Table::Movie
 My::Stuff::Row::Movie
   My::Stuff::CachedRow::Movie
   My::Stuff::UncachedRow::Movie
   My::Stuff::PotentialRow::Movie
 My::Stuff::Table::Image
 My::Stuff::Row::Image
   My::Stuff::CachedRow::Image
   My::Stuff::UncachedRow::Image
   My::Stuff::PotentialRow::Image

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.


METHOD CREATION OPTIONS

When using Alzabo::MethodMaker, you may specify any of the following parameters. Specifying 'all' causes all of them to be used.

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.

insert_hooks => $bool

Look for hooks to wrap around the insert method in Alzabo::Runtime::Table. See Loading Classes for more details. You have to define either a pre_insert or post_insert method (or both) for the generated table class or this parameter will not do anything. See the HOOK section for more details.

Row object methods

row_column => $bool

This tells MethodMaker to create get/set methods for each column a row has. These methods take a single optional argument, which if given will cause that column to be updated for the row.

update_hooks => $bool

Look for hooks to wrap around the update method in Alzabo::Runtime::Row. See Loading Classes for more details. You have to define either a pre_update or post_update method (or both) for the generated row class or this parameter will not do anything. See the HOOK section for more details.

select_hooks => $bool

Look for hooks to wrap around the select method in Alzabo::Runtime::Row. See Loading Classes for more details. You have to define either a pre_select or post_select method (or both) for the generated row class or this parameter will not do anything. See the HOOK section for more details.

delete_hooks => $bool

Look for hooks to wrap around the delete method in Alzabo::Runtime::Row. See Loading Classes for more details. You have to define either a pre_delete or post_delete method (or both) for the generated row class or this parameter will not do anything. See the HOOK section for more details.

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
                            role_name

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_columns => $bool

Lookup columns are columns in foreign tables to which a table has a many-to-one or one-to-one relationship to the foreign table's primary key. For example, given the tables below:

  Restaurant                    Cuisine
  ---------                     --------
  restaurant_id                 cuisine_id
  name              (n..1)      description
  phone                         spiciness
  cuisine_id

If we have a Restaurant row, we might want to have methods available such as ->cuisine_description or ->cuisine_spiciness.

self_relations => $bool

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

 Location
 --------
 location_id
 name
 parent_location_id

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.


HOOKS

As was mentioned before, it is possible to create pre- and post-execution hooks to wrap around a number of methods. This allow you to do data validation on inserts and updates as well as giving you a chance to filter incoming our outgoing data as needed (for example, if you need to convert dates to and from a specific RDBMS format).

All hooks are inside a transaction which is rolled back if any part of the process fails.

It should be noted that Alzabo uses both the < Alzabo::Runtime::Row-select >> and Alzabo::Runtime::Row->delete methods internally. If their behavior is radically altered through the use of hooks, then some of Alzabo's functionality may be broken.

Given this, it may be safer to create new methods to fetch and massage data rather than to create post-select hooks that alter data.

Each of these hooks receives different parameters, documented below:

Insert Hooks

Update Hooks

Select Hooks

Delete hooks


NAMING SUB PARAMETERS

The naming sub will receive a hash containing the following parameters:

The following parameters vary from case to case, depending on the value of type.

When the type is table:

When the type is table_column or row_column:

When the type is foreign_key, linking_table, or self_relation:

When the type is foreign_key:

When the type is linking_table:

When the type is lookup_columns:

When the type is self_relation:


NAMING SUB EXAMPLE

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 );
         }
         else
         {
             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);
     }
     # Lookup columns are columns if foreign tables for which there
     # exists a one-to-one or many-to-one relationship.  In cases such
     # as these, it is often the case that the foreign table is rarely
     # used on its own, but rather it primarily used as a lookup table
     # for values that should appear to be part of other tables.
     #
     # For example, an Address table might have a many-to-one
     # relationship with a State table.  The State table would contain
     # the columns 'name' and 'abbreviation'.  If we have
     # an Address table row, it is convenient to simply be able to say
     # $address->state_name and $address->state_abbreviation.
     if ( $p{type} eq 'lookup_columns' )
     {
         return join '_', map { lc $_->name } $p{foreign_key}->table_to, $p{column};
     }
     # This should be fairly self-explanatory.
     return $p{parent} ? 'parent' : 'children'
         if $p{type} eq 'self_relation';
     # 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);
 }


AUTHOR

Dave Rolsky, <autarch@urth.org>