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