Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

Class::Autouse(3)                    User Contributed Perl Documentation                   Class::Autouse(3)



NAME
       Class::Autouse - Run-time load a class the first time you call a method in it.

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

DESCRIPTION
       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 :)

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

   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.

   Recursive Loading
       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.

   No-Stat Mode
       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};

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

   Loading with Regular Expressions
       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.

   Registering a Callback for Dynamic Class Creation
       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";

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

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

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

METHODS
   autouse $class, ...
       The autouse method sets one or more classes 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).

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

   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. For a more comprehensive set of methods of this nature, see Class::Inspector.

   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
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Autouse>

       For other issues, or commercial enhancement or support, contact the author.

AUTHORS
       Adam Kennedy <cpan@ali.as>

       Scott Smith <sakoht@cpan.org>

       Rob Napier <rnapier@employees.org>

SEE ALSO
       autoload, autoclass

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



perl v5.16.2                                     2012-02-02                                Class::Autouse(3)