=pod

=head1 NAME

Package::Autoloader - modular 'AUTOLOAD' and 'can' for packages


=head1 SYNOPSIS

The following basic example demonstrates how subroutine generation is done and how packages can facilitate the potential.

	package Synopsis;
	use Package::Autoloader sub{eval shift}, sub {
		my $generator = q{
			my $greet = substr($sub_name, 6); #magic
	 		return(qq{return('Hello $greet\n')});
		};
		$_[0]->register_rule($generator, 'greet_');
	};
	
	print greet_world();
	
	
	package Synopsis::Desc1;
	use Package::Autoloader sub{eval shift};
	
	print greet_mundo();
	
	
	package Synopsis::Desc2;
	our @ISA = ('Synopsis');
	use Package::Autoloader sub{eval shift};
	
	my $obj = bless( \(my $o = 0), 'Synopsis::Desc2');
	print STDOUT ($obj->can('greet__monde') ? 'Can' : 'Cannot'), "\n";
	print $obj->greet_monde();


The dynamically generated subroutines greet_world, greet_mundo, and salut_monde
all print Hello plus the second part of their name to the screen. The
example makes maximum use of convenience features.

The package Synopsis::Desc2 should remind you that can, defined and exists are not aware of AUTOLOAD. It is too monolithic and unstructured. However, there are two subroutines potentially_can, and potentially_defined, which are aware of Package::Autoloader. Details below.


=head1 WARNING

This is an early public release of Package::Autoloader. The module
hasn't been thoroughly tested, making the probability of fatal bugs
quiet high. It is not the goal of the release to provide a well-tested
module, but to document the current development. That are the reasons
why the installation of Package::Autoloader fails intentionally.


=head1 DESCRIPTION

Package::Autoloader supplies packages with subroutine definitions on the fly. It requires individual activation with the sub-eval-shift like shown in the synopsis. This module complements L<Package::Transporter>.

Once a missing subroutine is encountered, Perl's autoload mechanism is triggered and groups of rules are checked for a matching generator. If one is found, it should bring the requested subroutine into existence.

A hierarchical search for a matching rule through the package name is performed. For the package A::B::C the hierarchy is A::B::C, A::B, A, and ''. Any rule found on the way to the top is checked.

From a practical point of view, Package::Autoloader enables you to specify autoloading in terms of modular rules instead of a monolithic AUTOLOAD subroutine. The rules are normally activated during compile time.


=head2 Subroutine Potential

Whether a package has potential of a subroutine can be tested with the utility functions potentially_(can|defined). They have to be activated. Either globally by setting Package::Autoloader::Package::CANDEF=1 or individually by using the following technique:

	package Synopsis::Desc1;
	use Package::Autoloader sub{eval shift}, sub{
		$_[0]->potentially_candef;
	};

The dynamic functions take the name of a subroutine (meaning a string) as an argument and return true or false. That makes their use consistent, but different from from their static counterparts 'can' and 'defined'.

There is no potentially_exists, because the rule system in Package::Autoloader doesn't distinguish between defined and exists, because AUTOLOAD doesn't tell whether a prototype is requested or a full subroutine definition. 'exists' considers even prototypes and names treated with undef (crazy, eh?), while 'defined' only considers (fully) defined subroutines. You probably want to use the combination of can and defined for most practical purposes.


=head2 Visit Points

By default a missing subroutine is defined inside a package via an eval. The eval is passed around through the anonymous subroutine reference sub{eval shift}. This construct is called a visit point for the purpose of this documentation.

It is actually a fast solution, easy to understand, and with straightforward results, bearing only a few surprises. Direct symbol table manipulations can't achieve the same, so its futile to discuss whether they are faster or slower with regards to the overall effort.

Every package using Package::Autoloader gets an individual AUTOLOAD subroutine. That appeared to be the most robust approach and allows for a 'use strict' without exceptions.


=head1 RULES

The two rules from the synopsis conveniently hide the full interface for rules. You can specify rules in three ways

=over 8

=item * by giving B<a generator and a subroutine name> - a minimal rule object will be created with the own package name for the search default;

=item * by giving B<an array holding parameters for new()> - a rule object will be instantiated accordingly;

=item * by giving B<a ready-make rule object> - will be taken as-is.

=back


=head2 Rule Details

A rule is a check whether a generator applies to a missing subroutine. Example: a call for Ex::Ample::no_such_thing(7, [8, 9]) will cause these style of checks to occur internally:

	$rule->check('Ex::Ample', 'no_such_thing', 1, 7, [8, 9]);

Included in Package::Autoloader is the general-purpose rule class Package::Autoloader::Rule. To create a rule object for the above example, use it as follows:

	use Package::Autoloader::Rule;
	my $rule = Package::Autoloader::Rule->new
		($generator, 'Ex::Ample', 'no_such_thing', 1, '', 'ARRAY');

However, it is not required to specify all details; normally the last item in rule creation is the subroutine name. Note that the standard rule class does not check the values of arguments, but rather the result of ref().

In order to minimize the number of rules to evaluate, they are organized by purpose, package name, and subroutine name. Internally the above rule will be stored in the pre-selection tree under

	'Ex::Ample' => {'no_' => [$rule]}

This detail only needs to be considered when you write your own rules class. See the pre_select attribute in the standard class.

To widen the scope of a hierarchy search rule, shorten the names. Ex applies to all package names starting with Ex (full package name, but no wildcard required), Ex::(A|B|C) is recognized as a regular expression and an empty package name applies to all packages.

Similarly for subroutine names (any kind of search). Specify no_ to match a name starting with no_ (partial subroutine name ending in underscore but no wildcard required), no_(parking|money) is recognized as a regular expression and an empty subroutine name applies to all subroutines.


=head2 Generators

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

=over 8

=item * B<a string not looking like a complete subroutine definition> - surroundings are added automatically.

=item * B<a string starting with 'sub '> - taken as a complete definition and submitted to the eval(). Note that the string should include a return statement for a reference to the subroutine after the definition. 

=item * B<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.

=back


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::Autoloader, because that function is covered by Package::Transporter. Autoloader 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);
	};


=head1 PUBLIC INTERFACE REFERENCE

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

=over 8

=item B<potentially_candef>

Activates the two subroutines potentially_can and potentially_defined for the current package.

=item B<register_rule>

Trigger the convenience function as described above.

=back


=head1 BUGS

Please report unknown bugs via the "CPAN Request Tracker", which is the default way of managing such reports. If that is too much of hassle, then just drop me a note to the e-mail address below.

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Package-Autoloader

This is an early public release. Also see the Todo file.


=head1 AUTHOR

Winfried Trumper E<lt>pub+perl(a)wt.tuxomania.netE<gt>


=head1 COPYRIGHT

Copyright (C) 2010 Winfried Trumper

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


=head1 SEE ALSO

L<Package::Transporter> complements Package::Autoloader in various ways.

=head2 Relations

Some of the exporter modules create subroutines on the fly, most notably Sub::Exporter and Class::Exporter. The compatibility of 'AUTOLOAD' and 'can' is addressed by L<Class::AutoloadCAN>.


=cut
