Dave Rolsky > Alzabo-0.92 > Alzabo::MethodMaker

Download:
Alzabo-0.92.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  4
Open  1
View/Report Bugs
Module Version: 2   Source  

$self->{name}

$desc

EOF $pod .= $params if $params;

    return $pod;
}

package Alzabo::ClassDocs;

use Params::Validate qw( validate SCALAR );

use base qw(Alzabo::Docs);

sub new { my $class = shift; my %p = validate( @_, { group => { type => SCALAR }, description => { type => SCALAR }, } );

    return bless \%p, $class;
}

sub as_pod { my $self = shift;

    return ucfirst "$self->{description}\n\n";
}

1;

__END__

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 ^

These parameters are all passed to the module when it is imported via use.

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.

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.

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

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

Table object methods.

Row object methods

HOOKS ^

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

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

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.
     #
     # 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);
 }

GENERATED DOCUMENTATION ^

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, docs_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 docs_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 STDOUT.

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

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

  print $s->docs_as_pod;

AUTHOR ^

Dave Rolsky, <autarch@urth.org>

syntax highlighting: