This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: New harness is failing things
[perl5.git] / lib / Exporter.pm
CommitLineData
8990e307
LW
1package Exporter;
2
748a9306 3require 5.001;
8990e307 4
a0d0e21e 5$ExportLevel = 0;
4af1b167 6$Verbose ||= 0;
90564d98 7$VERSION = '5.562';
2b5b2650 8
4af1b167
IZ
9sub export_to_level {
10 require Exporter::Heavy;
11 goto &heavy_export_to_level;
84902520
TB
12}
13
4af1b167
IZ
14sub export {
15 require Exporter::Heavy;
16 goto &heavy_export;
748a9306
LW
17}
18
4af1b167
IZ
19sub export_tags {
20 require Exporter::Heavy;
21 _push_tags((caller)[0], "EXPORT", \@_);
2b5b2650
PP
22}
23
4af1b167
IZ
24sub export_ok_tags {
25 require Exporter::Heavy;
26 _push_tags((caller)[0], "EXPORT_OK", \@_);
a0d0e21e
LW
27}
28
4af1b167
IZ
29sub import {
30 my $pkg = shift;
31 my $callpkg = caller($ExportLevel);
32 *exports = *{"$pkg\::EXPORT"};
33 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
34 *fail = *{"$pkg\::EXPORT_FAIL"};
35 return export $pkg, $callpkg, @_
36 if $Verbose or $Debug or @fail > 1;
37 my $args = @_ or @_ = @exports;
38
39 if ($args and not %exports) {
40 foreach my $sym (@exports, @{"$pkg\::EXPORT_OK"}) {
41 $sym =~ s/^&//;
42 $exports{$sym} = 1;
3221d3b0 43 }
4af1b167
IZ
44 }
45 if ($Verbose or $Debug
46 or grep {/\W/ or $args and not exists $exports{$_}
47 or @fail and $_ eq $fail[0]
48 or (@{"$pkg\::EXPORT_OK"}
49 and $_ eq ${"$pkg\::EXPORT_OK"}[0])} @_) {
50 return export $pkg, $callpkg, ($args ? @_ : ());
51 }
52 #local $SIG{__WARN__} = sub {require Carp; goto &Carp::carp};
53 local $SIG{__WARN__} =
54 sub {require Carp; local $Carp::CarpLevel = 1; &Carp::carp};
55 foreach $sym (@_) {
56 # shortcut for the common case of no type character
57 *{"$callpkg\::$sym"} = \&{"$pkg\::$sym"};
58 }
e50aee73
AD
59}
60
8990e307 611;
2b5b2650
PP
62
63# A simple self test harness. Change 'require Carp' to 'use Carp ()' for testing.
64# package main; eval(join('',<DATA>)) or die $@ unless caller;
65__END__
66package Test;
67$INC{'Exporter.pm'} = 1;
68@ISA = qw(Exporter);
69@EXPORT = qw(A1 A2 A3 A4 A5);
70@EXPORT_OK = qw(B1 B2 B3 B4 B5);
71%EXPORT_TAGS = (T1=>[qw(A1 A2 B1 B2)], T2=>[qw(A1 A2 B3 B4)], T3=>[qw(X3)]);
72@EXPORT_FAIL = qw(B4);
73Exporter::export_ok_tags('T3', 'unknown_tag');
74sub export_fail {
75 map { "Test::$_" } @_ # edit symbols just as an example
76}
77
78package main;
79$Exporter::Verbose = 1;
80#import Test;
81#import Test qw(X3); # export ok via export_ok_tags()
82#import Test qw(:T1 !A2 /5/ !/3/ B5);
83import Test qw(:T2 !B4);
84import Test qw(:T2); # should fail
851;
86
87=head1 NAME
88
89Exporter - Implements default import method for modules
90
91=head1 SYNOPSIS
92
93In module ModuleName.pm:
94
95 package ModuleName;
96 require Exporter;
97 @ISA = qw(Exporter);
98
99 @EXPORT = qw(...); # symbols to export by default
100 @EXPORT_OK = qw(...); # symbols to export on request
101 %EXPORT_TAGS = tag => [...]; # define names for sets of symbols
102
103In other files which wish to use ModuleName:
104
105 use ModuleName; # import default symbols into my package
106
107 use ModuleName qw(...); # import listed symbols into my package
108
109 use ModuleName (); # do not import any symbols
110
111=head1 DESCRIPTION
112
113The Exporter module implements a default C<import> method which
68dc0745 114many modules choose to inherit rather than implement their own.
2b5b2650
PP
115
116Perl automatically calls the C<import> method when processing a
117C<use> statement for a module. Modules and C<use> are documented
118in L<perlfunc> and L<perlmod>. Understanding the concept of
119modules and how the C<use> statement operates is important to
120understanding the Exporter.
121
4fddf32b
GS
122=head2 How to Export
123
124The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
125symbols that are going to be exported into the users name space by
126default, or which they can request to be exported, respectively. The
127symbols can represent functions, scalars, arrays, hashes, or typeglobs.
128The symbols must be given by full name with the exception that the
129ampersand in front of a function is optional, e.g.
130
131 @EXPORT = qw(afunc $scalar @array); # afunc is a function
132 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
133
2b5b2650
PP
134=head2 Selecting What To Export
135
136Do B<not> export method names!
137
138Do B<not> export anything else by default without a good reason!
139
140Exports pollute the namespace of the module user. If you must export
141try to use @EXPORT_OK in preference to @EXPORT and avoid short or
142common symbol names to reduce the risk of name clashes.
143
144Generally anything not exported is still accessible from outside the
1fef88e7 145module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
2b5b2650
PP
146syntax. By convention you can use a leading underscore on names to
147informally indicate that they are 'internal' and not for public use.
148
149(It is actually possible to get private functions by saying:
150
151 my $subref = sub { ... };
152 &$subref;
153
154But there's no way to call that directly as a method, since a method
155must have a name in the symbol table.)
156
157As a general rule, if the module is trying to be object oriented
158then export nothing. If it's just a collection of functions then
159@EXPORT_OK anything but use @EXPORT with caution.
160
161Other module design guidelines can be found in L<perlmod>.
162
163=head2 Specialised Import Lists
164
165If the first entry in an import list begins with !, : or / then the
166list is treated as a series of specifications which either add to or
167delete from the list of names to import. They are processed left to
168right. Specifications are in the form:
169
170 [!]name This name only
171 [!]:DEFAULT All names in @EXPORT
172 [!]:tag All names in $EXPORT_TAGS{tag} anonymous list
173 [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match
174
175A leading ! indicates that matching names should be deleted from the
176list of names to import. If the first specification is a deletion it
177is treated as though preceded by :DEFAULT. If you just want to import
178extra names in addition to the default set you will still need to
179include :DEFAULT explicitly.
180
181e.g., Module.pm defines:
182
183 @EXPORT = qw(A1 A2 A3 A4 A5);
184 @EXPORT_OK = qw(B1 B2 B3 B4 B5);
185 %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
186
187 Note that you cannot use tags in @EXPORT or @EXPORT_OK.
188 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
189
190An application using Module can say something like:
191
192 use Module qw(:DEFAULT :T2 !B3 A3);
193
194Other examples include:
195
196 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
197 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
198
199Remember that most patterns (using //) will need to be anchored
200with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
201
202You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
203specifications are being processed and what is actually being imported
204into modules.
205
84902520
TB
206=head2 Exporting without using Export's import method
207
208Exporter has a special method, 'export_to_level' which is used in situations
209where you can't directly call Export's import method. The export_to_level
210method looks like:
211
ba5725f8 212MyPackage->export_to_level($where_to_export, $package, @what_to_export);
84902520
TB
213
214where $where_to_export is an integer telling how far up the calling stack
215to export your symbols, and @what_to_export is an array telling what
ba5725f8
GS
216symbols *to* export (usually this is @_). The $package argument is
217currently unused.
84902520
TB
218
219For example, suppose that you have a module, A, which already has an
220import function:
221
222package A;
223
224@ISA = qw(Exporter);
225@EXPORT_OK = qw ($b);
226
227sub import
228{
229 $A::b = 1; # not a very useful import method
230}
231
232and you want to Export symbol $A::b back to the module that called
233package A. Since Exporter relies on the import method to work, via
234inheritance, as it stands Exporter::import() will never get called.
235Instead, say the following:
236
237package A;
238@ISA = qw(Exporter);
239@EXPORT_OK = qw ($b);
240
241sub import
242{
243 $A::b = 1;
244 A->export_to_level(1, @_);
245}
246
247This will export the symbols one level 'above' the current package - ie: to
248the program or module that used package A.
249
250Note: Be careful not to modify '@_' at all before you call export_to_level
251- or people using your package will get very unexplained results!
252
253
2b5b2650
PP
254=head2 Module Version Checking
255
256The Exporter module will convert an attempt to import a number from a
1fef88e7 257module into a call to $module_name-E<gt>require_version($value). This can
2b5b2650
PP
258be used to validate that the version of the module being used is
259greater than or equal to the required version.
260
261The Exporter module supplies a default require_version method which
262checks the value of $VERSION in the exporting module.
263
264Since the default require_version method treats the $VERSION number as
d5e40bcc
PP
265a simple numeric value it will regard version 1.10 as lower than
2661.9. For this reason it is strongly recommended that you use numbers
267with at least two decimal places, e.g., 1.09.
2b5b2650
PP
268
269=head2 Managing Unknown Symbols
270
271In some situations you may want to prevent certain symbols from being
272exported. Typically this applies to extensions which have functions
273or constants that may not exist on some systems.
274
275The names of any symbols that cannot be exported should be listed
276in the C<@EXPORT_FAIL> array.
277
7a2e2cd6 278If a module attempts to import any of these symbols the Exporter
2b5b2650
PP
279will give the module an opportunity to handle the situation before
280generating an error. The Exporter will call an export_fail method
281with a list of the failed symbols:
282
283 @failed_symbols = $module_name->export_fail(@failed_symbols);
284
285If the export_fail method returns an empty list then no error is
286recorded and all the requested symbols are exported. If the returned
287list is not empty then an error is generated for each symbol and the
288export fails. The Exporter provides a default export_fail method which
289simply returns the list unchanged.
290
291Uses for the export_fail method include giving better error messages
292for some symbols and performing lazy architectural checks (put more
293symbols into @EXPORT_FAIL by default and then take them out if someone
294actually tries to use them and an expensive check shows that they are
295usable on that platform).
296
297=head2 Tag Handling Utility Functions
298
299Since the symbols listed within %EXPORT_TAGS must also appear in either
300@EXPORT or @EXPORT_OK, two utility functions are provided which allow
301you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
302
303 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
304
305 Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
306 Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
307
308Any names which are not tags are added to @EXPORT or @EXPORT_OK
d5e40bcc 309unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
2b5b2650
PP
310names being silently added to @EXPORT or @EXPORT_OK. Future versions
311may make this a fatal error.
312
313=cut