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 "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:

• type => $method_type

  This will always be the same as one of the parameters you give to the import method. It will be one of the following: foreign_key, insert, linking_table, lookup_table, row_column, self_relation, table, table_column, or update.

The following parameters vary from case to case:

When the type is table:

• table => Alzabo::Table object

  This parameter will be passed when the type is table. It is the table object the schema object's method will return.

When the type is table_column or row_column:

• column => Alzabo::Column object

  When the type is table_column, this is the column object the method will return. When the type is row_column, then it is the column whose value the method will return.

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

• foreign_key => Alzabo::ForeignKey object

  This is the foreign key on which the method is based.

When the type is foreign_key:

• plural => $bool

  This indicates whether or not the method that is being created will return a cursor object (true) or a row object (false).

When the type is linking_table:

• foreign_key_2 => Alzabo::ForeignKey object

  When making a linking table method, two foreign keys are used. The foreign_key is from the table being linked from to the linking table. This parameter is the foreign key from the linking table to the table being linked to.

When the type is self_relation:

• parent => $boolean

  This indicates whether or not the method being created will return parent objects (true) or child objects (false).

pluralize => \&pluralize - DEPRECATED

This option has been deprecated in favor of the name option.

Some of the methods are designed to return an Alzabo::Runtime::RowCursor object. If your table names are singular, it may be desirable to use the plural form for the method names (such as 'movie' becoming 'movies'). If you provide a callback for this parameter, it will be used to make the plural forms. If none is provided, then the unaltered table name will be used.

This callback should expect to receive a single parameter, the word to be pluralized, and should return its plural form.

EFFECTS

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.

Schema

<class root>::Schema

Tables

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

Rows

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

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::Table::image
 My::Stuff::Row::image
   My::Stuff::CachedRow::image
   My::Stuff::UncachedRow::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.

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 root>::Row::<table name> 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.

METHOD CREATION OPTIONS

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

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

update

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.

For relationships with 1..n cardinality, the pluralize callback will be called in an attempt to pluralize the method name.

Take these tables as an example.

  movie                     credit
  ---------                 --------
  movie_id                  movie_id
  title                     person_id
                            role_name

Name generation

When creating the method that returns rows from the credit table for the movie row objects, we will attempt to first pluralize the word 'credit'. Let's assume that pluralization returns the word 'credits'. This will create a method $movie_row->credits that returns an Alzabo::Runtime::RowCursor object. This cursor will return one Alzabo::Runtime::Row object for every credit containing the movie_id of the calling row.

Conversely, credit row objects will have a method $credit_row->movie which will return the Alzabo::Runtime::Row object containing the movie_id of the credit row.

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

Name generation

Start with the name of the linking table. Let's assume that we have a linking table named 'movie_image' that links together a movie table and an image table in an n..n relationship.

If the linking table name contains the name of the table for which we are creating the method, strip it from the beginning of the method name. Also strip any underscores that follow this name.

Similarly, strip the name of the table if it occurs at the end of the linking table name, along with any underscore immediately preceding it.

Then call the pluralize callback to pluralize the method name.

The previous two rules would leave us with the methods $movie_row->images for the movie table rows and $image_row->movies for the image table rows.

To illustrate further, let's use a slightly more complex example with the aforementioned movie and image tables. Let's assume that there are now two linking tables, one named 'movie_poster_image' and one named 'movie_premiere_image'.

If we apply the previous rules (and assume an English pluralization) we will end up with the following methods:

 $movie_row->poster_images
 $movie_row->premiere_images
 $image->movie_posters
 $image->movie_premieres

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
  phone
  cuisine_id

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.

Name generation

In the above example, this module would create a method $restaurant_row->cuisine that returns the value of cuisine.description in the row with the cuisine_id in that restaurant table row.

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.

Name generation

It is not possible to create the relationship methods via the usual method, because the same name would be used for both methods. In this case, the default is to create parent and children methods in the row object. The parent method returns a single row object, while the children method returns a cursor.

AUTHOR

Dave Rolsky, <autarch@urth.org>

cpanm Alzabo

perl -MCPAN -e shell
install Alzabo