NAME
    Class::Autouse - Run-time class loading on first method call

SYNOPSIS
      # 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};

      # Turn on debugging
      use Class::Autouse qw{:debug};

      # Turn on developer mode
      use Class::Autouse qw{:devel};

      # Turn on the Super Loader
      use Class::Autouse qw{:superloader};

DESCRIPTION
    Class::Autouse allows you to specify a class the will only load when a
    method of that class is called. For large classes 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.

  Use as a pragma
    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' );

  The Internal Debugger
    Given the ":debug" pragma argument, Class::Autouse will dump detailed
    internal call information. This can be usefull when an error has
    occurred that may be a little difficult to debug, and some more
    inforamtion about when the problem has actually occurred is required.
    Debug messages are written to STDOUT, and will look something like

     Class::Autouse::autouse_recursive( 'Foo' )
      Class::Autouse::_recursive( 'Foo', 'load' )
       Class::Autouse::load( 'Foo' )
       Class::Autouse::_child_classes( '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...

  Developer Mode
    "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.

  No Stat Mode
    For situations where a module exists on a remote disk that is relatively
    expensive to get to, you can call "Class::Autouse" with the :nostat
    param to disable initial file existance checking at hook time.

  Super Loader
    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.

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

  Class, not Module
    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 do use a subroutine directly, say with "Class::method()", the
    class will not be loaded. This limitation is made to allow more
    powerfull features in other areas, because the module can focus on just
    loading the modules, and not have to deal with importing.

  mod_perl
    The methods that Class::Autouse uses are 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.

METHODS
  autouse $class
    The autouse method sets the class to be loaded as required.

  load $class
    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.

  devel
    The devel method sets development mode on (argument of 1) or off
    (argument of 0)

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

  class_exists $class
    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.

  autouse_recursive $class
    The same as the "autouse" method, but autouses recursively

  load_recursive $class
    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.

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

AUTHORS
    Adam Kennedy (Maintainer), <http://ali.as/>, cpan@ali.as

    Rob Napier (No longer involved), rnapier@employees.org

SEE ALSO
    autoload, autoclass

COPYRIGHT
    Copyright (c) 2002 - 2005 Adam Kennedy. All rights reserved.

    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.