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