File Coverage

blib/lib/Class/Autouse.pm
Criterion Covered Total %
statement 223 256 87.1
branch 79 130 60.8
condition 24 44 54.5
subroutine 38 41 92.7
pod 7 8 87.5
total 371 479 77.5


line stmt bran cond sub pod time code
1             package Class::Autouse;
2              
3             # See POD at end of file for documentation
4              
5             ### Memory Overhead: 396K
6              
7 7     7   196 use 5.005;
  7         107  
  7         69  
8 7     7   110 use strict;
  7         64  
  7         135  
9 7     7   117 no strict 'refs'; # We _really_ abuse refs :)
  7         65  
  7         95  
10 7     7   18847 use UNIVERSAL ();
  7         3426  
  7         122  
11              
12             # Avoid a 5.6 bug where a constant set to undef throws a "useless use of
13             # constant in void context" warning.
14 7     7   114 use vars qw{$DEBUG};
  7         66  
  7         107  
15             BEGIN {
16 7   50 7   161 $DEBUG ||= 0;
17             }
18              
19             # Handle the debugging switch via a constant to allow debugging
20             # to be optimised out at compile time if not needed.
21 7     7   108 use constant DEBUG => $DEBUG;
  7         64  
  7         124  
22             print "Class::Autouse::autoload -> Debugging Activated.\n" if DEBUG;
23              
24             # Become an exporter so we don't get complaints when we act as a pragma.
25             # I don't fully understand the reason for this, but it works and I can't
26             # recall how to replicate the problem, so leaving it in to avoid any
27             # possible reversion. Besides, so many things use Exporter it should
28             # be practically free to do this.
29 7     7   237 use base 'Exporter';
  7         65  
  7         154  
30              
31             # Load required modules
32             # Luckily, these are so common they are basically free
33 7     7   148 use Carp ();
  7         64  
  7         142  
34 7     7   156 use File::Spec ();
  7         64  
  7         153  
35 7     7   221 use List::Util ();
  7         98  
  7         371  
36              
37             # Globals
38 7     7   3032 use vars qw{ $VERSION $DEVEL $SUPERLOAD $NOSTAT }; # Load environment
  7         79  
  7         108  
39 7     7   519 use vars qw{ %SPECIAL %LOADED %BAD }; # Special cases
  7         77  
  7         241  
40 7     7   183 use vars qw{ $HOOKS %chased $orig_can $orig_isa }; # Working information
  7         65  
  7         85  
