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