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.

These parameters are all passed to the module when it is imported via CWuse. This parameter is required. 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. 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 );

* name_maker => \&naming_sub

If provided, 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. CWAlzabo::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.

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

Your schema, table, and row objects to be blessed into subclasses of CWAlzabo::Runtime::Schema, CWAlzabo::Runtime::Table, CWAlzabo::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.

In order to make it convenient to add new methods to the table and row classes, the created table classes are all subclasses of a new class based on your class root, and the same thing is done for all created row classes.

* Schema

  <class root>::Schema

* Tables

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

All tables will be subclasses of:

  <class root>::Table

* Rows

  <class root>::Row::<table name>

All rows will be subclasses of:

  <class root>::Row

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

 My::MovieDB::Schema

 My::MovieDB::Table::Movie - subclass of My::MovieDB::Table
 My::MovieDB::Row::Movie   - subclass of My::MovieDB::Row

 My::MovieDB::Table::Image - subclass of My::MovieDB::Table
 My::MovieDB::Row::Image   - subclass of My::MovieDB::Row

For each class into which an object is blessed, this module will attempt to load that class via a CWuse 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.

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

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 CW$schema->Movie and CW$schema->Image.

Creates methods for the tables that return the column object matching the name of the method. This is quite similar to the CWtables option for schemas. So if our Movie table had a column called title, we could write CW$schema->Movie->title. Look for hooks to wrap around the CWinsert() method in CWAlzabo::Runtime::Table. See Loading Classes for more details. You have to define either a CWpre_insert() and/or CWpost_insert() method for the generated table class or this parameter will not do anything. See the HOOKS section for more details.

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. Look for hooks to wrap around the CWupdate method in CWAlzabo::Runtime::Row. See Loading Classes for more details. You have to define a CWpre_update() and/or CWpost_update() method for the generated row class or this parameter will not do anything. See the HOOKS section for more details. Look for hooks to wrap around the CWselect method in CWAlzabo::Runtime::Row. See Loading Classes for more details. You have to define either a CWpre_select() and/or CWpost_select() method for the generated row class or this parameter will not do anything. See the HOOKS section for more details. Look for hooks to wrap around the CWdelete method in CWAlzabo::Runtime::Row. See Loading Classes for more details. You have to define either a CWpre_delete() and/or CWpost_delete() method for the generated row class or this parameter will not do anything. See the HOOKS section for more details. Creates methods in row objects named for the table to which the relationship exists. These methods return either a single CWAlzabo::Runtime::Row object or a single CWAlzabo::Runtime::RowCursor object, depending on the cardinality of the relationship. For exa

  Movie                     Credit
  ---------                 --------
  movie_id                  movie_id
  title                     person_id
                            role_name

  User           UserGroup        Group
  -------        ---------        --------
  user_id        user_id          group_id
  user_name      group_id         group_name

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

 Location
 --------
 location_id
 location_name
 parent_location_id

As was mentioned previously, it is possible to create pre- and post-execution hooks to wrap around a number of methods. This allows you to do data validation on inserts and updates as well as giving you a chance to filter incoming or outgoing data as needed. For example, this can be used 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 CWAlzabo::Runtime::Row->select and CWAlzabo::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:

* pre_insert

This method receives a hash reference of all the parameters that are passed to the CWAlzabo::Runtime::Table->insert() method. These are the actual parameters that will be passed to the CWinsert method so alterations to this reference will be seen by that method. This allows you to alter the values that actually end up going into the database or change any other parameters as you see fit.

* post_insert

This method also receives a hash reference containing all of the parameters passed to the CWinsert() method. In addition, the hash reference contains an additional key, row, which contains the newly created row.

* pre_update

This method receives a hash reference of the parameters that will be passed to the CWAlzabo::Runtime::Row->update() method. Again, alterations to these parameters will be seen by the CWupdate method.

* post_update

This method receives the same parameters as CWpre_update()

* pre_select

This method receives an array reference containing the names of the requested columns. This is called when either the CWAlzabo::Runtime::Row->select() or CWAlzabo::Runtime::Row->select_hash() methods are called.

* post_select

This method is called after the CWAlzabo::Runtime::Row->select() or CWAlzabo::Runtime::Row->select_hash() methods. It receives a hash containing the name and values returned from the revelant method, which it may modify. If the values of this hash reference are modified, then this will be seen by the original caller.

* pre_delete

This method receives no parameters.

The naming sub will receive a hash containing the following parameters: 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, linking_table, lookup_columns, row_column, self_relation, table, table_column.

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

When the type is table:

* table => Alzabo::Table object

This parameter will be passed when the type is CWtable. 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, or self_relation:

* foreign_key => Alzabo::ForeignKey object

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

It is possible to create an n..n relationship between a table and itself, and MethodMaker will attempt to generate linking table methods for such relationships, so your naming sub may need to take this into account.

When the type is foreign_key: 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 CWforeign_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 lookup_columns:

* column => Alzabo::Column object

When making lookup column methods, this column is the column in the foreign table for which a method is being made.

When the type is self_relation: This indicates whether or not the method being created will return parent objects (true) or child objects (false).

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.
     #
     # Note: this will generate a bad name if given a linking table
     # that links a table to itself.
     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);
 }

This module keeps track of methods that are generated and can in turn generate basic POD for those methods.

Any schema that has had methods generated for it by Alzabo::MethodMaker will have an additional method, CWdocs_as_pod. This will return documentation for the schema object's methods, as well as any documentation available for objects that the schema contains, in this case tables. The tables in turn return their own documentation plus that of their contained row classes.

It is also possible to call the CWdocs_as_pod method on any generated table or row class individually.

A simple script like the following can be used to send all of the generated documentation to CWSTDOUT.

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

  my $s = Alzabo::Runtime::Schema->load_from_file( name => 'foo' );

  print $s->docs_as_pod;

Dave Rolsky, <autarch@urth.org>