This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Bump $VERSION of all PathTools modules to 3.2501
[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;
47f97feb 12our $VERSION = '5.61';
a6faae8d 13our (%Cache);
09e96b99
JC
14# Carp does this now for us, so we can finally live w/o Carp
15#$Carp::Internal{Exporter} = 1;
2b5b2650 16
0e57b4e8 17sub as_heavy {
4af1b167 18 require Exporter::Heavy;
0e57b4e8
IZ
19 # Unfortunately, this does not work if the caller is aliased as *name = \&foo
20 # Thus the need to create a lot of identical subroutines
21 my $c = (caller(1))[3];
22 $c =~ s/.*:://;
23 \&{"Exporter::Heavy::heavy_$c"};
84902520
TB
24}
25
4af1b167 26sub export {
0e57b4e8 27 goto &{as_heavy()};
a0d0e21e
LW
28}
29
4af1b167
IZ
30sub import {
31 my $pkg = shift;
32 my $callpkg = caller($ExportLevel);
b75c8c73 33
fe43f860
FD
34 if ($pkg eq "Exporter" and @_ and $_[0] eq "import") {
35 *{$callpkg."::import"} = \&import;
36 return;
37 }
38
4af1b167 39 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
a6faae8d 40 my($exports, $fail) = (\@{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
4af1b167 41 return export $pkg, $callpkg, @_
b75c8c73 42 if $Verbose or $Debug or @$fail > 1;
a6faae8d 43 my $export_cache = ($Cache{$pkg} ||= {});
b75c8c73 44 my $args = @_ or @_ = @$exports;
732bb7c2
NC
45
46 local $_;
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->{$_}
fa1bb02f
NC
56 or @$fail and $_ eq $fail->[0])) and last
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__} =
bb2cbcd1 64 sub {require Carp; &Carp::carp};
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
PP
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
PP
99=head1 NAME
100
101Exporter - Implements default import method for modules
102
103=head1 SYNOPSIS
104
65503211 105In module YourModule.pm:
2b5b2650 106
65503211 107 package YourModule;
2b5b2650
PP
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
65503211 118In other files which wish to use YourModule:
2b5b2650 119
65503211
NC
120 use ModuleName qw(frobnicate); # import listed symbols
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
PP
126=head1 DESCRIPTION
127
65503211
NC
128The Exporter module implements an C<import> method which allows a module
129to export functions and variables to its users' namespaces. Many modules
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
PP
133
134Perl automatically calls the C<import> method when processing a
135C<use> statement for a module. Modules and C<use> are documented
136in L<perlfunc> and L<perlmod>. Understanding the concept of
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
PP
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
162try to use @EXPORT_OK in preference to @EXPORT and avoid short or
163common symbol names to reduce the risk of name clashes.
164
165Generally anything not exported is still accessible from outside the
1fef88e7 166module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
2b5b2650
PP
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
PP
178
179As a general rule, if the module is trying to be object oriented
180then export nothing. If it's just a collection of functions then
65503211
NC
181@EXPORT_OK anything but use @EXPORT with caution. For function and
182method names use barewords in preference to names prefixed with
183ampersands for the export lists.
2b5b2650
PP
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
194=item C<use ModuleName;>
195
196This imports all the symbols from ModuleName's @EXPORT into the namespace
197of the C<use> statement.
198
199=item C<use ModuleName ();>
200
201This causes perl to load your module but does not import any symbols.
202
203=item C<use ModuleName qw(...);>
204
205This imports only the symbols listed by the caller into their namespace.
206All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error
207occurs. The advanced export features of Exporter are accessed like this,
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
PP
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
221or delete from the list of names to import. They are processed left to
2b5b2650
PP
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
231is treated as though preceded by :DEFAULT. If you just want to import
232extra names in addition to the default set you will still need to
233include :DEFAULT explicitly.
234
235e.g., 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
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
65503211 263where you can't directly call Exporter's import method. The export_to_level
84902520
TB
264method looks like:
265
cec46e5a 266 MyPackage->export_to_level($where_to_export, $package, @what_to_export);
84902520
TB
267
268where $where_to_export is an integer telling how far up the calling stack
269to export your symbols, and @what_to_export is an array telling what
ba5725f8
GS
270symbols *to* export (usually this is @_). The $package argument is
271currently unused.
84902520
TB
272
273For example, suppose that you have a module, A, which already has an
274import function:
275
cec46e5a 276 package A;
84902520 277
cec46e5a
RGS
278 @ISA = qw(Exporter);
279 @EXPORT_OK = qw ($b);
84902520 280
cec46e5a
RGS
281 sub import
282 {
283 $A::b = 1; # not a very useful import method
284 }
84902520
TB
285
286and you want to Export symbol $A::b back to the module that called
287package A. Since Exporter relies on the import method to work, via
288inheritance, as it stands Exporter::import() will never get called.
289Instead, say the following:
290
cec46e5a
RGS
291 package A;
292 @ISA = qw(Exporter);
293 @EXPORT_OK = qw ($b);
84902520 294
cec46e5a
RGS
295 sub import
296 {
297 $A::b = 1;
298 A->export_to_level(1, @_);
299 }
84902520
TB
300
301This will export the symbols one level 'above' the current package - ie: to
302the program or module that used package A.
303
fe43f860 304Note: Be careful not to modify C<@_> at all before you call export_to_level
84902520
TB
305- or people using your package will get very unexplained results!
306
fe43f860
FD
307=head2 Exporting without inheriting from Exporter
308
309By including Exporter in your @ISA you inherit an Exporter's import() method
310but you also inherit several other helper methods which you probably don't
311want. To avoid this you can do
312
313 package YourModule;
314 use Exporter qw( import );
315
316which will export Exporter's own import() method into YourModule.
317Everything will work as before but you won't need to include Exporter in
318@YourModule::ISA.
84902520 319
47f97feb
AF
320Note: This feature was introduced in version 5.57
321of Exporter, released with perl 5.8.3.
322
2b5b2650
PP
323=head2 Module Version Checking
324
325The Exporter module will convert an attempt to import a number from a
1fef88e7 326module into a call to $module_name-E<gt>require_version($value). This can
2b5b2650
PP
327be used to validate that the version of the module being used is
328greater than or equal to the required version.
329
330The Exporter module supplies a default require_version method which
331checks the value of $VERSION in the exporting module.
332
333Since the default require_version method treats the $VERSION number as
d5e40bcc
PP
334a simple numeric value it will regard version 1.10 as lower than
3351.9. For this reason it is strongly recommended that you use numbers
336with at least two decimal places, e.g., 1.09.
2b5b2650
PP
337
338=head2 Managing Unknown Symbols
339
340In some situations you may want to prevent certain symbols from being
341exported. Typically this applies to extensions which have functions
342or constants that may not exist on some systems.
343
344The names of any symbols that cannot be exported should be listed
345in the C<@EXPORT_FAIL> array.
346
7a2e2cd6 347If a module attempts to import any of these symbols the Exporter
2b5b2650
PP
348will give the module an opportunity to handle the situation before
349generating an error. The Exporter will call an export_fail method
350with a list of the failed symbols:
351
352 @failed_symbols = $module_name->export_fail(@failed_symbols);
353
354If the export_fail method returns an empty list then no error is
355recorded and all the requested symbols are exported. If the returned
356list is not empty then an error is generated for each symbol and the
357export fails. The Exporter provides a default export_fail method which
358simply returns the list unchanged.
359
360Uses for the export_fail method include giving better error messages
361for some symbols and performing lazy architectural checks (put more
362symbols into @EXPORT_FAIL by default and then take them out if someone
363actually tries to use them and an expensive check shows that they are
364usable on that platform).
365
366=head2 Tag Handling Utility Functions
367
368Since the symbols listed within %EXPORT_TAGS must also appear in either
369@EXPORT or @EXPORT_OK, two utility functions are provided which allow
370you to easily add tagged sets of symbols to @EXPORT or @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
377Any names which are not tags are added to @EXPORT or @EXPORT_OK
d5e40bcc 378unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
2b5b2650
PP
379names being silently added to @EXPORT or @EXPORT_OK. Future versions
380may make this a fatal error.
381
d584343b
GME
382=head2 Generating combined tags
383
384If several symbol categories exist in %EXPORT_TAGS, it's usually
385useful to create the utility ":all" to simplify "use" statements.
386
387The 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
400CGI.pm creates an ":all" tag which contains some (but not really
401all) of its categories. That could be done with one small
402change:
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
414Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
415
5fea0f12
BS
416=head2 C<AUTOLOAD>ed Constants
417
8b4c0206
T
418Many modules make use of C<AUTOLOAD>ing for constant subroutines to
419avoid having to compile and waste memory on rarely used values (see
420L<perlsub> for details on constant subroutines). Calls to such
421constant subroutines are not optimized away at compile time because
422they can't be checked at compile time for constancy.
423
424Even if a prototype is available at compile time, the body of the
425subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
426examine both the C<()> prototype and the body of a subroutine at
427compile time to detect that it can safely replace calls to that
428subroutine with the constant value.
5fea0f12
BS
429
430A 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
8b4c0206
T
440This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
441SO_LINGER is encountered later in C<My> package.
5fea0f12 442
8b4c0206
T
443If you are writing a package that C<AUTOLOAD>s, consider forcing
444an C<AUTOLOAD> for any constants explicitly imported by other packages
445or which are usually used when your package is C<use>d.
5fea0f12 446
47f97feb
AF
447=head1 Good Practices
448
449=head2 Declaring C<@EXPORT_OK> and Friends
450
451When using C<Exporter> with the standard C<strict> and C<warnings>
452pragmas, the C<our> keyword is needed to declare the package
453variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc.
454
455 our @ISA = qw(Exporter);
456 our @EXPORT_OK = qw(munge frobnicate);
457
458If backward compatibility for Perls under 5.6 is important,
459one 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
467There are some caveats with the use of runtime statements
468like C<require Exporter> and the assignment to package
469variables, which can very subtle for the unaware programmer.
470This may happen for instance with mutually recursive
471modules, which are affected by the time the relevant
472constructions are executed.
473
474The ideal (but a bit ugly) way to never have to think
475about that is to use C<BEGIN> blocks. So the first part
476of 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
490The C<BEGIN> will assure that the loading of F<Exporter.pm>
491and the assignments to C<@ISA> and C<@EXPORT_OK> happen
492immediately, leaving no room for something to get awry
493or just plain wrong.
494
495With respect to loading C<Exporter> and inheriting, there
496are 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
502Any of these statements are nice replacements for
503C<BEGIN { require Exporter; @ISA = qw(Exporter); }>
504with the same compile-time effect. The basic difference
505is that C<base> code interacts with declared C<fields>
506while C<parent> is a streamlined version of the older
507C<base> code to just establish the IS-A relationship.
508
509For more details, see the documentation and code of
510L<base> and L<parent>.
511
512=head2 What not to Export
513
514You have been warned already in L</Selecting What to Export>
515to not export:
516
517=over 4
518
519=item *
520
44ddc072 521method names (because you don't need to
47f97feb
AF
522and that's likely to not do what you want),
523
524=item *
525
526anything by default (because you don't want to surprise your users...
527badly)
528
529=item *
530
531anything you don't need to (because less is more)
532
533=back
534
535There's one more item to add to this list. Do B<not>
536export variable names. Just because C<Exporter> lets you
537do that, it does not mean you should.
538
539 @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
540
541Exporting variables is not a good idea. They can
542change under the hood, provoking horrible
543effects at-a-distance, that are too hard to track
544and to fix. Trust me: they are not worth it.
545
546To provide the capability to set/get class-wide
547settings, it is best instead to provide accessors
548as subroutines or class methods instead.
549
550=head1 SEE ALSO
551
552C<Exporter> is definitely not the only module with
553symbol exporter capabilities. At CPAN, you may find
554a bunch of them. Some are lighter. Some
555provide improved APIs and features. Peek the one
556that fits your needs. The following is
557a sample list of such modules.
558
559 Exporter::Easy
560 Exporter::Lite
561 Exporter::Renaming
562 Exporter::Tidy
563 Sub::Exporter / Sub::Installer
564 Perl6::Export / Perl6::Export::Attrs
565
566=head1 LICENSE
567
568This library is free software. You can redistribute it
569and/or modify it under the same terms as Perl itself.
570
2b5b2650 571=cut