41              
42             # Compile-time Initialisation and Optimisation
43             BEGIN {
44 7     7   97 $VERSION = '1.27';
45              
46             # We play with UNIVERSAL::can at times, so save a backup copy
47 7         73 $orig_can = \&UNIVERSAL::can;
48 7         72 $orig_isa = \&UNIVERSAL::isa;
49              
50             # We always start with the superloader off
51 7         65 $SUPERLOAD = 0;
52              
53             # Disable stating for situations where modules are on remote disks
54 7         64 $NOSTAT = 0;
55              
56             # AUTOLOAD hook counter
57 7         62 $HOOKS = 0;
58              
59             # ERRATA
60             # Special classes are internal and should be left alone.
61             # Loaded modules are those already loaded by us.
62             # Bad classes are those that are incompatible with us.
63 7         97 %SPECIAL = map { $_ => 1 } qw{ CORE main ARRAY HASH SCALAR REF UNIVERSAL };
  49         3578  
64 7         87 %LOADED  = map { $_ => 1 } qw{ UNIVERSAL Exporter Carp File::Spec };
  28         303  
65 7         358 %BAD     = map { $_ => 1 } qw{ IO::File };
  7         86  
66              
67             # "Have we tried to autoload a method before?"
68             # Anti-loop protection. Contains fully referenced sub names
69 7         239 %chased = ();
70             }
71              
72              
73              
74              
75              
76             #####################################################################
77             # Configuration and Setting up
78              
79             # Developer mode flag.
80             # Cannot be turned off once turned on.
81             sub devel {
82 2     2 1 109 _debug(\@_, 1) if DEBUG;
83              
84             # Enable if not already
85 2 50       49 return 1 if $DEVEL;
86 2         21 $DEVEL = 1;
87              
88             # Load any unloaded modules.
89             # Most of the time there should be nothing here.
90 2         114 foreach my $class ( grep { $INC{$_} eq 'Class::Autouse' } keys %INC ) {
  132         1681  
91 1         13 $class =~ s/\//::/;
92 1         13 $class =~ s/\.pm$//i;
93 1         14 Class::Autouse->load($class);
94             }
95             }
96              
97             # Happy Fun Super Loader!
98             # The process here is to replace the &UNIVERSAL::AUTOLOAD sub
99             # ( which is just a dummy by default ) with a flexible class loader.
100             sub superloader {
101 0     0 1 0 _debug(\@_, 1) if DEBUG;
102              
103 0 0       0 unless ( $SUPERLOAD ) {
104             # Overwrite UNIVERSAL::AUTOLOAD and catch any
105             # UNIVERSAL::DESTROY calls so they don't trigger
106             # UNIVERSAL::AUTOLOAD. Anyone handling DESTROY calls
107             # via an AUTOLOAD should be summarily shot.
108 0         0 *UNIVERSAL::AUTOLOAD = \&_AUTOLOAD;
109 0         0 *UNIVERSAL::DESTROY  = \&_DESTROY;
110              
111             # Because this will never go away, we increment $HOOKS such
112             # that it will never be decremented, and thus the
113             # UNIVERSAL::can/isa hijack will never be removed.
114 0 0       0 _UPDATE_HOOKS() unless $HOOKS++;
115             }
116              
117 0         0 $SUPERLOAD = 1;
118             }
119              
120             # The main autouse sub
121             sub autouse {
122             # Operate as a function or a method
123 15 50   15 1 239 shift if $_[0] eq 'Class::Autouse';
124              
125             # Ignore calls with no arguments
126 15 100       164 return 1 unless @_;
127              
128 13         111 _debug(\@_) if DEBUG;
129              
130 13         122 foreach my $class ( grep { $_ } @_ ) {
  17         185  
131             # Control flag handling
132 17 100       249 if ( substr($class, 0, 1) eq ':' ) {
133 1 50       12 if ( $class eq ':superloader' ) {
    50          
    0          
134             # Turn on the superloader
135 0         0 Class::Autouse->superloader;
136             } elsif ( $class eq ':devel' ) {
137             # Turn on devel mode
138 1         12 Class::Autouse->devel(1);
139             } elsif ( $class eq ':nostat' ) {
140             # Disable stat checks
141 0         0 $NOSTAT = 1;
142             }
143 1         29 next;
144             }
145              
146             # Load now if in devel mode, or if its a bad class
147 16 50 33     2953 if ( $DEVEL || $BAD{$class} ) {
148 0         0 Class::Autouse->load( $class );
149 0         0 next;
150             }
151              
152             # Does the file for the class exist?
153 16         282 my $file = _class_file($class);
154 16 50       190 next if exists $INC{$file};
155 16 50 33     198 unless ( $NOSTAT or _file_exists($file) ) {
156 0         0 my $inc = join ', ', @INC;
157 0         0 _cry("Can't locate $file in \@INC (\@INC contains: $inc)");
158             }
159              
160             # Don't actually do anything if the superloader is on.
161             # It will catch all AUTOLOAD calls.
162 16 50       199 next if $SUPERLOAD;
163              
164             # Add the AUTOLOAD hook and %INC lock to prevent 'use'ing
165 16         276 *{"${class}::AUTOLOAD"} = \&_AUTOLOAD;
  16         364  
166 16         175 $INC{$file} = 'Class::Autouse';
167              
168             # When we add the first hook, hijack UNIVERSAL::can/isa
169 16 100       205 _UPDATE_HOOKS() unless $HOOKS++;
170             }
171              
172 13         244 1;
173             }
174              
175             # Import behaves the same as autouse
176 7     7   94 sub import { shift->autouse(@_) }
177              
178              
179              
180              
181              
182             #####################################################################
183             # Explicit Actions
184              
185             # Completely load a class ( The class and all its dependencies ).
186             sub load {
187 15     15 1 127 _debug(\@_, 1) if DEBUG;
188              
189 15 50       193 my $class = $_[1] or _cry('No class name specified to load');
190 15 50       165 return 1 if $LOADED{$class};
191              
192             # Load the entire ISA tree
193 15         145 my @stack = ( $class );
194 15         160 my %seen = ( UNIVERSAL => 1 );
195 15         173 my @search = ();
196 15         213 while ( my $c = shift @stack ) {
197 22 50       294 next if $seen{$c}++;
198              
199             # Ensure class is loaded
200 22 100       1303 _load($c) unless $LOADED{$c};
201              
202             # Add the class to the search list,
203             # and add the @ISA to the load stack.
204 21         245 push @search, $c;
205 21         187          unshift @stack, @{"${c}::ISA"};
  21         2228  
206             }
207              
208             # If called an an array context, return the ISA tree.
209             # In scalar context, just return true.
210 14 100       287 wantarray ? @search : 1;
211             }
212              
213             # Is a particular class installed in out @INC somewhere
214             # OR is it loaded in our program already
215             sub class_exists {
216 2     2 1 17 _debug(\@_, 1) if DEBUG;
217 2 100       24 _namespace_occupied($_[1]) or _file_exists($_[1]);
218             }
219              
220             # A more general method to answer the question
221             # "Can I call a method on this class and expect it to work"
222             # Returns undef if the class does not exist
223             # Returns 0 if the class is not loaded ( or autouse'd )
224             # Returns 1 if the class can be used.
225             sub can_call_methods {
226 0     0 0 0 _debug(\@_, 1) if DEBUG;
227 0 0       0 _namespace_occupied($_[1]) or exists $INC{_class_file($_[1])};
228             }
229              
230             # Recursive methods currently only work withing the scope of the single @INC
231             # entry containing the "top" module, and will probably stay this way
232              
233             # Autouse not only a class, but all others below it.
234             sub autouse_recursive {
235 2     2 1 19 _debug(\@_, 1) if DEBUG;
236              
237             # Just load if in devel mode
238 2 100       27 return Class::Autouse->load_recursive($_[1]) if $DEVEL;
239              
240             # Don't need to do anything if the super loader is on
241 1 50       11 return 1 if $SUPERLOAD;
242              
243             # Find all the child classes, and hand them to the autouse method
244 1         12 Class::Autouse->autouse( $_[1], _child_classes($_[1]) );
245             }
246              
247             # Load not only a class and all others below it
248             sub load_recursive {
249 1     1 1 9 _debug(\@_, 1) if DEBUG;
250              
251             # Load the parent class, and its children
252 1         12 foreach ( $_[1], _child_classes($_[1]) ) {
253 2         56 Class::Autouse->load($_);
254             }
255              
256 1         14 1;
257             }
258              
259              
260              
261              
262              
263             #####################################################################
264             # Symbol Table Hooks
265              
266             # These get hooked to various places on the symbol table,
267             # to enable the autoload functionality
268              
269             # Get's linked via the symbol table to any AUTOLOADs are required
270             sub _AUTOLOAD {
271 8     8   72 _debug(\@_, 0, ", AUTOLOAD = '$Class::Autouse::AUTOLOAD'") if DEBUG;
272              
273             # Loop detection ( Just in case )
274 8 50       91 my $method = $Class::Autouse::AUTOLOAD or _cry('Missing method name');
275 8 50       106 _cry("Undefined subroutine &$method called") if ++$chased{ $method } > 10;
276              
277             # Don't bother with special classes
278 8         131 my ($class, $function) = $method =~ m/^(.*)::(.*)$/s;
279 8 50       92 _cry("Undefined subroutine &$method called") if $SPECIAL{$class};
280              
281             # Load the class and it's dependancies, and get the search path
282 8         97 my @search = Class::Autouse->load($class);
283              
284             # Find and go to the named method
285 8     10   98 my $found = List::Util::first { defined *{"${_}::$function"}{CODE} } @search;
  10         89  
  10         125  
286 8 50       124 goto &{"${found}::$function"} if $found;
  8         122  
287              
288             # Check for package AUTOLOADs
289 0         0 foreach my $c ( @search ) {
290 0 0       0          if ( defined *{"${c}::AUTOLOAD"}{CODE} ) {
  0         0  
291             # Simulate a normal autoload call
292 0         0          ${"${c}::AUTOLOAD"} = $method;
  0         0  
293 0         0          goto &{"${c}::AUTOLOAD"};
  0         0  
294                      }
295             }
296              
297             # Can't find the method anywhere. Throw the same error Perl does.
298 0         0 _cry("Can't locate object method \"$function\" via package \"$class\"");
299             }
300              
301             # This just handles the call and does nothing
302             sub _DESTROY {
303 0     0   0 _debug(\@_) if DEBUG;
304             }
305              
306             # This is the replacement for UNIVERSAL::isa
307             sub _isa {
308 30   66 30   5027 my $class = ref $_[0] || $_[0] || return undef;
      33        
309              
310             # Shortcut for the most likely cases
311 30 100 66     328 if ( $LOADED{$class} or defined @{"${class}::ISA"} ) {
  30         409  
312 24         188 goto &{$orig_isa};
  24         543  
313             }
314              
315 6         75 _preload_class($orig_isa, @_);
316             }
317              
318             # This is the replacement for UNIVERSAL::can
319             sub _can {
320 6534   100 6534   113620 my $class = ref $_[0] || $_[0] || return undef;
      66        
321              
322             # Shortcut for the most likely cases
323 6533 100 66     84553 if ( $LOADED{$class} or defined @{"${class}::ISA"} ) {
  6533         126149  
324 6529         68136 goto &{$orig_can};
  6529         275916  
325             }
326              
327 4         43 _preload_class($orig_can, @_);
328             }
329              
330             sub _preload_class {
331 10     10   212 my $orig = shift;
332 10   33     151 my $class = ref $_[0] || $_[0] || return undef;
      33        
333              
334             # Does it look like a package?
335 10 100       206 $class =~ /^[^\W\d]\w*(?:(?:'|::)[^\W\d]\w*)*$/o or return undef;
336              
337             # Do we try to load the class
338 9         82 my $load = 0;
339 9         94 my $file = _class_file($class);
340 9 100 66     1935 if ( defined $INC{$file} and $INC{$file} eq 'Class::Autouse' ) {
    50          
    0          
341             # It's an autoused class
342 4         38 $load = 1;
343             } elsif ( ! $SUPERLOAD ) {
344             # Superloader isn't on, don't load
345 5         89 $load = 0;
346             } elsif ( _namespace_occupied($class) ) {
347             # Superloader is on, but there is something already in the class
348             # This can't be the autouse loader, because we would have caught
349             # that case already.
350 0         0 $load = 0;
351             } else {
352             # The rules of the superloader say we assume loaded unless we can
353             # tell otherwise. Thus, we have to have a go at loading.
354 0         0 $load = 1;
355             }
356              
357             # If needed, load the class and all its dependencies.
358 9 100       92 if ( $load ) {
359 4         67 eval { Class::Autouse->load($class) };
  4         50  
360 4 100       46 die $@ if $@;
361             }
362              
363             # Hand off to the real function
364 8         69 goto &{$orig};;
  8         183  
365             }
366              
367              
368              
369              
370              
371             #####################################################################
372             # Support Functions
373              
374             # Load a single class
375             sub _load ($) {
376 21     21   205 _debug(\@_) if DEBUG;
377              
378             # Don't attempt to load special classes
379 21 50       222 my $class = shift or _cry('Did not specify a class to load');
380 21 50       212 return 1 if $SPECIAL{$class};
381              
382             # Run some checks
383 21         277 my $file = _class_file($class);
384 21 100       269 if ( defined $INC{$file} ) {
    50          
385             # If the %INC lock is set to any other value, the file is
386             # already loaded. We do not need to do anything.
387 20 100       225 return $LOADED{$class} = 1 if $INC{$file} ne 'Class::Autouse';
388              
389             # Because we autoused it earlier, we know the file for this
390             # class MUST exist.
391             # Removing the AUTOLOAD hook and %INC lock is all we have to do
392 16         1950 delete ${"${class}::"}{'AUTOLOAD'};
  16         361  
393 16         170 delete $INC{$file};
394              
395             } elsif ( ! _file_exists($file) ) {
396             # File doesn't exist. We might still be OK, if the class was
397             # defined in some other module that got loaded a different way.
398 0 0       0 return $LOADED{$class} = 1 if _namespace_occupied($class);
399 0         0 my $inc = join ', ', @INC;
400 0         0 _cry("Can't locate $file in \@INC (\@INC contains: $inc)");
401             }
402              
403             # Load the file
404 17         2311 print _call_depth(1) . " Class::Autouse::load -> Loading in $file\n" if DEBUG;
405 17         150 eval {
406 17         44421 CORE::require($file);
407             };
408 17 100       241 _cry($@) if $@;
409              
410             # Give back UNIVERSAL::can/isa if there are no other hooks
411 16 100       276 --$HOOKS or _UPDATE_HOOKS();
412              
413 16         207 $LOADED{$class} = 1;
414             }
415              
416             # Find all the child classes for a parent class.
417             # Returns in the list context.
418             sub _child_classes ($) {
419 2     2   18 _debug(\@_) if DEBUG;
420              
421             # Find where it is in @INC
422 2         24 my $base_file = _class_file(shift);
423             my $inc_path = List::Util::first {
424 2     2   44 -f File::Spec->catfile($_, $base_file)
425 2 50       20 } @INC or return;
426              
427             # Does the file have a subdirectory
428             # i.e. Are there child classes
429 2         41 my $child_path = substr( $base_file, 0, length($base_file) - 3 );
430 2         24 my $child_path_full = File::Spec->catdir( $inc_path, $child_path );
431 2 50 33     162 return 0 unless -d $child_path_full and -r _;
432              
433             # Main scan loop
434 2         20 local *FILELIST;
435 2         20 my ($dir, @files, @modules) = ();
436 2         21 my @queue = ( $child_path );
437 2         25 while ( $dir = pop @queue ) {
438 3         37 my $full_dir = File::Spec->catdir($inc_path, $dir);
439              
440             # Read in the raw file list
441             # Skip directories we can't open
442 3 50       422 opendir( FILELIST, $full_dir ) or next;
443 3         181 @files = readdir FILELIST;
444 3         54 closedir FILELIST;
445              
446             # Iterate over them
447 5         74 @files = map { File::Spec->catfile($dir, $_) } # Full relative path
  11         233  
448 3         30 grep { ! /^\./ } @files; # Ignore hidden files
449 3         34 foreach my $file ( @files ) {
450 5         58 my $full_file = File::Spec->catfile($inc_path, $file);
451              
452             # Add to the queue if its a directory we can descend
453 5 100 66     378 if ( -d $full_file and -r _ ) {
454 1         10 push @queue, $file;
455 1         11 next;
456             }
457              
458             # We only want .pm files we can read
459 4 50       51 next unless substr( $file, length($file) - 3 ) eq '.pm';
460 4 50       40 next unless -f _;
461              
462 4         53 push @modules, $file;
463             }
464             }
465              
466             # Convert the file names into modules
467 4         79 map { join '::', File::Spec->splitdir($_) }
  4         45  
468 2         21 map { substr($_, 0, length($_) - 3) } @modules;
469             }
470              
471              
472              
473              
474              
475             #####################################################################
476             # Private support methods
477              
478             # Does a class or file exists somewhere in our include path. For
479             # convenience, returns the unresolved file name ( even if passed a class )
480             sub _file_exists ($) {
481 18     18   152 _debug(\@_) if DEBUG;
482              
483             # What are we looking for?
484 18 50       193 my $file = shift or return undef;
485 18 50       220 return undef if $file =~ m/(?:\012|\015)/o;
486              
487             # If provided a class name, convert it
488 18 100       199 $file = _class_file($file) if $file =~ /::/o;
489              
490             # Scan @INC for the file
491 18         175 foreach ( @INC ) {
492 27 100       430 return $file if -f File::Spec->catfile($_, $file);
493             }
494              
495 1         23 undef;
496             }
497              
498             # Is a namespace occupied by anything significant
499             sub _namespace_occupied ($) {
500 2     2   16 _debug(\@_) if DEBUG;
501              
502             # Handle the most likely case
503 2 50       25 my $class = shift or return undef;
504 2 100       18 return 1 if defined @{"${class}::ISA"};
  2         40  
505              
506             # Get the list of glob names, ignoring namespaces
507 1         9 foreach ( keys %{"${class}::"} ) {
  1         18  
508 0 0       0 next if substr($_, -2) eq '::';
509              
510             # Only check for methods, since that's all that's reliable
511 0 0       0 return 1 if defined *{"${class}::$_"}{CODE};
  0         0  
512             }
513              
514 1         18 '';
515             }
516              
517             # For a given class, get the file name
518             sub _class_file ($) {
519 49     49   831 join( '/', split /(?:\'|::)/, shift ) . '.pm';
520             }
521              
522             # Establish our call depth
523             sub _call_depth {
524 1     1   9 my $spaces = shift;
525 1         9 if ( DEBUG and ! $spaces ) { _debug(\@_) }
526              
527             # Search up the caller stack to find the first call that isn't us.
528 1         9 my $level = 0;
529 1         13 while( $level++ < 1000 ) {
530 4         69 my @call = caller($level);
531 4         84 my ($subclass) = $call[3] =~ m/^(.*)::/so;
532 4 100 66     58 unless ( defined $subclass and $subclass eq 'Class::Autouse' ) {
533             # Subtract 1 for this sub's call
534 1         9 $level -= 1;
535 1 50       15 return $spaces ? join( '', (' ') x ($level - 2)) : $level;
536             }
537             }
538              
539 0         0 Carp::croak( "Infinite loop trying to find call depth" );
540             }
541              
542             # Die gracefully
543             sub _cry {
544 1     1   9 _debug() if DEBUG;
545 1         10 local $Carp::CarpLevel;
546 1         12 $Carp::CarpLevel += _call_depth();
547 1         15 Carp::croak( $_[0] );
548             }
549              
550             # Adaptive debug print generation
551             BEGIN {
552 7     7   147 eval <<'END_DEBUG' if DEBUG;
553            
554             sub _debug {
555             my $args = shift;
556             my $method = !! shift;
557             my $message = shift || '';
558             my @c = caller(1);
559             my $msg = _call_depth(1) . $c[3];
560             if ( ref $args ) {
561             my @mapped = map { "'$_'" } @$args;
562             shift @mapped if $method;
563             $msg .= @mapped ? '( ' . ( join ', ', @mapped ) . ' )' : '()';
564             }
565             print "$msg$message\n";
566             }
567            
568             END_DEBUG
569             }
570              
571              
572              
573              
574              
575             #####################################################################
576             # Final Initialisation
577              
578             # The _UPDATE_HOOKS function is intended to turn our hijacking of UNIVERSAL::can
579             # on or off, depending on whether we have any live hooks. The idea being, if we
580             # don't have any live hooks, why bother intercepting UNIVERSAL::can calls?
581             sub _UPDATE_HOOKS () {
582 17     17   251 local $^W = 0;
583 17 100       2228 *UNIVERSAL::can = $HOOKS ? \&_can : $orig_can;
584 17 100       2082 *UNIVERSAL::isa = $HOOKS ? \&_isa : $orig_isa;
585             }
586              
587             BEGIN {
588             # Optional integration with prefork.pm (if installed)
589 7     7   135 eval { require prefork };
  7         218  
590 7 50       102 if ( $@ ) {
591             # prefork is not installed.
592             # Do manual detection of mod_perl
593 0 0       0 $DEVEL = 1 if $ENV{MOD_PERL};
594             } else {
595             # Go into devel mode when prefork is enabled
596 7         189 $LOADED{prefork} = 1;
597 7         958 eval "prefork::notify( sub { Class::Autouse->devel(1) } )";
598 7 50       293 die $@ if $@;
599             }
600             }
601              
602             1;
603              
604             __END__
605            
606             =pod
607            
608             =head1 NAME
609            
610             Class::Autouse - Run-time load a class the first time you call a method in it.
611            
612             =head1 SYNOPSIS
613            
614             # Debugging (if you go that way) must be set before the first use
615             BEGIN {
616             $Class::Autouse::DEBUG = 1;
617             }
618            
619             # Load a class on method call
620             use Class::Autouse;
621             Class::Autouse->autouse( 'CGI' );
622             print CGI->b('Wow!');
623            
624             # Use as a pragma
625             use Class::Autouse qw{CGI};
626            
627             # Turn on developer mode
628             use Class::Autouse qw{:devel};
629            
630             # Turn on the Super Loader
631             use Class::Autouse qw{:superloader};
632            
633             # Disable module-existance check, and thus one additional 'stat'
634             # per module, at autouse-time if loading modules off a remote
635             # network drive such as NFS or SMB.
636             use Class::Autouse qw{:nostat};
637            
638             =head1 DESCRIPTION
639            
640             C<Class::Autouse> allows you to specify a class the will only load when a
641             method of that class is called. For large classes that might not be used
642             during the running of a program, such as L<Date::Manip>, this can save
643             you large amounts of memory, and decrease the script load time a great deal.
644            
645             =head2 Class, not Module
646            
647             The terminology "class loading" instead of "module loading" is used
648             intentionally. Modules will only be loaded if they are acting as a class.
649            
650             That is, they will only be loaded during a Class-E<gt>method call. If you try
651             to use a subroutine directly, say with C<Class::method()>, the class will
652             not be loaded and a fatal error will mostly likely occur.
653            
654             This limitation is made to allow more powerfull features in other areas,
655             because the module can focus on just loading the modules, and not have
656             to deal with importing.
657            
658             And really, if you are doing OO Perl, you should be avoiding importing
659             wherever possible.
660            
661             =head2 Use as a pragma
662            
663             Class::Autouse can be used as a pragma, specifying a list of classes
664             to load as the arguments. For example
665            
666             use Class::Autouse qw{CGI Data::Manip This::That};
667            
668             is equivalent to
669            
670             use Class::Autouse;
671             Class::Autouse->autouse( 'CGI' );
672             Class::Autouse->autouse( 'Data::Manip' );
673             Class::Autouse->autouse( 'This::That' );
674            
675             =head2 Developer Mode
676            
677             C<Class::Autouse> features a developer mode. In developer mode, classes
678             are loaded immediately, just like they would be with a normal 'use'
679             statement (although the import sub isn't called).
680            
681             This allows error checking to be done while developing, at the expense of
682             a larger memory overhead. Developer mode is turned on either with the
683             C<devel> method, or using :devel in any of the pragma arguments.
684             For example, this would load CGI.pm immediately
685            
686             use Class::Autouse qw{:devel CGI};
687            
688             While developer mode is roughly equivalent to just using a normal use
689             command, for a large number of modules it lets you use autoloading
690             notation, and just comment or uncomment a single line to turn developer
691             mode on or off. You can leave it on during development, and turn it
692             off for speed reasons when deploying.
693            
694             =head2 No-Stat Mode
695            
696             For situations where a module exists on a remote disk or another relatively
697             expensive location, you can call C<Class::Autouse> with the :nostat param
698             to disable initial file existance checking at hook time.
699            
700             # Disable autoload-time file existance checking
701             use Class::Autouse qw{:nostat};
702            
703             =head2 Super Loader Mode
704            
705             Turning on the C<Class::Autouse> super loader allows you to automatically
706             load B<ANY> class without specifying it first. Thus, the following will
707             work and is completely legal.
708            
709             use Class::Autouse qw{:superloader};
710            
711             print CGI->b('Wow!');
712            
713             The super loader can be turned on with either the
714             C<Class::Autouse-E<gt>>superloader> method, or the C<:superloader> pragma
715             argument.
716            
717             Please note that unlike the normal one-at-a-time autoloading, the
718             super-loader makes global changes, and so is not completely self-contained.
719            
720             It has the potential to cause unintended effects at a distance. If you
721             encounter unusual behaviour, revert to autousing one-at-a-time, or use
722             the recursive loading.
723            
724             Use of the Super Loader is highly discouraged for widely distributed
725             public applications or modules unless unavoidable. B<Do not use> just
726             to be lazy and save a few lines of code.
727            
728             =head2 Recursive Loading
729            
730             As an alternative to the super loader, the C<autouse_recursive> and
731             C<load_recursive> methods can be used to autouse or load an entire tree
732             of classes.
733            
734             For example, the following would give you access to all the L<URI>
735             related classes installed on the machine.
736            
737             Class::Autouse->autouse_recursive( 'URI' );
738            
739             Please note that the loadings will only occur down a single branch of the
740             include path, whichever the top class is located in.
741            
742             =head2 mod_perl
743            
744             The mechanism that C<Class::Autouse> uses is not compatible with L<mod_perl>.
745             In particular with reloader modules like L<Apache::Reload>. C<Class::Autouse>
746             detects the presence of mod_perl and acts as normal, but will always load
747             all classes immediately, equivalent to having developer mode enabled.
748            
749             This is actually beneficial, as under mod_perl classes should be preloaded
750             in the parent mod_perl process anyway, to prevent them having to be loaded
751             by the Apache child classes. It also saves HUGE amounts of memory.
752            
753             =head2 prefork
754            
755             As for mod_perl, C<Class::Autouse> is compatible with the L<prefork> module,
756             and all modules autoloaded will be loaded before forking correctly, when
757             requested by L<prefork>.
758            
759             =head2 The Internal Debugger
760            
761             Class::Autouse provides an internal debugger, which can be used to debug
762             any weird edge cases you might encounter when using it.
763            
764             If the C<$Class::Autouse::DEBUG> variable is true when C<Class::Autouse>
765             is first loaded, debugging will be compiled in. This debugging prints
766             output like the following to STDOUT.
767            
768             Class::Autouse::autouse_recursive( 'Foo' )
769             Class::Autouse::_recursive( 'Foo', 'load' )
770             Class::Autouse::load( 'Foo' )
771             Class::Autouse::_child_classes( 'Foo' )
772             Class::Autouse::load( 'Foo::Bar' )
773             Class::Autouse::_file_exists( 'Foo/Bar.pm' )
774             Class::Autouse::load -> Loading in Foo/Bar.pm
775             Class::Autouse::load( 'Foo::More' )
776             etc...
777            
778             Please note that because this is optimised out if not used, you can
779             no longer (since 1.20) enable debugging at run-time. This decision was
780             made to remove a large number of unneeded branching and speed up loading.
781            
782             =head1 METHODS
783            
784             =head2 autouse $class, ...
785            
786             The autouse method sets one or more classes to be loaded as required.
787            
788             =head2 load $class
789            
790             The load method loads one or more classes into memory. This is functionally
791             equivalent to using require to load the class list in, except that load
792             will detect and remove the autoloading hook from a previously autoused
793             class, whereas as use effectively ignore the class, and not load it.
794            
795             =head2 devel
796            
797             The devel method sets development mode on (argument of 1) or off
798             (argument of 0).
799            
800             If any classes have previously been autouse'd and not loaded when this
801             method is called, they will be loaded immediately.
802            
803             =head2 superloader
804            
805             The superloader method turns on the super loader.
806            
807             Please note that once you have turned the superloader on, it cannot be
808             turned off. This is due to code that might be relying on it being there not
809             being able to autoload its classes when another piece of code decides
810             they don't want it any more, and turns the superloader off.
811            
812             =head2 class_exists $class
813            
814             Handy method when doing the sort of jobs that C<Class::Autouse> does. Given
815             a class name, it will return true if the class can be loaded ( i.e. in @INC ),
816             false if the class can't be loaded, and undef if the class name is invalid.
817            
818             Note that this does not actually load the class, just tests to see if it can
819             be loaded. Loading can still fail. For a more comprehensive set of methods
820             of this nature, see L<Class::Inspector>.
821            
822             =head2 autouse_recursive $class
823            
824             The same as the C<autouse> method, but autouses recursively.
825            
826             =head2 load_recursive $class
827            
828             The same as the C<load> method, but loads recursively. Great for checking that
829             a large class tree that might not always be loaded will load correctly.
830            
831             =head1 SUPPORT
832            
833             Bugs should be always be reported via the CPAN bug tracker at
834            
835             L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Autouse>
836            
837             For other issues, or commercial enhancement or support, contact the author.
838            
839             =head1 AUTHORS
840            
841             Adam Kennedy (Creator and Maintainer), L<http://ali.as/>, cpan@ali.as
842            
843             Rob Napier (No longer involved), rnapier@employees.org
844            
845             =head1 SEE ALSO
846            
847             L<autoload>, L<autoclass>
848            
849             =head1 COPYRIGHT
850            
851             Copyright (c) 2002 - 2006 Adam Kennedy. All rights reserved.
852            
853             This program is free software; you can redistribute
854             it and/or modify it under the same terms as Perl itself.
855            
856             The full text of the license can be found in the
857             LICENSE file included with this module.
858            
859             =cut
860