This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
h2xs broken
[perl5.git] / lib / Exporter.pm
CommitLineData
8990e307
LW
1package Exporter;
2
732bb7c2 3require 5.006;
8990e307 4
b75c8c73
MS
5use strict;
6no strict 'refs';
7
8our $Debug = 0;
9our $ExportLevel = 0;
10our $Verbose ||= 0;
732bb7c2 11our $VERSION = '5.565';
bb2cbcd1 12$Carp::Internal{Exporter} = 1;
2b5b2650 13
4af1b167
IZ
14sub export_to_level {
15 require Exporter::Heavy;
b75c8c73 16 goto &Exporter::Heavy::heavy_export_to_level;
84902520
TB
17}
18
4af1b167
IZ
19sub export {
20 require Exporter::Heavy;
b75c8c73 21 goto &Exporter::Heavy::heavy_export;
748a9306
LW
22}
23
4af1b167
IZ
24sub export_tags {
25 require Exporter::Heavy;
b75c8c73 26 Exporter::Heavy::_push_tags((caller)[0], "EXPORT", \@_);
2b5b2650
PP
27}
28
4af1b167
IZ
29sub export_ok_tags {
30 require Exporter::Heavy;
b75c8c73 31 Exporter::Heavy::_push_tags((caller)[0], "EXPORT_OK", \@_);
a0d0e21e
LW
32}
33
4af1b167
IZ
34sub import {
35 my $pkg = shift;
36 my $callpkg = caller($ExportLevel);
b75c8c73 37
4af1b167 38 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
732bb7c2
NC
39 my($exports, $export_cache, $fail)
40 = (\@{"$pkg\::EXPORT"}, \%{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
4af1b167 41 return export $pkg, $callpkg, @_
b75c8c73
MS
42 if $Verbose or $Debug or @$fail > 1;
43 my $args = @_ or @_ = @$exports;
732bb7c2
NC
44
45 local $_;
b75c8c73 46 if ($args and not %$export_cache) {
732bb7c2
NC
47 s/^&//, $export_cache->{$_} = 1
48 foreach (@$exports, @{"$pkg\::EXPORT_OK"});
4af1b167 49 }
fa1bb02f
NC
50 my $heavy;
51 # Try very hard not to use {} and hence have to enter scope on the foreach
52 # We bomb out of the loop with last as soon as heavy is set.
53 if ($args or $fail) {
732bb7c2 54 ($heavy = (/\W/ or $args and not exists $export_cache->{$_}
fa1bb02f
NC
55 or @$fail and $_ eq $fail->[0])) and last
56 foreach (@_);
57 } else {
58 ($heavy = /\W/) and last
732bb7c2 59 foreach (@_);
4af1b167 60 }
732bb7c2 61 return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy;
4af1b167 62 local $SIG{__WARN__} =
bb2cbcd1 63 sub {require Carp; &Carp::carp};
732bb7c2
NC
64 # shortcut for the common case of no type character
65 *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_;
e50aee73
AD
66}
67
2b5b2650 68
b75c8c73
MS
69# Default methods
70
2b5b2650 71sub export_fail {
b75c8c73
MS
72 my $self = shift;
73 @_;
2b5b2650
PP
74}
75
b75c8c73
MS
76
77sub require_version {
78 require Exporter::Heavy;
79 goto &Exporter::Heavy::require_version;
80}
81
82
2b5b2650 831;
732bb7c2 84__END__
b75c8c73 85
2b5b2650
PP
86=head1 NAME
87
88Exporter - Implements default import method for modules
89
90=head1 SYNOPSIS
91
92In module ModuleName.pm:
93
94 package ModuleName;
95 require Exporter;
96 @ISA = qw(Exporter);
97
98 @EXPORT = qw(...); # symbols to export by default
99 @EXPORT_OK = qw(...); # symbols to export on request
100 %EXPORT_TAGS = tag => [...]; # define names for sets of symbols
101
102In other files which wish to use ModuleName:
103
104 use ModuleName; # import default symbols into my package
105
106 use ModuleName qw(...); # import listed symbols into my package
107
108 use ModuleName (); # do not import any symbols
109
110=head1 DESCRIPTION
111
112The Exporter module implements a default C<import> method which
68dc0745 113many modules choose to inherit rather than implement their own.
2b5b2650
PP
114
115Perl automatically calls the C<import> method when processing a
116C<use> statement for a module. Modules and C<use> are documented
117in L<perlfunc> and L<perlmod>. Understanding the concept of
118modules and how the C<use> statement operates is important to
119understanding the Exporter.
120
4fddf32b
GS
121=head2 How to Export
122
123The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
124symbols that are going to be exported into the users name space by
125default, or which they can request to be exported, respectively. The
126symbols can represent functions, scalars, arrays, hashes, or typeglobs.
127The symbols must be given by full name with the exception that the
128ampersand in front of a function is optional, e.g.
129
130 @EXPORT = qw(afunc $scalar @array); # afunc is a function
131 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
132
2b5b2650
PP
133=head2 Selecting What To Export
134
135Do B<not> export method names!
136
137Do B<not> export anything else by default without a good reason!
138
139Exports pollute the namespace of the module user. If you must export
140try to use @EXPORT_OK in preference to @EXPORT and avoid short or
141common symbol names to reduce the risk of name clashes.
142
143Generally anything not exported is still accessible from outside the
1fef88e7 144module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
2b5b2650
PP
145syntax. By convention you can use a leading underscore on names to
146informally indicate that they are 'internal' and not for public use.
147
148(It is actually possible to get private functions by saying:
149
150 my $subref = sub { ... };
e60ce172
BT
151 $subref->(@args); # Call it as a function
152 $obj->$subref(@args); # Use it as a method
2b5b2650 153
e60ce172
BT
154However if you use them for methods it is up to you to figure out
155how to make inheritance work.)
2b5b2650
PP
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
d584343b
GME
313=head2 Generating combined tags
314
315If several symbol categories exist in %EXPORT_TAGS, it's usually
316useful to create the utility ":all" to simplify "use" statements.
317
318The simplest way to do this is:
319
320 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
321
322 # add all the other ":class" tags to the ":all" class,
323 # deleting duplicates
324 {
325 my %seen;
326
327 push @{$EXPORT_TAGS{all}},
328 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
329 }
330
331CGI.pm creates an ":all" tag which contains some (but not really
332all) of its categories. That could be done with one small
333change:
334
335 # add some of the other ":class" tags to the ":all" class,
336 # deleting duplicates
337 {
338 my %seen;
339
340 push @{$EXPORT_TAGS{all}},
341 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
342 foreach qw/html2 html3 netscape form cgi internal/;
343 }
344
345Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
346
5fea0f12
BS
347=head2 C<AUTOLOAD>ed Constants
348
8b4c0206
T
349Many modules make use of C<AUTOLOAD>ing for constant subroutines to
350avoid having to compile and waste memory on rarely used values (see
351L<perlsub> for details on constant subroutines). Calls to such
352constant subroutines are not optimized away at compile time because
353they can't be checked at compile time for constancy.
354
355Even if a prototype is available at compile time, the body of the
356subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
357examine both the C<()> prototype and the body of a subroutine at
358compile time to detect that it can safely replace calls to that
359subroutine with the constant value.
5fea0f12
BS
360
361A workaround for this is to call the constants once in a C<BEGIN> block:
362
363 package My ;
364
365 use Socket ;
366
367 foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
368 BEGIN { SO_LINGER }
369 foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
370
8b4c0206
T
371This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
372SO_LINGER is encountered later in C<My> package.
5fea0f12 373
8b4c0206
T
374If you are writing a package that C<AUTOLOAD>s, consider forcing
375an C<AUTOLOAD> for any constants explicitly imported by other packages
376or which are usually used when your package is C<use>d.
5fea0f12 377
2b5b2650 378=cut