This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Last patch needed to get Perl5.7 to build natively on VOS
[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
98In module ModuleName.pm:
99
100 package ModuleName;
101 require Exporter;
102 @ISA = qw(Exporter);
103
104 @EXPORT = qw(...); # symbols to export by default
105 @EXPORT_OK = qw(...); # symbols to export on request
106 %EXPORT_TAGS = tag => [...]; # define names for sets of symbols
107
108In other files which wish to use ModuleName:
109
110 use ModuleName; # import default symbols into my package
111
112 use ModuleName qw(...); # import listed symbols into my package
113
114 use ModuleName (); # do not import any symbols
115
116=head1 DESCRIPTION
117
118The Exporter module implements a default C<import> method which
68dc0745 119many modules choose to inherit rather than implement their own.
2b5b2650
PP
120
121Perl automatically calls the C<import> method when processing a
122C<use> statement for a module. Modules and C<use> are documented
123in L<perlfunc> and L<perlmod>. Understanding the concept of
124modules and how the C<use> statement operates is important to
125understanding the Exporter.
126
4fddf32b
GS
127=head2 How to Export
128
129The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
130symbols that are going to be exported into the users name space by
131default, or which they can request to be exported, respectively. The
132symbols can represent functions, scalars, arrays, hashes, or typeglobs.
133The symbols must be given by full name with the exception that the
134ampersand in front of a function is optional, e.g.
135
136 @EXPORT = qw(afunc $scalar @array); # afunc is a function
137 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
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
165@EXPORT_OK anything but use @EXPORT with caution.
166
167Other module design guidelines can be found in L<perlmod>.
168
169=head2 Specialised Import Lists
170
171If the first entry in an import list begins with !, : or / then the
172list is treated as a series of specifications which either add to or
173delete from the list of names to import. They are processed left to
174right. Specifications are in the form:
175
176 [!]name This name only
177 [!]:DEFAULT All names in @EXPORT
178 [!]:tag All names in $EXPORT_TAGS{tag} anonymous list
179 [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match
180
181A leading ! indicates that matching names should be deleted from the
182list of names to import. If the first specification is a deletion it
183is treated as though preceded by :DEFAULT. If you just want to import
184extra names in addition to the default set you will still need to
185include :DEFAULT explicitly.
186
187e.g., Module.pm defines:
188
189 @EXPORT = qw(A1 A2 A3 A4 A5);
190 @EXPORT_OK = qw(B1 B2 B3 B4 B5);
191 %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
192
193 Note that you cannot use tags in @EXPORT or @EXPORT_OK.
194 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
195
196An application using Module can say something like:
197
198 use Module qw(:DEFAULT :T2 !B3 A3);
199
200Other examples include:
201
202 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
203 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
204
205Remember that most patterns (using //) will need to be anchored
206with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
207
208You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
209specifications are being processed and what is actually being imported
210into modules.
211
84902520
TB
212=head2 Exporting without using Export's import method
213
214Exporter has a special method, 'export_to_level' which is used in situations
215where you can't directly call Export's import method. The export_to_level
216method looks like:
217
ba5725f8 218MyPackage->export_to_level($where_to_export, $package, @what_to_export);
84902520
TB
219
220where $where_to_export is an integer telling how far up the calling stack
221to export your symbols, and @what_to_export is an array telling what
ba5725f8
GS
222symbols *to* export (usually this is @_). The $package argument is
223currently unused.
84902520
TB
224
225For example, suppose that you have a module, A, which already has an
226import function:
227
228package A;
229
230@ISA = qw(Exporter);
231@EXPORT_OK = qw ($b);
232
233sub import
234{
235 $A::b = 1; # not a very useful import method
236}
237
238and you want to Export symbol $A::b back to the module that called
239package A. Since Exporter relies on the import method to work, via
240inheritance, as it stands Exporter::import() will never get called.
241Instead, say the following:
242
243package A;
244@ISA = qw(Exporter);
245@EXPORT_OK = qw ($b);
246
247sub import
248{
249 $A::b = 1;
250 A->export_to_level(1, @_);
251}
252
253This will export the symbols one level 'above' the current package - ie: to
254the program or module that used package A.
255
256Note: Be careful not to modify '@_' at all before you call export_to_level
257- or people using your package will get very unexplained results!
258
259
2b5b2650
PP
260=head2 Module Version Checking
261
262The Exporter module will convert an attempt to import a number from a
1fef88e7 263module into a call to $module_name-E<gt>require_version($value). This can
2b5b2650
PP
264be used to validate that the version of the module being used is
265greater than or equal to the required version.
266
267The Exporter module supplies a default require_version method which
268checks the value of $VERSION in the exporting module.
269
270Since the default require_version method treats the $VERSION number as
d5e40bcc
PP
271a simple numeric value it will regard version 1.10 as lower than
2721.9. For this reason it is strongly recommended that you use numbers
273with at least two decimal places, e.g., 1.09.
2b5b2650
PP
274
275=head2 Managing Unknown Symbols
276
277In some situations you may want to prevent certain symbols from being
278exported. Typically this applies to extensions which have functions
279or constants that may not exist on some systems.
280
281The names of any symbols that cannot be exported should be listed
282in the C<@EXPORT_FAIL> array.
283
7a2e2cd6 284If a module attempts to import any of these symbols the Exporter
2b5b2650
PP
285will give the module an opportunity to handle the situation before
286generating an error. The Exporter will call an export_fail method
287with a list of the failed symbols:
288
289 @failed_symbols = $module_name->export_fail(@failed_symbols);
290
291If the export_fail method returns an empty list then no error is
292recorded and all the requested symbols are exported. If the returned
293list is not empty then an error is generated for each symbol and the
294export fails. The Exporter provides a default export_fail method which
295simply returns the list unchanged.
296
297Uses for the export_fail method include giving better error messages
298for some symbols and performing lazy architectural checks (put more
299symbols into @EXPORT_FAIL by default and then take them out if someone
300actually tries to use them and an expensive check shows that they are
301usable on that platform).
302
303=head2 Tag Handling Utility Functions
304
305Since the symbols listed within %EXPORT_TAGS must also appear in either
306@EXPORT or @EXPORT_OK, two utility functions are provided which allow
307you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
308
309 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
310
311 Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
312 Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
313
314Any names which are not tags are added to @EXPORT or @EXPORT_OK
d5e40bcc 315unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
2b5b2650
PP
316names being silently added to @EXPORT or @EXPORT_OK. Future versions
317may make this a fatal error.
318
d584343b
GME
319=head2 Generating combined tags
320
321If several symbol categories exist in %EXPORT_TAGS, it's usually
322useful to create the utility ":all" to simplify "use" statements.
323
324The simplest way to do this is:
325
326 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
327
328 # add all the other ":class" tags to the ":all" class,
329 # deleting duplicates
330 {
331 my %seen;
332
333 push @{$EXPORT_TAGS{all}},
334 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
335 }
336
337CGI.pm creates an ":all" tag which contains some (but not really
338all) of its categories. That could be done with one small
339change:
340
341 # add some of the other ":class" tags to the ":all" class,
342 # deleting duplicates
343 {
344 my %seen;
345
346 push @{$EXPORT_TAGS{all}},
347 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
348 foreach qw/html2 html3 netscape form cgi internal/;
349 }
350
351Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
352
5fea0f12
BS
353=head2 C<AUTOLOAD>ed Constants
354
8b4c0206
T
355Many modules make use of C<AUTOLOAD>ing for constant subroutines to
356avoid having to compile and waste memory on rarely used values (see
357L<perlsub> for details on constant subroutines). Calls to such
358constant subroutines are not optimized away at compile time because
359they can't be checked at compile time for constancy.
360
361Even if a prototype is available at compile time, the body of the
362subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
363examine both the C<()> prototype and the body of a subroutine at
364compile time to detect that it can safely replace calls to that
365subroutine with the constant value.
5fea0f12
BS
366
367A workaround for this is to call the constants once in a C<BEGIN> block:
368
369 package My ;
370
371 use Socket ;
372
373 foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
374 BEGIN { SO_LINGER }
375 foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
376
8b4c0206
T
377This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
378SO_LINGER is encountered later in C<My> package.
5fea0f12 379
8b4c0206
T
380If you are writing a package that C<AUTOLOAD>s, consider forcing
381an C<AUTOLOAD> for any constants explicitly imported by other packages
382or which are usually used when your package is C<use>d.
5fea0f12 383
2b5b2650 384=cut