Class::Autouse - Run-time load a class the first time you call a method in it.
##################################################################
# SAFE FEATURES
# Debugging (if you go that way) must be set before the first use
BEGIN {
$Class::Autouse::DEBUG = 1;
}
# Turn on developer mode (always load immediately)
use Class::Autouse qw{:devel};
# Load a class on method call
use Class::Autouse;
Class::Autouse->autouse( 'CGI' );
print CGI->b('Wow!');
# Use as a pragma
use Class::Autouse qw{CGI};
# Use a whole module tree
Class::Autouse->autouse_recursive('Acme');
# Disable module-existance check, and thus one additional 'stat'
# per module, at autouse-time if loading modules off a remote
# network drive such as NFS or SMB.
# (See below for other performance optimizations.)
use Class::Autouse qw{:nostat};
##################################################################
# UNSAFE FEATURES
# Turn on the Super Loader (load all classes on demand)
use Class::Autouse qw{:superloader};
# Autouse classes matching a given regular expression
use Class::Autouse qr/::Test$/;
# Install a class generator (instead of overriding UNIVERSAL::AUTOLOAD)
# (See below for a detailed example)
use Class::Autouse \&my_class_generator;
# Add a manual callback to UNIVERSAL::AUTOLOAD for syntactic sugar
Class::Autouse->sugar(\&my_magic);
Class::Autouse is a runtime class loader that allows you to specify
classes that will only load when a method of that class is called.
For large classes or class trees that might not be used during the running of a
program, such as Date::Manip, this can save you large amounts of memory, and
decrease the script load time a great deal.
Class::Autouse also provides a number of "unsafe" features for
runtime generation of classes and implementation of syntactic sugar. These
features make use of (evil) UNIVERSAL::AUTOLOAD hooking, and are implemented
in this class because these hooks can only be done by a one module, and
Class::Autouse serves as a useful place to centralise this kind of evil :)
The terminology "class loading" instead of "module loading"
is used intentionally. Modules will only be loaded if they are acting as a
class.
That is, they will only be loaded during a Class->method call. If you try to
use a subroutine directly, say with "Class::method()", the class
will not be loaded and a fatal error will mostly likely occur.
This limitation is made to allow more powerful features in other areas, because
we can focus on just loading the modules, and not have to deal with importing.
And really, if you are doing OO Perl, you should be avoiding importing wherever
possible.
Class::Autouse can be used as a pragma, specifying a list of classes to load as
the arguments. For example
use Class::Autouse qw{CGI Data::Manip This::That};
is equivalent to
use Class::Autouse;
Class::Autouse->autouse( 'CGI' );
Class::Autouse->autouse( 'Data::Manip' );
Class::Autouse->autouse( 'This::That' );
"Class::Autouse" features a developer mode. In developer mode, classes
are loaded immediately, just like they would be with a normal 'use' statement
(although the import sub isn't called).
This allows error checking to be done while developing, at the expense of a
larger memory overhead. Developer mode is turned on either with the
"devel" method, or using :devel in any of the pragma arguments. For
example, this would load CGI.pm immediately
use Class::Autouse qw{:devel CGI};
While developer mode is roughly equivalent to just using a normal use command,
for a large number of modules it lets you use autoloading notation, and just
comment or uncomment a single line to turn developer mode on or off. You can
leave it on during development, and turn it off for speed reasons when
deploying.
As an alternative to the super loader, the "autouse_recursive" and
"load_recursive" methods can be used to autouse or load an entire
tree of classes.
For example, the following would give you access to all the URI related classes
installed on the machine.
Class::Autouse->autouse_recursive( 'URI' );
Please note that the loadings will only occur down a single branch of the
include path, whichever the top class is located in.
For situations where a module exists on a remote disk or another relatively
expensive location, you can call "Class::Autouse" with the :nostat
param to disable initial file existance checking at hook time.
# Disable autoload-time file existance checking
use Class::Autouse qw{:nostat};
Turning on the "Class::Autouse" super loader allows you to
automatically load
ANY class without specifying it first. Thus, the
following will work and is completely legal.
use Class::Autouse qw{:superloader};
print CGI->b('Wow!');
The super loader can be turned on with either the
"Class::Autouse->"superloader> method, or the
":superloader" pragma argument.
Please note that unlike the normal one-at-a-time autoloading, the super-loader
makes global changes, and so is not completely self-contained.
It has the potential to cause unintended effects at a distance. If you encounter
unusual behaviour, revert to autousing one-at-a-time, or use the recursive
loading.
Use of the Super Loader is highly discouraged for widely distributed public
applications or modules unless unavoidable.
Do not use just to be lazy
and save a few lines of code.
As another alternative to the superloader and recursive loading, a compiled
regular expression (qr//) can be supplied as a loader. Note that this loader
implements UNIVERSAL::AUTOLOAD, and has the same side effects as the
superloader.
If none of the above are sufficient, a CODE reference can be given to
Class::Autouse. Any attempt to call a method on a missing class will launch
each registered callback until one returns true.
Since overriding UNIVERSAL::AUTOLOAD can be done only once in a given Perl
application, this feature allows UNIVERSAL::AUTOLOAD to be shared. Please use
this instead of implementing your own UNIVERSAL::AUTOLOAD.
See the warnings under the "Super Loader Module" above which apply to
all of the features which override UNIVERSAL::AUTOLOAD.
It is up to the callback to define the class, the details of which are beyond
the scope of this document. See the example below for a quick reference:
Callback Example
Any use of a class like Foo::Wrapper autogenerates that class as a proxy around
Foo.
use Class::Autouse sub {
my ($class) = @_;
if ($class =~ /(^.*)::Wrapper/) {
my $wrapped_class = $1;
eval "package $class; use Class::AutoloadCAN;";
die $@ if $@;
no strict 'refs';
*{$class . '::new' } = sub {
my $class = shift;
my $proxy = $wrapped_class->new(@_);
my $self = bless({proxy => $proxy},$class);
return $self;
};
*{$class . '::CAN' } = sub {
my ($obj,$method) = @_;
my $delegate = $wrapped_class->can($method);
return unless $delegate;
my $delegator = sub {
my $self = shift;
if (ref($self)) {
return $self->{proxy}->$method(@_);
}
else {
return $wrapped_class->$method(@_);
}
};
return *{ $class . '::' . $method } = $delegator;
};
return 1;
}
return;
};
package Foo;
sub new { my $class = shift; bless({@_},$class); }
sub class_method { 123 }
sub instance_method {
my ($self,$v) = @_;
return $v * $self->some_property
}
sub some_property { shift->{some_property} }
package main;
my $x = Foo::Wrapper->new(
some_property => 111,
);
print $x->some_property,"\n";
print $x->instance_method(5),"\n";
print Foo::Wrapper->class_method,"\n";
This method is provided to support "syntactic sugar": allowing the
developer to put things into Perl which do not look like regular Perl. There
are several ways to do this in Perl. Strategies which require overriding
UNIVERSAL::AUTOLOAD can use this interface instead to share that method with
the superloader, and with class gnerators.
When Perl is unable to find a subroutine/method, and all of the class loaders
are exhausted, callbacks registered via
sugar() are called. The
callbacks receive the class name, method name, and parameters of the call.
If the callback returns nothing, Class::Autouse will continue to iterate through
other callbacks. The first callback which returns a true value will end
iteration. That value is expected to be a CODE reference which will respond to
the AUTOLOAD call.
Note: The sugar callback(s) will only be fired by UNIVERSAL::AUTOLOAD after all
other attempts at loading the class are done, and after attempts to use
regular AUTOLOAD to handle the method call. It is never fired by
isa()
or
can(). It will fire repatedly for the same class. To generate
classes, use the regular CODE ref support in
autouse().
Syntactic Sugar Example
use Class::Autouse;
Class::Autouse->sugar(
sub {
my $caller = caller(1);
my ($class,$method,@params) = @_;
shift @params;
my @words = ($method,$class,@params);
my $sentence = join(" ",@words);
return sub { $sentence };
}
);
$x = trolls have big ugly hairy feet;
print $x,"\n";
# trolls have big ugly hairy feet
The mechanism that "Class::Autouse" uses is not compatible with
mod_perl. In particular with reloader modules like Apache::Reload.
"Class::Autouse" detects the presence of mod_perl and acts as
normal, but will always load all classes immediately, equivalent to having
developer mode enabled.
This is actually beneficial, as under mod_perl classes should be preloaded in
the parent mod_perl process anyway, to prevent them having to be loaded by the
Apache child classes. It also saves HUGE amounts of memory.
Note that dynamically generated classes and classes loaded via regex CANNOT be
pre-loaded automatically before forking child processes. They will still be
loaded on demand, often in the child process. See prefork below.
As with mod_perl, "Class::Autouse" is compatible with the prefork
module, and all modules specifically autoloaded will be loaded before forking
correctly, when requested by prefork.
Since modules generated via callback or regex cannot be loaded automatically by
prefork in a generic way, it's advised to use prefork directly to
load/generate classes when using mod_perl.
- :nostat
- Described above, this option is useful when the module in
question is on remote disk.
- :noprebless
- When set, Class::Autouse presumes that objects which are
already blessed have their class loaded.
This is true in most cases, but will break if the developer intends to
reconstitute serialized objects from Data::Dumper, FreezeThaw or its
cousins, and has configured Class::Autouse to load the involved classes
just-in-time.
- :staticisa
- When set, presumes that @ISA will not change for a class
once it is loaded. The greatest grandparent of a class will be given back
the original can/isa implementations which are faster than those
Class::Autouse installs into UNIVERSAL. This is a performance tweak useful
in most cases, but is left off by default to prevent obscure bugs.
Class::Autouse provides an internal debugger, which can be used to debug any
weird edge cases you might encounter when using it.
If the $Class::Autouse::DEBUG variable is true when "Class::Autouse"
is first loaded, debugging will be compiled in. This debugging prints output
like the following to STDOUT.
Class::Autouse::autouse_recursive( 'Foo' )
Class::Autouse::_recursive( 'Foo', 'load' )
Class::Autouse::load( 'Foo' )
Class::Autouse::_children( 'Foo' )
Class::Autouse::load( 'Foo::Bar' )
Class::Autouse::_file_exists( 'Foo/Bar.pm' )
Class::Autouse::load -> Loading in Foo/Bar.pm
Class::Autouse::load( 'Foo::More' )
etc...
Please note that because this is optimised out if not used, you can no longer
(since 1.20) enable debugging at run-time. This decision was made to remove a
large number of unneeded branching and speed up loading.
The autouse method sets one or more classes to be loaded as required.
The load method loads one or more classes into memory. This is functionally
equivalent to using require to load the class list in, except that load will
detect and remove the autoloading hook from a previously autoused class,
whereas as use effectively ignore the class, and not load it.
The devel method sets development mode on (argument of 1) or off (argument of
0).
If any classes have previously been autouse'd and not loaded when this method is
called, they will be loaded immediately.
The superloader method turns on the super loader.
Please note that once you have turned the superloader on, it cannot be turned
off. This is due to code that might be relying on it being there not being
able to autoload its classes when another piece of code decides they don't
want it any more, and turns the superloader off.
Handy method when doing the sort of jobs that "Class::Autouse" does.
Given a class name, it will return true if the class can be loaded ( i.e. in
@INC ), false if the class can't be loaded, and undef if the class name is
invalid.
Note that this does not actually load the class, just tests to see if it can be
loaded. Loading can still fail. For a more comprehensive set of methods of
this nature, see Class::Inspector.
The same as the "autouse" method, but autouses recursively.
The same as the "load" method, but loads recursively. Great for
checking that a large class tree that might not always be loaded will load
correctly.
Bugs should be always be reported via the CPAN bug tracker at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Autouse>
For other issues, or commercial enhancement or support, contact the author.
Adam Kennedy <
[email protected]>
Scott Smith <
[email protected]>
Rob Napier <
[email protected]>
autoload, autoclass
Copyright 2002 - 2012 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this
module.