NAME

Package::Transporter::Generator::Eponymous_Directory - require .pl files containing subroutine definitions from a directory

SYNOPSIS

        use strict;
        use lib '.'; # allows the .pl files to be read via require()
        
        package eponymous_directory;
        
        use Package::Transporter sub{eval shift}, sub {
                $_[0]->register_potential('Eponymous_Directory', 'FOR_SELF', undef);
        };
        
        yn(potentially_defined('hello_worlds'));
        yn(potentially_defined('hello_world'));
        yn(defined(&hello_world));
        
        hello_world();
        
        yn(defined(&hello_world));
        exit(0);
        

DESCRIPTION

The generator can be used to keep the subroutines of a module as individual .pl files in a directory. In case your module has a huge number of subroutines, out of which only a few are typically used, keeping the subroutines in an external source might conserve time and memory.

Eponymous means the same name. This generator tries to require() files of the same name as the subroutine from the directory of the same name as the package file. Example:

        Subroutine: hello_world
        Package: The::Requesting::Package
        Package File: /opt/perl5/5.10.0/The/Requesting/Package.pm
        Result:
        require('/opt/perl5/5.10.0/The/Requesting/Package/hello_world.pl');

The generator makes a listing of the directory and uses that for rule matching. Newly added .pl files will only be seen on the next start of the program.

Because of the require(), taint checks and untainting comes in for free.

Prototypes

Prototype definitions are supported, but have to be explicitely requested. It only makes sense if defining and requesting package are the same (therefore the explicit request). Beside that, the correct prototype might not be known at compile time. However, for AUTOLOADed subroutines the prototype is not checked in Perl5, so for the moment prototypes are pretty much useless.

The prototypes reside in a file called -prototypes.pl in the eponymous directory. Example:

        require('/opt/perl5/5.10.0/The/Requesting/Package/-prototypes.pl');

The following shell commands are the rough concept how to build such a prototypes-only file.

        rm -- -prototypes.pl
        cat -- *.pl \
        | grep '^sub ' \
        | sed -e 's/ *{.*$/;/' \
        > -prototypes.pl
        echo '1;' >> -prototypes.pl

ANYTHING ELSE

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