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