Win32 pacifying from mjd.
[perl.git] / lib / Exporter.pm
1 package Exporter;
2
3 require 5.006;
4
5 # Be lean.
6 #use strict;
7 #no strict 'refs';
8
9 our $Debug = 0;
10 our $ExportLevel = 0;
11 our $Verbose ||= 0;
12 our $VERSION = '5.566';
13 $Carp::Internal{Exporter} = 1;
14
15 sub as_heavy {
16   require Exporter::Heavy;
17   # Unfortunately, this does not work if the caller is aliased as *name = \&foo
18   # Thus the need to create a lot of identical subroutines
19   my $c = (caller(1))[3];
20   $c =~ s/.*:://;
21   \&{"Exporter::Heavy::heavy_$c"};
22 }
23
24 sub export {
25   goto &{as_heavy()};
26 }
27
28 sub import {
29   my $pkg = shift;
30   my $callpkg = caller($ExportLevel);
31
32   # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
33   my($exports, $export_cache, $fail)
34     = (\@{"$pkg\::EXPORT"}, \%{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
35   return export $pkg, $callpkg, @_
36     if $Verbose or $Debug or @$fail > 1;
37   my $args = @_ or @_ = @$exports;
38
39   local $_;
40   if ($args and not %$export_cache) {
41     s/^&//, $export_cache->{$_} = 1
42       foreach (@$exports, @{"$pkg\::EXPORT_OK"});
43   }
44   my $heavy;
45   # Try very hard not to use {} and hence have to  enter scope on the foreach
46   # We bomb out of the loop with last as soon as heavy is set.
47   if ($args or $fail) {
48     ($heavy = (/\W/ or $args and not exists $export_cache->{$_}
49                or @$fail and $_ eq $fail->[0])) and last
50                  foreach (@_);
51   } else {
52     ($heavy = /\W/) and last
53       foreach (@_);
54   }
55   return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy;
56   local $SIG{__WARN__} = 
57         sub {require Carp; &Carp::carp};
58   # shortcut for the common case of no type character
59   *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_;
60 }
61
62 # Default methods
63
64 sub export_fail {
65     my $self = shift;
66     @_;
67 }
68
69 # Unfortunately, caller(1)[3] "does not work" if the caller is aliased as
70 # *name = \&foo.  Thus the need to create a lot of identical subroutines
71 # Otherwise we could have aliased them to export().
72
73 sub export_to_level {
74   goto &{as_heavy()};
75 }
76
77 sub export_tags {
78   goto &{as_heavy()};
79 }
80
81 sub export_ok_tags {
82   goto &{as_heavy()};
83 }
84
85 sub require_version {
86   goto &{as_heavy()};
87 }
88
89 1;
90 __END__
91
92 =head1 NAME
93
94 Exporter - Implements default import method for modules
95
96 =head1 SYNOPSIS
97
98 In module YourModule.pm:
99
100   package YourModule;
101   require Exporter;
102   @ISA = qw(Exporter);
103   @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
104
105 In other files which wish to use YourModule:
106
107   use ModuleName qw(frobnicate);      # import listed symbols
108   frobnicate ($left, $right)          # calls YourModule::frobnicate
109
110 =head1 DESCRIPTION
111
112 The Exporter module implements an C<import> method which allows a module
113 to export functions and variables to its users' namespaces. Many modules
114 use Exporter rather than implementing their own C<import> method because
115 Exporter provides a highly flexible interface, with an implementation optimised
116 for the common case.
117
118 Perl automatically calls the C<import> method when processing a
119 C<use> statement for a module. Modules and C<use> are documented
120 in L<perlfunc> and L<perlmod>. Understanding the concept of
121 modules and how the C<use> statement operates is important to
122 understanding the Exporter.
123
124 =head2 How to Export
125
126 The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
127 symbols that are going to be exported into the users name space by
128 default, or which they can request to be exported, respectively.  The
129 symbols can represent functions, scalars, arrays, hashes, or typeglobs.
130 The symbols must be given by full name with the exception that the
131 ampersand in front of a function is optional, e.g.
132
133     @EXPORT    = qw(afunc $scalar @array);   # afunc is a function
134     @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
135
136 If you are only exporting function names it is recommended to omit the
137 ampersand, as the implementation is faster this way.
138
139 =head2 Selecting What To Export
140
141 Do B<not> export method names!
142
143 Do B<not> export anything else by default without a good reason!
144
145 Exports pollute the namespace of the module user.  If you must export
146 try to use @EXPORT_OK in preference to @EXPORT and avoid short or
147 common symbol names to reduce the risk of name clashes.
148
149 Generally anything not exported is still accessible from outside the
150 module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
151 syntax.  By convention you can use a leading underscore on names to
152 informally indicate that they are 'internal' and not for public use.
153
154 (It is actually possible to get private functions by saying:
155
156   my $subref = sub { ... };
157   $subref->(@args);            # Call it as a function
158   $obj->$subref(@args);        # Use it as a method
159
160 However if you use them for methods it is up to you to figure out
161 how to make inheritance work.)
162
163 As a general rule, if the module is trying to be object oriented
164 then export nothing. If it's just a collection of functions then
165 @EXPORT_OK anything but use @EXPORT with caution. For function and
166 method names use barewords in preference to names prefixed with
167 ampersands for the export lists.
168
169 Other module design guidelines can be found in L<perlmod>.
170
171 =head2 How to Import
172
173 In other files which wish to use your module there are three basic ways for
174 them to load your module and import its symbols:
175
176 =over 4
177
178 =item C<use ModuleName;>
179
180 This imports all the symbols from ModuleName's @EXPORT into the namespace
181 of the C<use> statement.
182
183 =item C<use ModuleName ();>
184
185 This causes perl to load your module but does not import any symbols.
186
187 =item C<use ModuleName qw(...);>
188
189 This imports only the symbols listed by the caller into their namespace.
190 All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error
191 occurs. The advanced export features of Exporter are accessed like this,
192 but with list entries that are syntactically distinct from symbol names.
193
194 =back
195
196 Unless you want to use its advanced features, this is probably all you
197 need to know to use Exporter.
198
199 =head1 Advanced features
200
201 =head2 Specialised Import Lists
202
203 If the first entry in an import list begins with !, : or / then the
204 list is treated as a series of specifications which either add to or
205 delete from the list of names to import. They are processed left to
206 right. Specifications are in the form:
207
208     [!]name         This name only
209     [!]:DEFAULT     All names in @EXPORT
210     [!]:tag         All names in $EXPORT_TAGS{tag} anonymous list
211     [!]/pattern/    All names in @EXPORT and @EXPORT_OK which match
212
213 A leading ! indicates that matching names should be deleted from the
214 list of names to import.  If the first specification is a deletion it
215 is treated as though preceded by :DEFAULT. If you just want to import
216 extra names in addition to the default set you will still need to
217 include :DEFAULT explicitly.
218
219 e.g., Module.pm defines:
220
221     @EXPORT      = qw(A1 A2 A3 A4 A5);
222     @EXPORT_OK   = qw(B1 B2 B3 B4 B5);
223     %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
224
225     Note that you cannot use tags in @EXPORT or @EXPORT_OK.
226     Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
227
228 An application using Module can say something like:
229
230     use Module qw(:DEFAULT :T2 !B3 A3);
231
232 Other examples include:
233
234     use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
235     use POSIX  qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
236
237 Remember that most patterns (using //) will need to be anchored
238 with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
239
240 You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
241 specifications are being processed and what is actually being imported
242 into modules.
243
244 =head2 Exporting without using Exporter's import method
245
246 Exporter has a special method, 'export_to_level' which is used in situations
247 where you can't directly call Exporter's import method. The export_to_level
248 method looks like:
249
250     MyPackage->export_to_level($where_to_export, $package, @what_to_export);
251
252 where $where_to_export is an integer telling how far up the calling stack
253 to export your symbols, and @what_to_export is an array telling what
254 symbols *to* export (usually this is @_).  The $package argument is
255 currently unused.
256
257 For example, suppose that you have a module, A, which already has an
258 import function:
259
260     package A;
261
262     @ISA = qw(Exporter);
263     @EXPORT_OK = qw ($b);
264
265     sub import
266     {
267         $A::b = 1;     # not a very useful import method
268     }
269
270 and you want to Export symbol $A::b back to the module that called 
271 package A. Since Exporter relies on the import method to work, via 
272 inheritance, as it stands Exporter::import() will never get called. 
273 Instead, say the following:
274
275     package A;
276     @ISA = qw(Exporter);
277     @EXPORT_OK = qw ($b);
278
279     sub import
280     {
281         $A::b = 1;
282         A->export_to_level(1, @_);
283     }
284
285 This will export the symbols one level 'above' the current package - ie: to 
286 the program or module that used package A. 
287
288 Note: Be careful not to modify '@_' at all before you call export_to_level
289 - or people using your package will get very unexplained results!
290
291
292 =head2 Module Version Checking
293
294 The Exporter module will convert an attempt to import a number from a
295 module into a call to $module_name-E<gt>require_version($value). This can
296 be used to validate that the version of the module being used is
297 greater than or equal to the required version.
298
299 The Exporter module supplies a default require_version method which
300 checks the value of $VERSION in the exporting module.
301
302 Since the default require_version method treats the $VERSION number as
303 a simple numeric value it will regard version 1.10 as lower than
304 1.9. For this reason it is strongly recommended that you use numbers
305 with at least two decimal places, e.g., 1.09.
306
307 =head2 Managing Unknown Symbols
308
309 In some situations you may want to prevent certain symbols from being
310 exported. Typically this applies to extensions which have functions
311 or constants that may not exist on some systems.
312
313 The names of any symbols that cannot be exported should be listed
314 in the C<@EXPORT_FAIL> array.
315
316 If a module attempts to import any of these symbols the Exporter
317 will give the module an opportunity to handle the situation before
318 generating an error. The Exporter will call an export_fail method
319 with a list of the failed symbols:
320
321   @failed_symbols = $module_name->export_fail(@failed_symbols);
322
323 If the export_fail method returns an empty list then no error is
324 recorded and all the requested symbols are exported. If the returned
325 list is not empty then an error is generated for each symbol and the
326 export fails. The Exporter provides a default export_fail method which
327 simply returns the list unchanged.
328
329 Uses for the export_fail method include giving better error messages
330 for some symbols and performing lazy architectural checks (put more
331 symbols into @EXPORT_FAIL by default and then take them out if someone
332 actually tries to use them and an expensive check shows that they are
333 usable on that platform).
334
335 =head2 Tag Handling Utility Functions
336
337 Since the symbols listed within %EXPORT_TAGS must also appear in either
338 @EXPORT or @EXPORT_OK, two utility functions are provided which allow
339 you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
340
341   %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
342
343   Exporter::export_tags('foo');     # add aa, bb and cc to @EXPORT
344   Exporter::export_ok_tags('bar');  # add aa, cc and dd to @EXPORT_OK
345
346 Any names which are not tags are added to @EXPORT or @EXPORT_OK
347 unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
348 names being silently added to @EXPORT or @EXPORT_OK. Future versions
349 may make this a fatal error.
350
351 =head2 Generating combined tags
352
353 If several symbol categories exist in %EXPORT_TAGS, it's usually
354 useful to create the utility ":all" to simplify "use" statements.
355
356 The simplest way to do this is:
357
358   %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
359
360   # add all the other ":class" tags to the ":all" class,
361   # deleting duplicates
362   {
363     my %seen;
364
365     push @{$EXPORT_TAGS{all}},
366       grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
367   }
368
369 CGI.pm creates an ":all" tag which contains some (but not really
370 all) of its categories.  That could be done with one small
371 change:
372
373   # add some of the other ":class" tags to the ":all" class,
374   # deleting duplicates
375   {
376     my %seen;
377
378     push @{$EXPORT_TAGS{all}},
379       grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
380         foreach qw/html2 html3 netscape form cgi internal/;
381   }
382
383 Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
384
385 =head2 C<AUTOLOAD>ed Constants
386
387 Many modules make use of C<AUTOLOAD>ing for constant subroutines to
388 avoid having to compile and waste memory on rarely used values (see
389 L<perlsub> for details on constant subroutines).  Calls to such
390 constant subroutines are not optimized away at compile time because
391 they can't be checked at compile time for constancy.
392
393 Even if a prototype is available at compile time, the body of the
394 subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
395 examine both the C<()> prototype and the body of a subroutine at
396 compile time to detect that it can safely replace calls to that
397 subroutine with the constant value.
398
399 A workaround for this is to call the constants once in a C<BEGIN> block:
400
401    package My ;
402
403    use Socket ;
404
405    foo( SO_LINGER );     ## SO_LINGER NOT optimized away; called at runtime
406    BEGIN { SO_LINGER }
407    foo( SO_LINGER );     ## SO_LINGER optimized away at compile time.
408
409 This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
410 SO_LINGER is encountered later in C<My> package.
411
412 If you are writing a package that C<AUTOLOAD>s, consider forcing
413 an C<AUTOLOAD> for any constants explicitly imported by other packages
414 or which are usually used when your package is C<use>d.
415
416 =cut