Package::Transporter::Generator::Potential::Homonymous_Directory - Require .pl files containing subroutine definitions from a directory of the same name as the package

	use strict;
	use lib '.'; # allows the .pl files to be read via require()

	package homonymous_directory;

	use Package::Transporter sub{eval shift}, sub {
		$_[0]->register_potential('Homonymous_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);

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.

Homonymous 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.

You can use .al files generated by AutoSplit, if you remove the package statement in those files.

When running under -c ('syntax check only'), the module will load all files from the homonymous directory. This reduces the chance of unpleasant surprises.

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 homonymous 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

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