Class, not Module

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

Use as a pragma

   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'  );

Developer Mode

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.

Recursive Loading

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.

No-Stat Mode

  # Disable autoload-time file existance checking
  use Class::Autouse qw{:nostat};

Super Loader Mode

    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.

Loading with Regular Expressions

Registering a Callback for Dynamic Class Creation

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";

sugar

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

mod_perl

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.

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.

Performance Optimizatons

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

The Internal Debugger

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.

autouse $class, ...

load $class

devel

If any classes have previously been autouse'd and not loaded when this method is called, they will be loaded immediately.

superloader

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.

class_exists $class

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.

autouse_recursive $class

load_recursive $class