NAME

Class::AutoGenerate - Automatically generate code upon require or use

SYNOPSIS

# Create a customized class loader (auto-generator)
package My::ClassLoader;
use Class::AutoGenerate -base;

# Define a matching rule that generates some code...
requiring 'Some::**::Class' => generates { qq{
    sub print_my_middle_names { print $1,"\n" }
} };

# In some other file, let's use the class loader
package main;

# Create the class loader, which adds itself to @INC
use My::ClassLoader;
BEGIN { My::ClassLoader->new( match_only => '**::Freaking::Class' ); }

# These class will be generated on the fly...
use Some::Freaking::Class;
use Some::Other::Freaking::Class;

Some::Freaking::Class->print_my_middle_names;
Some::Other::Freaking::Class->print_my_middle_names;

# Output is:
#   Freaking
#   Other::Freaking

DESCRIPTION

EXPERIMENTAL. I'm trying this idea out. Please let me know what you think by contacting me using the information listed under "AUTHOR". This is an experiment and any and all aspects of the API are up for revision at this point and I'm not even sure I'll maintain it, but I hope it will be found useful to myself and others.

Sometimes it's nice to be able to generate code on the fly. This tool does just that. You declare a few rules that can be used to define the class names you want to auto-generate and then the code that is to be built from it. Later you create your auto-generator object and start using the auto-generated classes.

This is a generalization baed upon Jifty::ClassLoader. If this experiment is successful in the way I'm testing it out for, it may be used to re-implement that class.

METHODS

import

When you are creating a new auto-generating class loader, you will include this statement in your package definition:

package My::ClassLoader;
use Class::AutoGenerate -base;

This statement tells Class::AutoGenerate to import all the subroutines in Class::AutoGenerate::Declare into the current package so that a new class loader can be declared.

Later, when you use your class loader, you will use the undecorated form:

use My::ClassLoader;

In this case, the import method does nothing special.

new

Creates a new instance of the auto-generating class loader object you've built. The class loader automatically adds itself to the @INC array to start loading classes.

If you want to immediately start using the class loader at compile time, you may wish to call this method within a BEGIN block:

use My::Custom::ClassLoader;
BEGIN { My::Custom::ClassLoader->new };

The constructor also recognizes the following options, passed in a hash, that can modify the behavior of the class loader.

match_only

This argument may be passed as anything that would be accepted in a "requiring" in Class::AutoGenerate::Declare clause and is used to prequalify which classes may actually be generated by this class loader. Using this, you can build one generic class loader that may be limited in how it is applied.

A module will only be generated if it first matches at least one of the patterns provided to "match_only".

For example,

package My::ClassLoader;
use Class::AutoGenerate -base;

requiring '**' => generates {};

1;

BEGIN { 
  My::ClassLoader->new( match_only => [ 'Prefix1::**', 'Prefix2::*' ] );
}

use Prefix1::Thing;
use Prefix2::Thing;
use Prefix3::Thing; # <--- ERROR: does not match the match_only clause

INC

This is the subroutine called by Perl during a perlfunc/require or perlfunc/use and evaluates the rules defined in your class loader. See perlfunc/require (towards the end) to see how this works.

It should be noted, however, that we cheat the system a little bit. According ot the require hook API, this method should return either a filehandle containing the code to be read or undef indicating that the hook does not know about the file being required.

This is done, except that only an empty stub package like this is ever returned when a class is auto-generated:

use strict;
use warnings;

package The::Included::Package::Name;

1;

Instead of having the import mechanism within Perl compile the code, most of the work is handled through symbol table manipulations and code evaluation before the file handle is returned. This allows for some earlier compile-time checking via closures and the like.

autogenerated MODULE

This method may be called in any of the following ways:

Class::AutoGenerate::autogenerated 'Some::Module';
Class::AutoGenerate->autogenerated('Some::Module');

# Where My::AutoGenerator->isa('Class::AutoGenerate')
My::AutoGenerator::autogenerated 'Some::Module';
My::AutoGenerator->autogenerated('Some::Module');

# Where $autogenerator->isa('Class::AutoGenerate');
$autogenerator->autogenerated('Some::Module');

Returns true if the package named was autogenerated by a Class::AutoGenerate class loader. Returns undef in any other case.

autogenerator_of MODULE

This method may be called in any of the following ways:

Class::AutoGenerate::autogenerator_of 'Some::Module';
Class::AutoGenerate->autogenerator_of('Some::Module');

# Where My::AutoGenerator->isa('Class::AutoGenerate')
My::AutoGenerator::autogenerator_of 'Some::Module';
My::AutoGenerator->autogenerator_of('Some::Module');

# Where $autogenerator->isa('Class::AutoGenerate');
$autogenerator->autogenerator_of('Some::Module');

Returns the object that was used to autogenerate the module. This is really just a shortcut for looking up the information in %INC, but saves some work of converting Perl module names into package file names and the cryptic use of the %INC variable.

_match_and_generate MODULE

This method is used internally to match "requiring" in Class::AutoGenerate::Declare statements and automatically generate code upon a match.

_declarations

Used internally to reference the "declare" in Class::AutoGenerate::Declare blocks and top-level "requiring" in Class::AutoGenerate::Declare rules in the auto-generating class loader's definition.

These are, then, instantiated to build the "_rules" for the object when "new" is called.

_rules

Used internally to reference the rules declared and instantiated within the auto-generating class loader.

_match_requiring MODULE, PATTERN

Used internally to match a "requiring" in Class::AutoGenerate::Declare declaration to a package name. Returns true if there's a match, or false otherwise.

_autogenerate MODULE, PATTERN, GENERATES

This method performs the action of taking the work in the generates declration and stuffing that work into the named package.

_stub_file_handle MODULE, CONCLUSIONS

Returns a basic stub class that is handed off to the import infrastructure of Perl to let it know that we succeeded, even though we already did most of the work for it.

SEE ALSO

Class::AutoGenerate::Declare

AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2007 Boomer Consulting, Inc.

This program is free software and may be modified and distributed under the same terms as Perl itself.

cpanm Class::AutoGenerate

perl -MCPAN -e shell
install Class::AutoGenerate