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