Alzabo...odMaker(3pm)

💖 Alzabo::MethodMaker 💖

okay bestie, this is the manual page for Alzabo::MethodMaker, hanging out in the 3pm section of the manual like the icon it is 🎀

and listen — the page literally opens with some raw code just vibing at the top before anything else, so here it is, verbatim, exactly as it appears, no notes 🙈:

$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. that's it, that's the whole job, and it eats 💅

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

okay so this module takes an existing schema and generates a whole bunch of useful methods for that schema, plus its tables, plus its rows. obsessed 🫶

the method-making situation is controlled by the parameters you hand over along with the use statement — exactly like the SYNOPSIS shows up there. ✨

🎀 PARAMETERS 🎀

all of these get passed to the module when it's imported via use. lowkey the whole control panel right here:

• schema => $schema_name — this one is required, no skipping it bestie.
• class_root => $class_name — if you give it, this becomes the root of the class names this module generates. it should not end in '::'. if you don't give one, then the calling module's name gets used as the root instead. head over to New Class Names for the whole tea.
• all => $bool — tells the module to make all the methods it possibly can. see METHOD CREATION OPTIONS for the details.

and real talk: if individual method creation options are set to false, that setting gets respected. so you could do

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

and that turns on all the regular options except for tables. slay.

• name_maker => \&naming_sub — if you provide this, the callback gets called every single time a method name needs to be generated, which gives you full control over the resulting names. otherwise names get generated the way the documentation describes.

the callback is expected to return a name for the method to be used. that name should not be fully qualified and should not contain any class designation — MethodMaker handles that part itself, bestie.

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 you try to use that as the method name, it won't work. Alzabo::Table objects already have such a method, and it returns the name of the table. see the relevant documentation of the schema, table, and row objects for a list of the methods they contain.

the NAMING SUB PARAMETERS section has all the details on what parameters get passed to this callback.

please note that if you have a large complex schema you will almost certainly need to provide a custom naming subroutine to avoid name conflicts. no cap, it's giving inevitable 💀

🔥 EFFECTS 🔥

using this module has several effects on your schema's objects. buckle up 🦋

🦋 New Class Names 🦋

your schema, table, and row objects get blessed into subclasses of Alzabo::Runtime::Schema, Alzabo::Runtime::Table, and Alzabo::Runtime::Row, respectively. these subclasses are where all the various methods created by this module live. the new class names get formed by taking the class_root parameter and adding onto it. ✨

and 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 happens for all created row classes. cute, right?

• 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

✨ 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's no module found, that won't cause an error, don't worry 🫶

but if that class defines any methods that have the same name as the ones this module generates, then this module will not attempt to generate them. respect the existing methods, periodt.

👑 METHOD CREATION OPTIONS 👑

when you're using Alzabo::MethodMaker, you may specify any of the following parameters. and specifying all causes all of them to be used. every last one. 💅

💅 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. iconic.

🍓 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. so if our Movie table had a column called title, we could write $schema->Movie->title. 🎀
• 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() and/or post_insert() method for the generated table class, or this parameter will not do anything. see the HOOKS section for more details. 🙈

🌈 Row object methods 🌈

• row_columns => $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. two jobs, one method, we love efficiency 💖
• 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 a pre_update() and/or post_update() method for the generated row class, or this parameter will not do anything. see the HOOKS 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() and/or post_select() method for the generated row class, or this parameter will not do anything. see the HOOKS 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() and/or post_delete() method for the generated row class, or this parameter will not do anything. see the HOOKS 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.

for exa

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

this would create a method for Movie row objects called Credit() which would return a cursor for the associated Credit table rows. similarly, Credit row objects would have a method called Movie() which would return the associated Movie row object. 🔥

• linking_tables => $bool — a linking table, as defined here, is a table with a two column primary key, 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. chef's kiss 🧚

for example, with the following tables:

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

the UserGroup table exists solely to facilitate the n..n relationship between User and Group. User row objects will have a Group() method, which returns a row cursor of Group row objects. and Group row objects will have a User() method which returns a row cursor of User row objects. 🦋

