This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [perl #24245] File::Copy::copy damages hard linked files
[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;
a6faae8d
HS
12our $VERSION = '5.567';
13our (%Cache);
bb2cbcd1 14$Carp::Internal{Exporter} = 1;
2b5b2650 15
0e57b4e8 16sub as_heavy {
4af1b167 17 require Exporter::Heavy;
0e57b4e8
IZ
18 # Unfortunately, this does not work if the caller is aliased as *name = \&foo
19 # Thus the need to create a lot of identical subroutines
20 my $c = (caller(1))[3];
21 $c =~ s/.*:://;
22 \&{"Exporter::Heavy::heavy_$c"};
84902520
TB
23}
24
4af1b167 25sub export {
0e57b4e8 26 goto &{as_heavy()};
a0d0e21e
LW
27}
28
4af1b167
IZ
29sub import {
30 my $pkg = shift;
31 my $callpkg = caller($ExportLevel);
b75c8c73 32
4af1b167 33 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
a6faae8d 34 my($exports, $fail) = (\@{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
4af1b167 35 return export $pkg, $callpkg, @_
b75c8c73 36 if $Verbose or $Debug or @$fail > 1;
a6faae8d 37 my $export_cache = ($Cache{$pkg} ||= {});
b75c8c73 38 my $args = @_ or @_ = @$exports;
732bb7c2
NC
39
40 local $_;
b75c8c73 41 if ($args and not %$export_cache) {
732bb7c2
NC
42 s/^&//, $export_cache->{$_} = 1
43 foreach (@$exports, @{"$pkg\::EXPORT_OK"});
4af1b167 44 }
fa1bb02f
NC
45 my $heavy;
46 # Try very hard not to use {} and hence have to enter scope on the foreach
47 # We bomb out of the loop with last as soon as heavy is set.
48 if ($args or $fail) {
732bb7c2 49 ($heavy = (/\W/ or $args and not exists $export_cache->{$_}
fa1bb02f
NC
50 or @$fail and $_ eq $fail->[0])) and last
51 foreach (@_);
52 } else {
53 ($heavy = /\W/) and last
732bb7c2 54 foreach (@_);
4af1b167 55 }
732bb7c2 56 return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy;
4af1b167 57 local $SIG{__WARN__} =
bb2cbcd1 58 sub {require Carp; &Carp::carp};
732bb7c2
NC
59 # shortcut for the common case of no type character
60 *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_;
e50aee73
AD
61}
62
b75c8c73
MS
63# Default methods
64
2b5b2650 65sub export_fail {
b75c8c73
MS
66 my $self = shift;
67 @_;
2b5b2650
PP
68}
69
0e57b4e8
IZ
70# Unfortunately, caller(1)[3] "does not work" if the caller is aliased as
71# *name = \&foo. Thus the need to create a lot of identical subroutines
72# Otherwise we could have aliased them to export().
b75c8c73 73
0e57b4e8
IZ
74sub export_to_level {
75 goto &{as_heavy()};
76}
77
78sub export_tags {
79 goto &{as_heavy()};
b75c8c73
MS
80}
81
0e57b4e8
IZ
82sub export_ok_tags {
83 goto &{as_heavy()};
84}
85
86sub require_version {
87 goto &{as_heavy()};
88}
b75c8c73 89
2b5b2650 901;
732bb7c2 91__END__
b75c8c73 92
2b5b2650
PP
93=head1 NAME
94
95Exporter - Implements default import method for modules
96
97=head1 SYNOPSIS
98
65503211 99In module YourModule.pm:
2b5b2650 100
65503211 101 package YourModule;
2b5b2650
PP
102 require Exporter;
103 @ISA = qw(Exporter);
65503211 104 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
2b5b2650 105
65503211 106In other files which wish to use YourModule:
2b5b2650 107
65503211
NC
108 use ModuleName qw(frobnicate); # import listed symbols
109 frobnicate ($left, $right) # calls YourModule::frobnicate
2b5b2650
PP
110
111=head1 DESCRIPTION
112
65503211
NC
113The Exporter module implements an C<import> method which allows a module
114to export functions and variables to its users' namespaces. Many modules
115use Exporter rather than implementing their own C<import> method because
116Exporter provides a highly flexible interface, with an implementation optimised
117for the common case.
2b5b2650
PP
118
119Perl automatically calls the C<import> method when processing a
120C<use> statement for a module. Modules and C<use> are documented
121in L<perlfunc> and L<perlmod>. Understanding the concept of
122modules and how the C<use> statement operates is important to
123understanding the Exporter.
124
4fddf32b
GS
125=head2 How to Export
126
127The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
128symbols that are going to be exported into the users name space by
129default, or which they can request to be exported, respectively. The
130symbols can represent functions, scalars, arrays, hashes, or typeglobs.
131The symbols must be given by full name with the exception that the
132ampersand in front of a function is optional, e.g.
133
134 @EXPORT = qw(afunc $scalar @array); # afunc is a function
135 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
136
65503211
NC
137If you are only exporting function names it is recommended to omit the
138ampersand, as the implementation is faster this way.
139
2b5b2650
PP
140=head2 Selecting What To Export
141
142Do B<not> export method names!
143
144Do B<not> export anything else by default without a good reason!
145
146Exports pollute the namespace of the module user. If you must export
147try to use @EXPORT_OK in preference to @EXPORT and avoid short or
148common symbol names to reduce the risk of name clashes.
149
150Generally anything not exported is still accessible from outside the
1fef88e7 151module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
2b5b2650
PP
152syntax. By convention you can use a leading underscore on names to
153informally indicate that they are 'internal' and not for public use.
154
155(It is actually possible to get private functions by saying:
156
157 my $subref = sub { ... };
e60ce172
BT
158 $subref->(@args); # Call it as a function
159 $obj->$subref(@args); # Use it as a method
2b5b2650 160
e60ce172
BT
161However if you use them for methods it is up to you to figure out
162how to make inheritance work.)
2b5b2650
PP
163
164As a general rule, if the module is trying to be object oriented
165then export nothing. If it's just a collection of functions then
65503211
NC
166@EXPORT_OK anything but use @EXPORT with caution. For function and
167method names use barewords in preference to names prefixed with
168ampersands for the export lists.
2b5b2650
PP
169
170Other module design guidelines can be found in L<perlmod>.
171
65503211
NC
172=head2 How to Import
173
174In other files which wish to use your module there are three basic ways for
175them to load your module and import its symbols:
176
177=over 4
178
179=item C<use ModuleName;>
180
181This imports all the symbols from ModuleName's @EXPORT into the namespace
182of the C<use> statement.
183
184=item C<use ModuleName ();>
185
186This causes perl to load your module but does not import any symbols.
187
188=item C<use ModuleName qw(...);>
189
190This imports only the symbols listed by the caller into their namespace.
191All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error
192occurs. The advanced export features of Exporter are accessed like this,
193but with list entries that are syntactically distinct from symbol names.
194
195=back
196
197Unless you want to use its advanced features, this is probably all you
198need to know to use Exporter.
199
200=head1 Advanced features
201
2b5b2650
PP
202=head2 Specialised Import Lists
203
204If the first entry in an import list begins with !, : or / then the
205list is treated as a series of specifications which either add to or
206delete from the list of names to import. They are processed left to
207right. Specifications are in the form:
208
209 [!]name This name only
210 [!]:DEFAULT All names in @EXPORT
211 [!]:tag All names in $EXPORT_TAGS{tag} anonymous list
212 [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match
213
214A leading ! indicates that matching names should be deleted from the
215list of names to import. If the first specification is a deletion it
216is treated as though preceded by :DEFAULT. If you just want to import
217extra names in addition to the default set you will still need to
218include :DEFAULT explicitly.
219
220e.g., Module.pm defines:
221
222 @EXPORT = qw(A1 A2 A3 A4 A5);
223 @EXPORT_OK = qw(B1 B2 B3 B4 B5);
224 %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
225
226 Note that you cannot use tags in @EXPORT or @EXPORT_OK.
227 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
228
229An application using Module can say something like:
230
231 use Module qw(:DEFAULT :T2 !B3 A3);
232
233Other examples include:
234
235 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
236 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
237
238Remember that most patterns (using //) will need to be anchored
239with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
240
241You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
242specifications are being processed and what is actually being imported
243into modules.
244
65503211 245=head2 Exporting without using Exporter's import method
84902520
TB
246
247Exporter has a special method, 'export_to_level' which is used in situations
65503211 248where you can't directly call Exporter's import method. The export_to_level
84902520
TB
249method looks like:
250
cec46e5a 251 MyPackage->export_to_level($where_to_export, $package, @what_to_export);
84902520
TB
252
253where $where_to_export is an integer telling how far up the calling stack
254to export your symbols, and @what_to_export is an array telling what
ba5725f8
GS
255symbols *to* export (usually this is @_). The $package argument is
256currently unused.
84902520
TB
257
258For example, suppose that you have a module, A, which already has an
259import function:
260
cec46e5a 261 package A;
84902520 262
cec46e5a
RGS
263 @ISA = qw(Exporter);
264 @EXPORT_OK = qw ($b);
84902520 265
cec46e5a
RGS
266 sub import
267 {
268 $A::b = 1; # not a very useful import method
269 }
84902520
TB
270
271and you want to Export symbol $A::b back to the module that called
272package A. Since Exporter relies on the import method to work, via
273inheritance, as it stands Exporter::import() will never get called.
274Instead, say the following:
275
cec46e5a
RGS
276 package A;
277 @ISA = qw(Exporter);
278 @EXPORT_OK = qw ($b);
84902520 279
cec46e5a
RGS
280 sub import
281 {
282 $A::b = 1;
283 A->export_to_level(1, @_);
284 }
84902520
TB
285
286This will export the symbols one level 'above' the current package - ie: to
287the program or module that used package A.
288
289Note: Be careful not to modify '@_' at all before you call export_to_level
290- or people using your package will get very unexplained results!
291
292
2b5b2650
PP
293=head2 Module Version Checking
294
295The Exporter module will convert an attempt to import a number from a
1fef88e7 296module into a call to $module_name-E<gt>require_version($value). This can
2b5b2650
PP
297be used to validate that the version of the module being used is
298greater than or equal to the required version.
299
300The Exporter module supplies a default require_version method which
301checks the value of $VERSION in the exporting module.
302
303Since the default require_version method treats the $VERSION number as
d5e40bcc
PP
304a simple numeric value it will regard version 1.10 as lower than
3051.9. For this reason it is strongly recommended that you use numbers
306with at least two decimal places, e.g., 1.09.
2b5b2650
PP
307
308=head2 Managing Unknown Symbols
309
310In some situations you may want to prevent certain symbols from being
311exported. Typically this applies to extensions which have functions
312or constants that may not exist on some systems.
313
314The names of any symbols that cannot be exported should be listed
315in the C<@EXPORT_FAIL> array.
316
7a2e2cd6 317If a module attempts to import any of these symbols the Exporter
2b5b2650
PP
318will give the module an opportunity to handle the situation before
319generating an error. The Exporter will call an export_fail method
320with a list of the failed symbols:
321
322 @failed_symbols = $module_name->export_fail(@failed_symbols);
323
324If the export_fail method returns an empty list then no error is
325recorded and all the requested symbols are exported. If the returned
326list is not empty then an error is generated for each symbol and the
327export fails. The Exporter provides a default export_fail method which
328simply returns the list unchanged.
329
330Uses for the export_fail method include giving better error messages
331for some symbols and performing lazy architectural checks (put more
332symbols into @EXPORT_FAIL by default and then take them out if someone
333actually tries to use them and an expensive check shows that they are
334usable on that platform).
335
336=head2 Tag Handling Utility Functions
337
338Since the symbols listed within %EXPORT_TAGS must also appear in either
339@EXPORT or @EXPORT_OK, two utility functions are provided which allow
340you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
341
342 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
343
344 Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
345 Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
346
347Any names which are not tags are added to @EXPORT or @EXPORT_OK
d5e40bcc 348unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
2b5b2650
PP
349names being silently added to @EXPORT or @EXPORT_OK. Future versions
350may make this a fatal error.
351
d584343b
GME
352=head2 Generating combined tags
353
354If several symbol categories exist in %EXPORT_TAGS, it's usually
355useful to create the utility ":all" to simplify "use" statements.
356
357The simplest way to do this is:
358
359 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
360
361 # add all the other ":class" tags to the ":all" class,
362 # deleting duplicates
363 {
364 my %seen;
365
366 push @{$EXPORT_TAGS{all}},
367 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
368 }
369
370CGI.pm creates an ":all" tag which contains some (but not really
371all) of its categories. That could be done with one small
372change:
373
374 # add some of the other ":class" tags to the ":all" class,
375 # deleting duplicates
376 {
377 my %seen;
378
379 push @{$EXPORT_TAGS{all}},
380 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
381 foreach qw/html2 html3 netscape form cgi internal/;
382 }
383
384Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
385
5fea0f12
BS
386=head2 C<AUTOLOAD>ed Constants
387
8b4c0206
T
388Many modules make use of C<AUTOLOAD>ing for constant subroutines to
389avoid having to compile and waste memory on rarely used values (see
390L<perlsub> for details on constant subroutines). Calls to such
391constant subroutines are not optimized away at compile time because
392they can't be checked at compile time for constancy.
393
394Even if a prototype is available at compile time, the body of the
395subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
396examine both the C<()> prototype and the body of a subroutine at
397compile time to detect that it can safely replace calls to that
398subroutine with the constant value.
5fea0f12
BS
399
400A workaround for this is to call the constants once in a C<BEGIN> block:
401
402 package My ;
403
404 use Socket ;
405
406 foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
407 BEGIN { SO_LINGER }
408 foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
409
8b4c0206
T
410This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
411SO_LINGER is encountered later in C<My> package.
5fea0f12 412
8b4c0206
T
413If you are writing a package that C<AUTOLOAD>s, consider forcing
414an C<AUTOLOAD> for any constants explicitly imported by other packages
415or which are usually used when your package is C<use>d.
5fea0f12 416
2b5b2650 417=cut