NAME

Package::Transporter::Generator - base class for subroutine generators

SYNOPSIS

        use Package::Transporter::Generator;

        my $generator = sub {
                sprintf(qq{print 'Hello %s\n'}, substr($_[1], 6));
        };
        bless($generator, 'Package::Transporter::Generator');

DESCRIPTION

A generator is a blessed anonymous subroutine, which is called with all information its rule check got plus a package object. Valid return values are:

• a string not looking like a complete subroutine definition - surroundings are added automatically.

• a string starting with 'sub ' - taken as a complete definition of the missing subroutine and submitted to the eval(). Note that the string should include a return statement for a reference to the subroutine after the definition.

• a CODE reference - assuming the generator already did all necessary steps, the reference is passed to the upper layers, where it will eventually hit the goto &$reference in the autoloader.

The first parameter to the generator call is a package object. The generator can use the package object to submit code to the package via ->transport(). While you have access to lexical variables declared before the visit point, you can't create them. Because eval behaves like a block, not like an inline instruction.

There is no general-purpose generator shipped with Package::Transporter, because that function is covered by Package::Transporter. Transporter is about demand, Transporter is about supply; they complement each other. Keep in mind that you can't autoload constant functions in Perl.

A manual crafted generator looks like the following:

        my $generator = sub { 
                my ($pkg, $sub_name, $argc) = (shift, shift, shift);

                #... do something to create the $sub_ref

                return($sub_ref);
        };

Generator Classes

Keep your generators in package files so that they are re-usable. It is also the most obvious way to define generators. The Hello_Anything class roughly looks like this:

        package Package::Transporter::Generator::Hello_Anything;
        use parent qw(Package::Transporter::Generator);
        
        sub new {
                my $generator = sub {
                        my ($pkg, $sub_name, $argc) = (shift, shift, shift);

                        my $sub_body = sprintf(
                                qq{print 'Hello %s\n'},
                                substr($sub_name, 6));
                        return($sub_body);
                };
                bless($generator, __PACKAGE__);
        }

Although the standard is to generate a subroutine, that behaviour is not mandatory. The generator can simply do what the function is supposed to do and return nothing.

You want to see the examples directory and the .pm files in Generator.

PUBLIC METHODS

The following methods belong to the public interface of Package::Transporter::Package.

run

Generate the subroutine.

ANYTHING ELSE

Please see the documentation of the upstream package Package::Transporter.