• 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
 restaurant_name   (n..1)      description
 phone                         spiciness
 cuisine_id

in this example, Restaurant row objects would have Cuisine_description() and Cuisine_spiciness methods which returned the corresponding values from the Cuisine table. 💜

• self_relations => $bool — a self relation is when a table has a parent/child relationship with itself. here's an example:

 Location
 --------
 location_id
 location_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. bestie, that's the documented situation as of right now 🙈

in this case, Location row objects will have both parent() and children() methods. the parent method returns a single row, while the children() method returns a row cursor of Location rows. 🌸

💖 HOOKS 💖

ok so like, we mentioned this before but let's get into it fr — you can create pre- and post-execution hooks that wrap around a whole bunch of methods. this is giving data validation on your inserts and updates, and it also lets you filter incoming or outgoing data however you need. for example? converting dates to and from a specific RDBMS format. iconic behavior tbh. ✨

every single hook lives inside a transaction, and that transaction gets rolled back if any part of the process fails. no half-finished nonsense here bestie. 🫶

ngl there's a catch you need to know about: Alzabo uses both the Alzabo::Runtime::Row->select and Alzabo::Runtime::Row->delete methods internally. if you radically alter their behavior through hooks, then some of Alzabo's functionality may end up broken. 💀

given that, it may be safer to just create new methods to fetch and massage data, rather than making post-select hooks that alter data. just saying. 🌸

each of these hooks receives different parameters, and we're documenting them all below:

✨ Insert Hooks

• pre_insert — this method receives a hash reference of all the parameters that are passed to the Alzabo::Runtime::Table->insert() method.

these are the actual parameters that will be passed to the insert method, so alterations to this reference will be seen by that method. that means you can alter the values that actually end up going into the database, or change any other parameters, however you see fit. 💅

• post_insert — this method also receives a hash reference containing all of the parameters passed to the insert() method. plus, the hash reference contains an additional key, row, which contains the newly created row. 🎀

🌈 Update Hooks

• pre_update — this method receives a hash reference of the parameters that will be passed to the Alzabo::Runtime::Row->update() method. again, alterations to these parameters will be seen by the update method.
• post_update — this method receives the same parameters as pre_update().

🦋 Select Hooks

• pre_select — this method receives an array reference containing the names of the requested columns. it gets called when either the Alzabo::Runtime::Row->select() or Alzabo::Runtime::Row->select_hash() methods are called.
• post_select — this method is called after the Alzabo::Runtime::Row->select() or Alzabo::Runtime::Row->select_hash() methods. it receives a hash containing the name and values returned from the relevant method, which it may modify. and if the values of this hash reference are modified, then this will be seen by the original caller. 👑

💜 Delete hooks

• pre_delete — this method receives no parameters. that's it. that's the whole vibe. 🙈

---

🎀 NAMING SUB PARAMETERS 🎀

the naming sub 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'll 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 gets passed when the type is table. it's the table object that 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's 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 that the method is based on.

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. heads up bestie 🫶

when the type is foreign_key:

• plural => $bool — this indicates whether or not the method 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 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:

• parent => $boolean — this indicates whether or not the method being created will return parent objects (true) or child objects (false).

---

🌟 NAMING SUB EXAMPLE 🌟

here is an example that covers all of the possible options, no cap:

 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 the methods that are generated, and can in turn generate basic POD for those methods. it's giving self-documenting, we love to see it. ✨

any schema that has had methods generated for it by Alzabo::MethodMaker will have an additional method, docs_as_pod. this returns documentation for the schema object's methods, plus any documentation available for objects that the schema contains — in this case, tables. and the tables in turn return their own documentation plus that of their contained row classes. it's a whole cascade bestie, so satisfying. 🦋

it's also possible to call the docs_as_pod method on any generated table or row class individually. main character energy for every class fr fr. 👑

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> — the icon who wrote this whole thing, we stan 💖

---

and that's a wrap on part 2 bestie!! 🎀 this beauty shipped as part of perl v5.34.0, dated 2022-06-14, and it's filed away in the User Contributed Perl Documentation under Alzabo...odMaker(3pm). go forth and make some methods, you've absolutely got this. slay 💅✨