1Class::Autouse(3) User Contributed Perl Documentation Class::Autouse(3)
2
6 Class::Autouse - Run-time load a class the first time you call a method
7 in it.
8
10 # Debugging (if you go that way) must be set before the first use
11 BEGIN {
12 $Class::Autouse::DEBUG = 1;
13 }
14 # Load a class on method call
16 use Class::Autouse;
17 Class::Autouse->autouse( 'CGI' );
18 print CGI->b('Wow!');
19 # Use as a pragma
21 use Class::Autouse qw{CGI};
22 # Turn on developer mode
24 use Class::Autouse qw{:devel};
25 # Turn on the Super Loader
27 use Class::Autouse qw{:superloader};
28 # Disable module-existance check, and thus one additional 'stat'
30 # per module, at autouse-time if loading modules off a remote
31 # network drive such as NFS or SMB.
32 use Class::Autouse qw{:nostat};
33
35 "Class::Autouse" allows you to specify a class the will only load when
36 a method of that class is called. For large classes that might not be
37 used during the running of a program, such as Date::Manip, this can
38 save you large amounts of memory, and decrease the script load time a
39 great deal.
40 Class, not Module
42 The terminology "class loading" instead of "module loading" is used
44 intentionally. Modules will only be loaded if they are acting as a
45 class.
46 That is, they will only be loaded during a Class->method call. If you
48 try to use a subroutine directly, say with "Class::method()", the class
49 will not be loaded and a fatal error will mostly likely occur.
50 This limitation is made to allow more powerfull features in other
52 areas, because the module can focus on just loading the modules, and
53 not have to deal with importing.
54 And really, if you are doing OO Perl, you should be avoiding importing
56 wherever possible.
57 Use as a pragma
59 Class::Autouse can be used as a pragma, specifying a list of classes to
61 load as the arguments. For example
62 use Class::Autouse qw{CGI Data::Manip This::That};
64 is equivalent to
66 use Class::Autouse;
68 Class::Autouse->autouse( 'CGI' );
69 Class::Autouse->autouse( 'Data::Manip' );
70 Class::Autouse->autouse( 'This::That' );
71 Developer Mode
73 "Class::Autouse" features a developer mode. In developer mode, classes
75 are loaded immediately, just like they would be with a normal 'use'
76 statement (although the import sub isn't called).
77 This allows error checking to be done while developing, at the expense
79 of a larger memory overhead. Developer mode is turned on either with
80 the "devel" method, or using :devel in any of the pragma arguments.
81 For example, this would load CGI.pm immediately
82 use Class::Autouse qw{:devel CGI};
84 While developer mode is roughly equivalent to just using a normal use
86 command, for a large number of modules it lets you use autoloading
87 notation, and just comment or uncomment a single line to turn developer
88 mode on or off. You can leave it on during development, and turn it off
89 for speed reasons when deploying.
90 No-Stat Mode
92 For situations where a module exists on a remote disk or another rela‐
94 tively expensive location, you can call "Class::Autouse" with the :nos‐
95 tat param to disable initial file existance checking at hook time.
96 # Disable autoload-time file existance checking
98 use Class::Autouse qw{:nostat};
99 Super Loader Mode
101 Turning on the "Class::Autouse" super loader allows you to automati‐
103 cally load ANY class without specifying it first. Thus, the following
104 will work and is completely legal.
105 use Class::Autouse qw{:superloader};
107 print CGI->b('Wow!');
109 The super loader can be turned on with either the
111 "Class::Autouse->"superloader> method, or the ":superloader" pragma
112 argument.
113 Please note that unlike the normal one-at-a-time autoloading, the
115 super-loader makes global changes, and so is not completely self-con‐
116 tained.
117 It has the potential to cause unintended effects at a distance. If you
119 encounter unusual behaviour, revert to autousing one-at-a-time, or use
120 the recursive loading.
121 Use of the Super Loader is highly discouraged for widely distributed
123 public applications or modules unless unavoidable. Do not use just to
124 be lazy and save a few lines of code.
125 Recursive Loading
127 As an alternative to the super loader, the "autouse_recursive" and
129 "load_recursive" methods can be used to autouse or load an entire tree
130 of classes.
131 For example, the following would give you access to all the URI related
133 classes installed on the machine.
134 Class::Autouse->autouse_recursive( 'URI' );
136 Please note that the loadings will only occur down a single branch of
138 the include path, whichever the top class is located in.
139 mod_perl
141 The mechanism that "Class::Autouse" uses is not compatible with
143 mod_perl. In particular with reloader modules like Apache::Reload.
144 "Class::Autouse" detects the presence of mod_perl and acts as normal,
145 but will always load all classes immediately, equivalent to having
146 developer mode enabled.
147 This is actually beneficial, as under mod_perl classes should be pre‐
149 loaded in the parent mod_perl process anyway, to prevent them having to
150 be loaded by the Apache child classes. It also saves HUGE amounts of
151 memory.
152 prefork
154 As for mod_perl, "Class::Autouse" is compatible with the prefork mod‐
156 ule, and all modules autoloaded will be loaded before forking cor‐
157 rectly, when requested by prefork.
158 The Internal Debugger
160 Class::Autouse provides an internal debugger, which can be used to
162 debug any weird edge cases you might encounter when using it.
163 If the $Class::Autouse::DEBUG variable is true when "Class::Autouse" is
165 first loaded, debugging will be compiled in. This debugging prints out‐
166 put like the following to STDOUT.
167 Class::Autouse::autouse_recursive( 'Foo' )
169 Class::Autouse::_recursive( 'Foo', 'load' )
170 Class::Autouse::load( 'Foo' )
171 Class::Autouse::_child_classes( 'Foo' )
172 Class::Autouse::load( 'Foo::Bar' )
173 Class::Autouse::_file_exists( 'Foo/Bar.pm' )
174 Class::Autouse::load -> Loading in Foo/Bar.pm
175 Class::Autouse::load( 'Foo::More' )
176 etc...
177 Please note that because this is optimised out if not used, you can no
179 longer (since 1.20) enable debugging at run-time. This decision was
180 made to remove a large number of unneeded branching and speed up load‐
181 ing.
182
184 autouse $class, ...
185 The autouse method sets one or more classes to be loaded as required.
187 load $class
189 The load method loads one or more classes into memory. This is func‐
191 tionally equivalent to using require to load the class list in, except
192 that load will detect and remove the autoloading hook from a previously
193 autoused class, whereas as use effectively ignore the class, and not
194 load it.
195 devel
197 The devel method sets development mode on (argument of 1) or off (argu‐
199 ment of 0).
200 If any classes have previously been autouse'd and not loaded when this
202 method is called, they will be loaded immediately.
203 superloader
205 The superloader method turns on the super loader.
207 Please note that once you have turned the superloader on, it cannot be
209 turned off. This is due to code that might be relying on it being there
210 not being able to autoload its classes when another piece of code
211 decides they don't want it any more, and turns the superloader off.
212 class_exists $class
214 Handy method when doing the sort of jobs that "Class::Autouse" does.
216 Given a class name, it will return true if the class can be loaded (
217 i.e. in @INC ), false if the class can't be loaded, and undef if the
218 class name is invalid.
219 Note that this does not actually load the class, just tests to see if
221 it can be loaded. Loading can still fail. For a more comprehensive set
222 of methods of this nature, see Class::Inspector.
223 autouse_recursive $class
225 The same as the "autouse" method, but autouses recursively.
227 load_recursive $class
229 The same as the "load" method, but loads recursively. Great for check‐
231 ing that a large class tree that might not always be loaded will load
232 correctly.
233
235 Bugs should be always be reported via the CPAN bug tracker at
236 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Autouse>
238 For other issues, or commercial enhancement or support, contact the
240 author.
241
243 Adam Kennedy (Creator and Maintainer), <http://ali.as/>, cpan@ali.as
244 Rob Napier (No longer involved), rnapier@employees.org
246
248 autoload, autoclass
249
251 Copyright (c) 2002 - 2006 Adam Kennedy.
252 This program is free software; you can redistribute it and/or modify it
254 under the same terms as Perl itself.
255 The full text of the license can be found in the LICENSE file included
257 with this module.
258perl v5.8.8 2007-11-11 Class::Autouse(3)