Upgrade to Pod-Simple-3.08
[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.64';
13 our (%Cache);
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   if ($pkg eq "Exporter" and @_ and $_[0] eq "import") {
33     *{$callpkg."::import"} = \&import;
34     return;
35   }
36
37   # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
38   my($exports, $fail) = (\@{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
39   return export $pkg, $callpkg, @_
40     if $Verbose or $Debug or @$fail > 1;
41   my $export_cache = ($Cache{$pkg} ||= {});
42   my $args = @_ or @_ = @$exports;
43
44   local $_;
45   if ($args and not %$export_cache) {
46     s/^&//, $export_cache->{$_} = 1
47       foreach (@$exports, @{"$pkg\::EXPORT_OK"});
48   }
49   my $heavy;
50   # Try very hard not to use {} and hence have to  enter scope on the foreach
51   # We bomb out of the loop with last as soon as heavy is set.
52   if ($args or $fail) {
53     ($heavy = (/\W/ or $args and not exists $export_cache->{$_}
54                or @$fail and $_ eq $fail->[0])) and last
55                  foreach (@_);
56   } else {
57     ($heavy = /\W/) and last
58       foreach (@_);
59   }
60   return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy;
61   local $SIG{__WARN__} = 
62         sub {require Carp; &Carp::carp};
63   # shortcut for the common case of no type character
64   *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_;
65 }
66
67 # Default methods
68
69 sub export_fail {
70     my $self = shift;
71     @_;
72 }
73
74 # Unfortunately, caller(1)[3] "does not work" if the caller is aliased as
75 # *name = \&foo.  Thus the need to create a lot of identical subroutines
76 # Otherwise we could have aliased them to export().
77
78 sub export_to_level {
79   goto &{as_heavy()};
80 }
81
82 sub export_tags {
83   goto &{as_heavy()};
84 }
85
86 sub export_ok_tags {
87   goto &{as_heavy()};
88 }
89
90 sub require_version {
91   goto &{as_heavy()};
92 }
93
94 1;
95 __END__
96
97 =head1 NAME
98
99 Exporter - Implements default import method for modules
100
101 =head1 SYNOPSIS
102
103 In module F<YourModule.pm>:
104
105   package YourModule;
106   require Exporter;
107   @ISA = qw(Exporter);
108   @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
109
110 or
111
112   package YourModule;
113   use Exporter 'import'; # gives you Exporter's import() method directly
114   @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
115
116 In other files which wish to use C<YourModule>:
117
118   use YourModule qw(frobnicate);      # import listed symbols
119   frobnicate ($left, $right)          # calls YourModule::frobnicate
120
121 Take a look at L</Good Practices> for some variants
122 you will like to use in modern Perl code.
123
124 =head1 DESCRIPTION
125
126 The Exporter module implements an C<import> method which allows a module
127 to export functions and variables to its users' namespaces. Many modules
128 use Exporter rather than implementing their own C<import> method because
129 Exporter provides a highly flexible interface, with an implementation optimised
130 for the common case.
131
132 Perl automatically calls the C<import> method when processing a
133 C<use> statement for a module. Modules and C<use> are documented
134 in L<perlfunc> and L<perlmod>. Understanding the concept of
135 modules and how the C<use> statement operates is important to
136 understanding the Exporter.
137
138 =head2 How to Export
139
140 The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
141 symbols that are going to be exported into the users name space by
142 default, or which they can request to be exported, respectively.  The
143 symbols can represent functions, scalars, arrays, hashes, or typeglobs.
144 The symbols must be given by full name with the exception that the
145 ampersand in front of a function is optional, e.g.
146
147     @EXPORT    = qw(afunc $scalar @array);   # afunc is a function
148     @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
149
150 If you are only exporting function names it is recommended to omit the
151 ampersand, as the implementation is faster this way.
152
153 =head2 Selecting What To Export
154
155 Do B<not> export method names!
156
157 Do B<not> export anything else by default without a good reason!
158
159 Exports pollute the namespace of the module user.  If you must export
160 try to use C<@EXPORT_OK> in preference to C<@EXPORT> and avoid short or
161 common symbol names to reduce the risk of name clashes.
162
163 Generally anything not exported is still accessible from outside the
164 module using the C<YourModule::item_name> (or C<< $blessed_ref->method >>)
165 syntax.  By convention you can use a leading underscore on names to
166 informally indicate that they are 'internal' and not for public use.
167
168 (It is actually possible to get private functions by saying:
169
170   my $subref = sub { ... };
171   $subref->(@args);            # Call it as a function
172   $obj->$subref(@args);        # Use it as a method
173
174 However if you use them for methods it is up to you to figure out
175 how to make inheritance work.)
176
177 As a general rule, if the module is trying to be object oriented
178 then export nothing. If it's just a collection of functions then
179 C<@EXPORT_OK> anything but use C<@EXPORT> with caution. For function and
180 method names use barewords in preference to names prefixed with
181 ampersands for the export lists.
182
183 Other module design guidelines can be found in L<perlmod>.
184
185 =head2 How to Import
186
187 In other files which wish to use your module there are three basic ways for
188 them to load your module and import its symbols:
189
190 =over 4
191
192 =item C<use YourModule;>
193
194 This imports all the symbols from YourModule's C<@EXPORT> into the namespace
195 of the C<use> statement.
196
197 =item C<use YourModule ();>
198
199 This causes perl to load your module but does not import any symbols.
200
201 =item C<use YourModule qw(...);>
202
203 This imports only the symbols listed by the caller into their namespace.
204 All listed symbols must be in your C<@EXPORT> or C<@EXPORT_OK>, else an error
205 occurs. The advanced export features of Exporter are accessed like this,
206 but with list entries that are syntactically distinct from symbol names.
207
208 =back
209
210 Unless you want to use its advanced features, this is probably all you
211 need to know to use Exporter.
212
213 =head1 Advanced features
214
215 =head2 Specialised Import Lists
216
217 If any of the entries in an import list begins with !, : or / then
218 the list is treated as a series of specifications which either add to
219 or delete from the list of names to import. They are processed left to
220 right. Specifications are in the form:
221
222     [!]name         This name only
223     [!]:DEFAULT     All names in @EXPORT
224     [!]:tag         All names in $EXPORT_TAGS{tag} anonymous list
225     [!]/pattern/    All names in @EXPORT and @EXPORT_OK which match
226
227 A leading ! indicates that matching names should be deleted from the
228 list of names to import.  If the first specification is a deletion it
229 is treated as though preceded by :DEFAULT. If you just want to import
230 extra names in addition to the default set you will still need to
231 include :DEFAULT explicitly.
232
233 e.g., F<Module.pm> defines:
234
235     @EXPORT      = qw(A1 A2 A3 A4 A5);
236     @EXPORT_OK   = qw(B1 B2 B3 B4 B5);
237     %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
238
239     Note that you cannot use tags in @EXPORT or @EXPORT_OK.
240     Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
241
242 An application using Module can say something like:
243
244     use Module qw(:DEFAULT :T2 !B3 A3);
245
246 Other examples include:
247
248     use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
249     use POSIX  qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
250
251 Remember that most patterns (using //) will need to be anchored
252 with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
253
254 You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
255 specifications are being processed and what is actually being imported
256 into modules.
257
258 =head2 Exporting without using Exporter's import method
259
260 Exporter has a special method, 'export_to_level' which is used in situations
261 where you can't directly call Exporter's import method. The export_to_level
262 method looks like:
263
264     MyPackage->export_to_level($where_to_export, $package, @what_to_export);
265
266 where C<$where_to_export> is an integer telling how far up the calling stack
267 to export your symbols, and C<@what_to_export> is an array telling what
268 symbols *to* export (usually this is C<@_>).  The C<$package> argument is
269 currently unused.
270
271 For example, suppose that you have a module, A, which already has an
272 import function:
273
274     package A;
275
276     @ISA = qw(Exporter);
277     @EXPORT_OK = qw ($b);
278
279     sub import
280     {
281         $A::b = 1;     # not a very useful import method
282     }
283
284 and you want to Export symbol C<$A::b> back to the module that called 
285 package A. Since Exporter relies on the import method to work, via 
286 inheritance, as it stands Exporter::import() will never get called. 
287 Instead, say the following:
288
289     package A;
290     @ISA = qw(Exporter);
291     @EXPORT_OK = qw ($b);
292
293     sub import
294     {
295         $A::b = 1;
296         A->export_to_level(1, @_);
297     }
298
299 This will export the symbols one level 'above' the current package - ie: to 
300 the program or module that used package A. 
301
302 Note: Be careful not to modify C<@_> at all before you call export_to_level
303 - or people using your package will get very unexplained results!
304
305 =head2 Exporting without inheriting from Exporter
306
307 By including Exporter in your C<@ISA> you inherit an Exporter's import() method
308 but you also inherit several other helper methods which you probably don't
309 want. To avoid this you can do
310
311   package YourModule;
312   use Exporter qw( import );
313
314 which will export Exporter's own import() method into YourModule.
315 Everything will work as before but you won't need to include Exporter in
316 C<@YourModule::ISA>.
317
318 Note: This feature was introduced in version 5.57
319 of Exporter, released with perl 5.8.3.
320
321 =head2 Module Version Checking
322
323 The Exporter module will convert an attempt to import a number from a
324 module into a call to C<< $module_name->require_version($value) >>. This can
325 be used to validate that the version of the module being used is
326 greater than or equal to the required version.
327
328 The Exporter module supplies a default C<require_version> method which
329 checks the value of C<$VERSION> in the exporting module.
330
331 Since the default C<require_version> method treats the C<$VERSION> number as
332 a simple numeric value it will regard version 1.10 as lower than
333 1.9. For this reason it is strongly recommended that you use numbers
334 with at least two decimal places, e.g., 1.09.
335
336 =head2 Managing Unknown Symbols
337
338 In some situations you may want to prevent certain symbols from being
339 exported. Typically this applies to extensions which have functions
340 or constants that may not exist on some systems.
341
342 The names of any symbols that cannot be exported should be listed
343 in the C<@EXPORT_FAIL> array.
344
345 If a module attempts to import any of these symbols the Exporter
346 will give the module an opportunity to handle the situation before
347 generating an error. The Exporter will call an export_fail method
348 with a list of the failed symbols:
349
350   @failed_symbols = $module_name->export_fail(@failed_symbols);
351
352 If the C<export_fail> method returns an empty list then no error is
353 recorded and all the requested symbols are exported. If the returned
354 list is not empty then an error is generated for each symbol and the
355 export fails. The Exporter provides a default C<export_fail> method which
356 simply returns the list unchanged.
357
358 Uses for the C<export_fail> method include giving better error messages
359 for some symbols and performing lazy architectural checks (put more
360 symbols into C<@EXPORT_FAIL> by default and then take them out if someone
361 actually tries to use them and an expensive check shows that they are
362 usable on that platform).
363
364 =head2 Tag Handling Utility Functions
365
366 Since the symbols listed within C<%EXPORT_TAGS> must also appear in either
367 C<@EXPORT> or C<@EXPORT_OK>, two utility functions are provided which allow
368 you to easily add tagged sets of symbols to C<@EXPORT> or C<@EXPORT_OK>:
369
370   %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
371
372   Exporter::export_tags('foo');     # add aa, bb and cc to @EXPORT
373   Exporter::export_ok_tags('bar');  # add aa, cc and dd to @EXPORT_OK
374
375 Any names which are not tags are added to C<@EXPORT> or C<@EXPORT_OK>
376 unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
377 names being silently added to C<@EXPORT> or C<@EXPORT_OK>. Future versions
378 may make this a fatal error.
379
380 =head2 Generating combined tags
381
382 If several symbol categories exist in C<%EXPORT_TAGS>, it's usually
383 useful to create the utility ":all" to simplify "use" statements.
384
385 The simplest way to do this is:
386
387   %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
388
389   # add all the other ":class" tags to the ":all" class,
390   # deleting duplicates
391   {
392     my %seen;
393
394     push @{$EXPORT_TAGS{all}},
395       grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
396   }
397
398 F<CGI.pm> creates an ":all" tag which contains some (but not really
399 all) of its categories.  That could be done with one small
400 change:
401
402   # add some of the other ":class" tags to the ":all" class,
403   # deleting duplicates
404   {
405     my %seen;
406
407     push @{$EXPORT_TAGS{all}},
408       grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
409         foreach qw/html2 html3 netscape form cgi internal/;
410   }
411
412 Note that the tag names in C<%EXPORT_TAGS> don't have the leading ':'.
413
414 =head2 C<AUTOLOAD>ed Constants
415
416 Many modules make use of C<AUTOLOAD>ing for constant subroutines to
417 avoid having to compile and waste memory on rarely used values (see
418 L<perlsub> for details on constant subroutines).  Calls to such
419 constant subroutines are not optimized away at compile time because
420 they can't be checked at compile time for constancy.
421
422 Even if a prototype is available at compile time, the body of the
423 subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
424 examine both the C<()> prototype and the body of a subroutine at
425 compile time to detect that it can safely replace calls to that
426 subroutine with the constant value.
427
428 A workaround for this is to call the constants once in a C<BEGIN> block:
429
430    package My ;
431
432    use Socket ;
433
434    foo( SO_LINGER );     ## SO_LINGER NOT optimized away; called at runtime
435    BEGIN { SO_LINGER }
436    foo( SO_LINGER );     ## SO_LINGER optimized away at compile time.
437
438 This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
439 SO_LINGER is encountered later in C<My> package.
440
441 If you are writing a package that C<AUTOLOAD>s, consider forcing
442 an C<AUTOLOAD> for any constants explicitly imported by other packages
443 or which are usually used when your package is C<use>d.
444
445 =head1 Good Practices
446
447 =head2 Declaring C<@EXPORT_OK> and Friends
448
449 When using C<Exporter> with the standard C<strict> and C<warnings>
450 pragmas, the C<our> keyword is needed to declare the package
451 variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc.
452
453   our @ISA = qw(Exporter);
454   our @EXPORT_OK = qw(munge frobnicate);
455
456 If backward compatibility for Perls under 5.6 is important,
457 one must write instead a C<use vars> statement.
458
459   use vars qw(@ISA @EXPORT_OK);
460   @ISA = qw(Exporter);
461   @EXPORT_OK = qw(munge frobnicate);
462
463 =head2 Playing Safe
464
465 There are some caveats with the use of runtime statements
466 like C<require Exporter> and the assignment to package
467 variables, which can very subtle for the unaware programmer.
468 This may happen for instance with mutually recursive
469 modules, which are affected by the time the relevant
470 constructions are executed.
471
472 The ideal (but a bit ugly) way to never have to think
473 about that is to use C<BEGIN> blocks. So the first part
474 of the L</SYNOPSIS> code could be rewritten as:
475
476   package YourModule;
477
478   use strict;
479   use warnings;
480
481   our (@ISA, @EXPORT_OK);
482   BEGIN {
483      require Exporter;
484      @ISA = qw(Exporter);
485      @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
486   }
487
488 The C<BEGIN> will assure that the loading of F<Exporter.pm>
489 and the assignments to C<@ISA> and C<@EXPORT_OK> happen
490 immediately, leaving no room for something to get awry
491 or just plain wrong.
492
493 With respect to loading C<Exporter> and inheriting, there
494 are alternatives with the use of modules like C<base> and C<parent>.
495
496   use base qw( Exporter );
497   # or
498   use parent qw( Exporter );
499
500 Any of these statements are nice replacements for
501 C<BEGIN { require Exporter; @ISA = qw(Exporter); }>
502 with the same compile-time effect. The basic difference
503 is that C<base> code interacts with declared C<fields>
504 while C<parent> is a streamlined version of the older
505 C<base> code to just establish the IS-A relationship.
506
507 For more details, see the documentation and code of
508 L<base> and L<parent>.
509
510 Another thorough remedy to that runtime vs. 
511 compile-time trap is to use L<Exporter::Easy>,
512 which is a wrapper of Exporter that allows all
513 boilerplate code at a single gulp in the
514 use statement.
515
516    use Exporter::Easy (
517        OK => [ qw(munge frobnicate) ],
518    );
519    # @ISA setup is automatic
520    # all assignments happen at compile time
521
522 =head2 What not to Export
523
524 You have been warned already in L</Selecting What To Export>
525 to not export:
526
527 =over 4
528
529 =item *
530
531 method names (because you don't need to
532 and that's likely to not do what you want),
533
534 =item *
535
536 anything by default (because you don't want to surprise your users...
537 badly)
538
539 =item *
540
541 anything you don't need to (because less is more)
542
543 =back
544
545 There's one more item to add to this list. Do B<not>
546 export variable names. Just because C<Exporter> lets you
547 do that, it does not mean you should.
548
549   @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
550
551 Exporting variables is not a good idea. They can
552 change under the hood, provoking horrible
553 effects at-a-distance, that are too hard to track
554 and to fix. Trust me: they are not worth it.
555
556 To provide the capability to set/get class-wide
557 settings, it is best instead to provide accessors
558 as subroutines or class methods instead.
559
560 =head1 SEE ALSO
561
562 C<Exporter> is definitely not the only module with
563 symbol exporter capabilities. At CPAN, you may find
564 a bunch of them. Some are lighter. Some
565 provide improved APIs and features. Peek the one
566 that fits your needs. The following is
567 a sample list of such modules.
568
569     Exporter::Easy
570     Exporter::Lite
571     Exporter::Renaming
572     Exporter::Tidy
573     Sub::Exporter / Sub::Installer
574     Perl6::Export / Perl6::Export::Attrs
575
576 =head1 LICENSE
577
578 This library is free software. You can redistribute it
579 and/or modify it under the same terms as Perl itself.
580
581 =cut
582
583
584