This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Exporter.pm: Consistent spaces after dots
[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;
23b51b60 12our $VERSION = '5.67';
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;
109 @ISA = qw(Exporter);
65503211 110 @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
116 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
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
149 @EXPORT = qw(afunc $scalar @array); # afunc is a function
150 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
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
2b5b2650 155=head2 Selecting What To Export
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
3e927c50 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
215=head1 Advanced features
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
226 [!]:tag All names in $EXPORT_TAGS{tag} anonymous list
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
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
244An application using Module can say something like:
245
246 use Module qw(:DEFAULT :T2 !B3 A3);
247
248Other examples include:
249
250 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
251 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
252
253Remember that most patterns (using //) will need to be anchored
254with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
255
256You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
257specifications are being processed and what is actually being imported
258into modules.
259
65503211 260=head2 Exporting without using Exporter's import method
84902520
TB
261
262Exporter has a special method, 'export_to_level' which is used in situations
5b2cfa76
FC
263where you can't directly call Exporter's
264import 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
5b2cfa76 288package A. Since Exporter relies on the import method to work, via
84902520
TB
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 311but you also inherit several other helper methods which you probably don't
5b2cfa76 312want. To avoid this you can do
fe43f860
FD
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 324=head2 Module Version Checking
325
326The Exporter module will convert an attempt to import a number from a
5b2cfa76 327module into a call to C<< $module_name->VERSION($value) >>. This can
2b5b2650 328be used to validate that the version of the module being used is
329greater than or equal to the required version.
330
1c0201fc 331Since the C<UNIVERSAL::VERSION> method treats the C<$VERSION> number as
d5e40bcc 332a simple numeric value it will regard version 1.10 as lower than
5b2cfa76 3331.9. For this reason it is strongly recommended that you use numbers
d5e40bcc 334with at least two decimal places, e.g., 1.09.
2b5b2650 335
336=head2 Managing Unknown Symbols
337
338In some situations you may want to prevent certain symbols from being
5b2cfa76 339exported. Typically this applies to extensions which have functions
2b5b2650 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 346will give the module an opportunity to handle the situation before
5b2cfa76 347generating an error. The Exporter will call an export_fail method
2b5b2650 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
5b2cfa76 353recorded and all the requested symbols are exported. If the returned
2b5b2650 354list is not empty then an error is generated for each symbol and the
5b2cfa76 355export fails. The Exporter provides a default C<export_fail> method which
2b5b2650 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 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 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
5b2cfa76 377names being silently added to C<@EXPORT> or C<@EXPORT_OK>. Future versions
2b5b2650 378may make this a fatal error.
379
d584343b
MG
380=head2 Generating combined tags
381
3e927c50 382If several symbol categories exist in C<%EXPORT_TAGS>, it's usually
d584343b
MG
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
MG
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
5b2cfa76 423subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
8b4c0206
T
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
5b2cfa76 473about that is to use C<BEGIN> blocks. So the first part
47f97feb
AF
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); }>
5b2cfa76 502with the same compile-time effect. The basic difference
47f97feb
AF
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
5b2cfa76
FC
510Another thorough remedy to that runtime
511vs. compile-time trap is to use L<Exporter::Easy>,
af30f7a9
AF
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
5b2cfa76
FC
545There's one more item to add to this list. Do B<not>
546export variable names. Just because C<Exporter> lets you
47f97feb
AF
547do that, it does not mean you should.
548
549 @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
550
5b2cfa76 551Exporting variables is not a good idea. They can
47f97feb
AF
552change under the hood, provoking horrible
553effects at-a-distance, that are too hard to track
5b2cfa76 554and to fix. Trust me: they are not worth it.
47f97feb
AF
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
5b2cfa76
FC
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
47f97feb
AF
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
5b2cfa76 578This library is free software. You can redistribute it
47f97feb
AF
579and/or modify it under the same terms as Perl itself.
580
2b5b2650 581=cut
3e927c50
AF
582
583
584