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