This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Bump Exporter's version in blead after last patch
[perl5.git] / lib / Exporter.pm
CommitLineData
8990e307
LW
1package Exporter;
2
732bb7c2 3require 5.006;
8990e307 4
0e57b4e8
IZ
5# Be lean.
6#use strict;
7#no strict 'refs';
b75c8c73
MS
8
9our $Debug = 0;
10our $ExportLevel = 0;
11our $Verbose ||= 0;
3247c188 12our $VERSION = '5.64_01';
a6faae8d 13our (%Cache);
3e927c50 14
0e57b4e8 15sub as_heavy {
4af1b167 16 require Exporter::Heavy;
0e57b4e8
IZ
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"};
84902520
TB
22}
23
4af1b167 24sub export {
0e57b4e8 25 goto &{as_heavy()};
a0d0e21e
LW
26}
27
4af1b167
IZ
28sub import {
29 my $pkg = shift;
30 my $callpkg = caller($ExportLevel);
b75c8c73 31
fe43f860
FD
32 if ($pkg eq "Exporter" and @_ and $_[0] eq "import") {
33 *{$callpkg."::import"} = \&import;
34 return;
35 }
36
4af1b167 37 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
a6faae8d 38 my($exports, $fail) = (\@{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
4af1b167 39 return export $pkg, $callpkg, @_
b75c8c73 40 if $Verbose or $Debug or @$fail > 1;
a6faae8d 41 my $export_cache = ($Cache{$pkg} ||= {});
b75c8c73 42 my $args = @_ or @_ = @$exports;
732bb7c2
NC
43
44 local $_;
b75c8c73 45 if ($args and not %$export_cache) {
732bb7c2
NC
46 s/^&//, $export_cache->{$_} = 1
47 foreach (@$exports, @{"$pkg\::EXPORT_OK"});
4af1b167 48 }
fa1bb02f
NC
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) {
732bb7c2 53 ($heavy = (/\W/ or $args and not exists $export_cache->{$_}
fa1bb02f
NC
54 or @$fail and $_ eq $fail->[0])) and last
55 foreach (@_);
56 } else {
57 ($heavy = /\W/) and last
732bb7c2 58 foreach (@_);
4af1b167 59 }
732bb7c2 60 return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy;
4af1b167 61 local $SIG{__WARN__} =
bb2cbcd1 62 sub {require Carp; &Carp::carp};
732bb7c2
NC
63 # shortcut for the common case of no type character
64 *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_;
e50aee73
AD
65}
66
b75c8c73
MS
67# Default methods
68
2b5b2650 69sub export_fail {
b75c8c73
MS
70 my $self = shift;
71 @_;
2b5b2650
PP
72}
73
0e57b4e8
IZ
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().
b75c8c73 77
0e57b4e8
IZ
78sub export_to_level {
79 goto &{as_heavy()};
80}
81
82sub export_tags {
83 goto &{as_heavy()};
b75c8c73
MS
84}
85
0e57b4e8
IZ
86sub export_ok_tags {
87 goto &{as_heavy()};
88}
89
90sub require_version {
91 goto &{as_heavy()};
92}
b75c8c73 93
2b5b2650 941;
732bb7c2 95__END__
b75c8c73 96
2b5b2650
PP
97=head1 NAME
98
99Exporter - Implements default import method for modules
100
101=head1 SYNOPSIS
102
3e927c50 103In module F<YourModule.pm>:
2b5b2650 104
65503211 105 package YourModule;
2b5b2650
PP
106 require Exporter;
107 @ISA = qw(Exporter);
65503211 108 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
2b5b2650 109
fe43f860
FD
110or
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
3e927c50 116In other files which wish to use C<YourModule>:
2b5b2650 117
3e927c50 118 use YourModule qw(frobnicate); # import listed symbols
65503211 119 frobnicate ($left, $right) # calls YourModule::frobnicate
2b5b2650 120
47f97feb
AF
121Take a look at L</Good Practices> for some variants
122you will like to use in modern Perl code.
123
2b5b2650
PP
124=head1 DESCRIPTION
125
65503211
NC
126The Exporter module implements an C<import> method which allows a module
127to export functions and variables to its users' namespaces. Many modules
128use Exporter rather than implementing their own C<import> method because
129Exporter provides a highly flexible interface, with an implementation optimised
130for the common case.
2b5b2650
PP
131
132Perl automatically calls the C<import> method when processing a
133C<use> statement for a module. Modules and C<use> are documented
134in L<perlfunc> and L<perlmod>. Understanding the concept of
135modules and how the C<use> statement operates is important to
136understanding the Exporter.
137
4fddf32b
GS
138=head2 How to Export
139
140The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
141symbols that are going to be exported into the users name space by
142default, or which they can request to be exported, respectively. The
143symbols can represent functions, scalars, arrays, hashes, or typeglobs.
144The symbols must be given by full name with the exception that the
145ampersand 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
65503211
NC
150If you are only exporting function names it is recommended to omit the
151ampersand, as the implementation is faster this way.
152
2b5b2650
PP
153=head2 Selecting What To Export
154
155Do B<not> export method names!
156
157Do B<not> export anything else by default without a good reason!
158
159Exports pollute the namespace of the module user. If you must export
3e927c50 160try to use C<@EXPORT_OK> in preference to C<@EXPORT> and avoid short or
2b5b2650
PP
161common symbol names to reduce the risk of name clashes.
162
163Generally anything not exported is still accessible from outside the
3e927c50 164module using the C<YourModule::item_name> (or C<< $blessed_ref->method >>)
2b5b2650
PP
165syntax. By convention you can use a leading underscore on names to
166informally 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 { ... };
e60ce172
BT
171 $subref->(@args); # Call it as a function
172 $obj->$subref(@args); # Use it as a method
2b5b2650 173
e60ce172
BT
174However if you use them for methods it is up to you to figure out
175how to make inheritance work.)
2b5b2650
PP
176
177As a general rule, if the module is trying to be object oriented
178then export nothing. If it's just a collection of functions then
3e927c50 179C<@EXPORT_OK> anything but use C<@EXPORT> with caution. For function and
65503211
NC
180method names use barewords in preference to names prefixed with
181ampersands for the export lists.
2b5b2650
PP
182
183Other module design guidelines can be found in L<perlmod>.
184
65503211
NC
185=head2 How to Import
186
187In other files which wish to use your module there are three basic ways for
188them to load your module and import its symbols:
189
190=over 4
191
3e927c50 192=item C<use YourModule;>
65503211 193
3e927c50 194This imports all the symbols from YourModule's C<@EXPORT> into the namespace
65503211
NC
195of the C<use> statement.
196
3e927c50 197=item C<use YourModule ();>
65503211
NC
198
199This causes perl to load your module but does not import any symbols.
200
3e927c50 201=item C<use YourModule qw(...);>
65503211
NC
202
203This imports only the symbols listed by the caller into their namespace.
3e927c50 204All listed symbols must be in your C<@EXPORT> or C<@EXPORT_OK>, else an error
65503211
NC
205occurs. The advanced export features of Exporter are accessed like this,
206but with list entries that are syntactically distinct from symbol names.
207
208=back
209
210Unless you want to use its advanced features, this is probably all you
211need to know to use Exporter.
212
213=head1 Advanced features
214
2b5b2650
PP
215=head2 Specialised Import Lists
216
a29b0897
MB
217If any of the entries in an import list begins with !, : or / then
218the list is treated as a series of specifications which either add to
219or delete from the list of names to import. They are processed left to
2b5b2650
PP
220right. 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
227A leading ! indicates that matching names should be deleted from the
228list of names to import. If the first specification is a deletion it
229is treated as though preceded by :DEFAULT. If you just want to import
230extra names in addition to the default set you will still need to
231include :DEFAULT explicitly.
232
3e927c50 233e.g., F<Module.pm> defines:
2b5b2650
PP
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
242An application using Module can say something like:
243
244 use Module qw(:DEFAULT :T2 !B3 A3);
245
246Other examples include:
247
248 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
249 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
250
251Remember that most patterns (using //) will need to be anchored
252with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
253
254You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
255specifications are being processed and what is actually being imported
256into modules.
257
65503211 258=head2 Exporting without using Exporter's import method
84902520
TB
259
260Exporter has a special method, 'export_to_level' which is used in situations
65503211 261where you can't directly call Exporter's import method. The export_to_level
84902520
TB
262method looks like:
263
cec46e5a 264 MyPackage->export_to_level($where_to_export, $package, @what_to_export);
84902520 265
3e927c50
AF
266where C<$where_to_export> is an integer telling how far up the calling stack
267to export your symbols, and C<@what_to_export> is an array telling what
268symbols *to* export (usually this is C<@_>). The C<$package> argument is
ba5725f8 269currently unused.
84902520
TB
270
271For example, suppose that you have a module, A, which already has an
272import function:
273
cec46e5a 274 package A;
84902520 275
cec46e5a
RGS
276 @ISA = qw(Exporter);
277 @EXPORT_OK = qw ($b);
84902520 278
cec46e5a
RGS
279 sub import
280 {
281 $A::b = 1; # not a very useful import method
282 }
84902520 283
3e927c50 284and you want to Export symbol C<$A::b> back to the module that called
84902520
TB
285package A. Since Exporter relies on the import method to work, via
286inheritance, as it stands Exporter::import() will never get called.
287Instead, say the following:
288
cec46e5a
RGS
289 package A;
290 @ISA = qw(Exporter);
291 @EXPORT_OK = qw ($b);
84902520 292
cec46e5a
RGS
293 sub import
294 {
295 $A::b = 1;
296 A->export_to_level(1, @_);
297 }
84902520
TB
298
299This will export the symbols one level 'above' the current package - ie: to
300the program or module that used package A.
301
fe43f860 302Note: Be careful not to modify C<@_> at all before you call export_to_level
84902520
TB
303- or people using your package will get very unexplained results!
304
fe43f860
FD
305=head2 Exporting without inheriting from Exporter
306
3e927c50 307By including Exporter in your C<@ISA> you inherit an Exporter's import() method
fe43f860
FD
308but you also inherit several other helper methods which you probably don't
309want. To avoid this you can do
310
311 package YourModule;
312 use Exporter qw( import );
313
314which will export Exporter's own import() method into YourModule.
315Everything will work as before but you won't need to include Exporter in
3e927c50 316C<@YourModule::ISA>.
84902520 317
47f97feb
AF
318Note: This feature was introduced in version 5.57
319of Exporter, released with perl 5.8.3.
320
2b5b2650
PP
321=head2 Module Version Checking
322
323The Exporter module will convert an attempt to import a number from a
3e927c50 324module into a call to C<< $module_name->require_version($value) >>. This can
2b5b2650
PP
325be used to validate that the version of the module being used is
326greater than or equal to the required version.
327
3e927c50
AF
328The Exporter module supplies a default C<require_version> method which
329checks the value of C<$VERSION> in the exporting module.
2b5b2650 330
3e927c50 331Since the default C<require_version> method treats the C<$VERSION> number as
d5e40bcc
PP
332a simple numeric value it will regard version 1.10 as lower than
3331.9. For this reason it is strongly recommended that you use numbers
334with at least two decimal places, e.g., 1.09.
2b5b2650
PP
335
336=head2 Managing Unknown Symbols
337
338In some situations you may want to prevent certain symbols from being
339exported. Typically this applies to extensions which have functions
340or constants that may not exist on some systems.
341
342The names of any symbols that cannot be exported should be listed
343in the C<@EXPORT_FAIL> array.
344
7a2e2cd6 345If a module attempts to import any of these symbols the Exporter
2b5b2650
PP
346will give the module an opportunity to handle the situation before
347generating an error. The Exporter will call an export_fail method
348with a list of the failed symbols:
349
350 @failed_symbols = $module_name->export_fail(@failed_symbols);
351
3e927c50 352If the C<export_fail> method returns an empty list then no error is
2b5b2650
PP
353recorded and all the requested symbols are exported. If the returned
354list is not empty then an error is generated for each symbol and the
3e927c50 355export fails. The Exporter provides a default C<export_fail> method which
2b5b2650
PP
356simply returns the list unchanged.
357
3e927c50 358Uses for the C<export_fail> method include giving better error messages
2b5b2650 359for some symbols and performing lazy architectural checks (put more
3e927c50 360symbols into C<@EXPORT_FAIL> by default and then take them out if someone
2b5b2650
PP
361actually tries to use them and an expensive check shows that they are
362usable on that platform).
363
364=head2 Tag Handling Utility Functions
365
3e927c50
AF
366Since the symbols listed within C<%EXPORT_TAGS> must also appear in either
367C<@EXPORT> or C<@EXPORT_OK>, two utility functions are provided which allow
368you to easily add tagged sets of symbols to C<@EXPORT> or C<@EXPORT_OK>:
2b5b2650
PP
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
3e927c50 375Any names which are not tags are added to C<@EXPORT> or C<@EXPORT_OK>
d5e40bcc 376unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
3e927c50 377names being silently added to C<@EXPORT> or C<@EXPORT_OK>. Future versions
2b5b2650
PP
378may make this a fatal error.
379
d584343b
GME
380=head2 Generating combined tags
381
3e927c50 382If several symbol categories exist in C<%EXPORT_TAGS>, it's usually
d584343b
GME
383useful to create the utility ":all" to simplify "use" statements.
384
385The 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
3e927c50 398F<CGI.pm> creates an ":all" tag which contains some (but not really
d584343b
GME
399all) of its categories. That could be done with one small
400change:
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
3e927c50 412Note that the tag names in C<%EXPORT_TAGS> don't have the leading ':'.
d584343b 413
5fea0f12
BS
414=head2 C<AUTOLOAD>ed Constants
415
8b4c0206
T
416Many modules make use of C<AUTOLOAD>ing for constant subroutines to
417avoid having to compile and waste memory on rarely used values (see
418L<perlsub> for details on constant subroutines). Calls to such
419constant subroutines are not optimized away at compile time because
420they can't be checked at compile time for constancy.
421
422Even if a prototype is available at compile time, the body of the
423subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
424examine both the C<()> prototype and the body of a subroutine at
425compile time to detect that it can safely replace calls to that
426subroutine with the constant value.
5fea0f12
BS
427
428A 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
8b4c0206
T
438This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
439SO_LINGER is encountered later in C<My> package.
5fea0f12 440
8b4c0206
T
441If you are writing a package that C<AUTOLOAD>s, consider forcing
442an C<AUTOLOAD> for any constants explicitly imported by other packages
443or which are usually used when your package is C<use>d.
5fea0f12 444
47f97feb
AF
445=head1 Good Practices
446
447=head2 Declaring C<@EXPORT_OK> and Friends
448
449When using C<Exporter> with the standard C<strict> and C<warnings>
450pragmas, the C<our> keyword is needed to declare the package
451variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc.
452
453 our @ISA = qw(Exporter);
454 our @EXPORT_OK = qw(munge frobnicate);
455
456If backward compatibility for Perls under 5.6 is important,
457one 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
465There are some caveats with the use of runtime statements
466like C<require Exporter> and the assignment to package
467variables, which can very subtle for the unaware programmer.
468This may happen for instance with mutually recursive
469modules, which are affected by the time the relevant
470constructions are executed.
471
472The ideal (but a bit ugly) way to never have to think
473about that is to use C<BEGIN> blocks. So the first part
474of 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
488The C<BEGIN> will assure that the loading of F<Exporter.pm>
489and the assignments to C<@ISA> and C<@EXPORT_OK> happen
490immediately, leaving no room for something to get awry
491or just plain wrong.
492
493With respect to loading C<Exporter> and inheriting, there
494are 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
500Any of these statements are nice replacements for
501C<BEGIN { require Exporter; @ISA = qw(Exporter); }>
502with the same compile-time effect. The basic difference
503is that C<base> code interacts with declared C<fields>
504while C<parent> is a streamlined version of the older
505C<base> code to just establish the IS-A relationship.
506
507For more details, see the documentation and code of
508L<base> and L<parent>.
509
af30f7a9
AF
510Another thorough remedy to that runtime vs.
511compile-time trap is to use L<Exporter::Easy>,
512which is a wrapper of Exporter that allows all
513boilerplate code at a single gulp in the
514use 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
47f97feb
AF
522=head2 What not to Export
523
af30f7a9 524You have been warned already in L</Selecting What To Export>
47f97feb
AF
525to not export:
526
527=over 4
528
529=item *
530
44ddc072 531method names (because you don't need to
47f97feb
AF
532and that's likely to not do what you want),
533
534=item *
535
536anything by default (because you don't want to surprise your users...
537badly)
538
539=item *
540
541anything you don't need to (because less is more)
542
543=back
544
545There's one more item to add to this list. Do B<not>
546export variable names. Just because C<Exporter> lets you
547do that, it does not mean you should.
548
549 @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
550
551Exporting variables is not a good idea. They can
552change under the hood, provoking horrible
553effects at-a-distance, that are too hard to track
554and to fix. Trust me: they are not worth it.
555
556To provide the capability to set/get class-wide
557settings, it is best instead to provide accessors
558as subroutines or class methods instead.
559
560=head1 SEE ALSO
561
562C<Exporter> is definitely not the only module with
563symbol exporter capabilities. At CPAN, you may find
564a bunch of them. Some are lighter. Some
565provide improved APIs and features. Peek the one
566that fits your needs. The following is
567a 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
578This library is free software. You can redistribute it
579and/or modify it under the same terms as Perl itself.
580
2b5b2650 581=cut
3e927c50
AF
582
583
584