12 our $VERSION = '5.67';
16 require Exporter::Heavy;
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];
21 \&{"Exporter::Heavy::heavy_$c"};
30 my $callpkg = caller($ExportLevel);
32 if ($pkg eq "Exporter" and @_ and $_[0] eq "import") {
33 *{$callpkg."::import"} = \&import;
37 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
38 my $exports = \@{"$pkg\::EXPORT"};
39 # But, avoid creating things if they don't exist, which saves a couple of
40 # hundred bytes per package processed.
41 my $fail = ${$pkg . '::'}{EXPORT_FAIL} && \@{"$pkg\::EXPORT_FAIL"};
42 return export $pkg, $callpkg, @_
43 if $Verbose or $Debug or $fail && @$fail > 1;
44 my $export_cache = ($Cache{$pkg} ||= {});
45 my $args = @_ or @_ = @$exports;
47 if ($args and not %$export_cache) {
48 s/^&//, $export_cache->{$_} = 1
49 foreach (@$exports, @{"$pkg\::EXPORT_OK"});
52 # Try very hard not to use {} and hence have to enter scope on the foreach
53 # We bomb out of the loop with last as soon as heavy is set.
55 ($heavy = (/\W/ or $args and not exists $export_cache->{$_}
56 or $fail and @$fail and $_ eq $fail->[0])) and last
59 ($heavy = /\W/) and last
62 return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy;
63 local $SIG{__WARN__} =
64 sub {require Carp; &Carp::carp} if not $SIG{__WARN__};
65 # shortcut for the common case of no type character
66 *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_;
76 # Unfortunately, caller(1)[3] "does not work" if the caller is aliased as
77 # *name = \&foo. Thus the need to create a lot of identical subroutines
78 # Otherwise we could have aliased them to export().
101 Exporter - Implements default import method for modules
105 In module F<YourModule.pm>:
110 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
115 use Exporter 'import'; # gives you Exporter's import() method directly
116 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
118 In other files which wish to use C<YourModule>:
120 use YourModule qw(frobnicate); # import listed symbols
121 frobnicate ($left, $right) # calls YourModule::frobnicate
123 Take a look at L</Good Practices> for some variants
124 you will like to use in modern Perl code.
128 The Exporter module implements an C<import> method which allows a module
129 to export functions and variables to its users' namespaces. Many modules
130 use Exporter rather than implementing their own C<import> method because
131 Exporter provides a highly flexible interface, with an implementation optimised
134 Perl automatically calls the C<import> method when processing a
135 C<use> statement for a module. Modules and C<use> are documented
136 in L<perlfunc> and L<perlmod>. Understanding the concept of
137 modules and how the C<use> statement operates is important to
138 understanding the Exporter.
142 The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
143 symbols that are going to be exported into the users name space by
144 default, or which they can request to be exported, respectively. The
145 symbols can represent functions, scalars, arrays, hashes, or typeglobs.
146 The symbols must be given by full name with the exception that the
147 ampersand in front of a function is optional, e.g.
149 @EXPORT = qw(afunc $scalar @array); # afunc is a function
150 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
152 If you are only exporting function names it is recommended to omit the
153 ampersand, as the implementation is faster this way.
155 =head2 Selecting What to Export
157 Do B<not> export method names!
159 Do B<not> export anything else by default without a good reason!
161 Exports pollute the namespace of the module user. If you must export
162 try to use C<@EXPORT_OK> in preference to C<@EXPORT> and avoid short or
163 common symbol names to reduce the risk of name clashes.
165 Generally anything not exported is still accessible from outside the
166 module using the C<YourModule::item_name> (or C<< $blessed_ref->method >>)
167 syntax. By convention you can use a leading underscore on names to
168 informally indicate that they are 'internal' and not for public use.
170 (It is actually possible to get private functions by saying:
172 my $subref = sub { ... };
173 $subref->(@args); # Call it as a function
174 $obj->$subref(@args); # Use it as a method
176 However if you use them for methods it is up to you to figure out
177 how to make inheritance work.)
179 As a general rule, if the module is trying to be object oriented
180 then export nothing. If it's just a collection of functions then
181 C<@EXPORT_OK> anything but use C<@EXPORT> with caution. For function and
182 method names use barewords in preference to names prefixed with
183 ampersands for the export lists.
185 Other module design guidelines can be found in L<perlmod>.
189 In other files which wish to use your module there are three basic ways for
190 them to load your module and import its symbols:
194 =item C<use YourModule;>
196 This imports all the symbols from YourModule's C<@EXPORT> into the namespace
197 of the C<use> statement.
199 =item C<use YourModule ();>
201 This causes perl to load your module but does not import any symbols.
203 =item C<use YourModule qw(...);>
205 This imports only the symbols listed by the caller into their namespace.
206 All listed symbols must be in your C<@EXPORT> or C<@EXPORT_OK>, else an error
207 occurs. The advanced export features of Exporter are accessed like this,
208 but with list entries that are syntactically distinct from symbol names.
212 Unless you want to use its advanced features, this is probably all you
213 need to know to use Exporter.
215 =head1 Advanced Features
217 =head2 Specialised Import Lists
219 If any of the entries in an import list begins with !, : or / then
220 the list is treated as a series of specifications which either add to
221 or delete from the list of names to import. They are processed left to
222 right. Specifications are in the form:
224 [!]name This name only
225 [!]:DEFAULT All names in @EXPORT
226 [!]:tag All names in $EXPORT_TAGS{tag} anonymous list
227 [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match
229 A leading ! indicates that matching names should be deleted from the
230 list of names to import. If the first specification is a deletion it
231 is treated as though preceded by :DEFAULT. If you just want to import
232 extra names in addition to the default set you will still need to
233 include :DEFAULT explicitly.
235 e.g., F<Module.pm> defines:
237 @EXPORT = qw(A1 A2 A3 A4 A5);
238 @EXPORT_OK = qw(B1 B2 B3 B4 B5);
239 %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
241 Note that you cannot use tags in @EXPORT or @EXPORT_OK.
243 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
245 An application using Module can say something like:
247 use Module qw(:DEFAULT :T2 !B3 A3);
249 Other examples include:
251 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
252 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
254 Remember that most patterns (using //) will need to be anchored
255 with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
257 You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
258 specifications are being processed and what is actually being imported
261 =head2 Exporting Without Using Exporter's import Method
263 Exporter has a special method, 'export_to_level' which is used in situations
264 where you can't directly call Exporter's
265 import method. The export_to_level
268 MyPackage->export_to_level(
269 $where_to_export, $package, @what_to_export
272 where C<$where_to_export> is an integer telling how far up the calling stack
273 to export your symbols, and C<@what_to_export> is an array telling what
274 symbols *to* export (usually this is C<@_>). The C<$package> argument is
277 For example, suppose that you have a module, A, which already has an
283 @EXPORT_OK = qw ($b);
287 $A::b = 1; # not a very useful import method
290 and you want to Export symbol C<$A::b> back to the module that called
291 package A. Since Exporter relies on the import method to work, via
292 inheritance, as it stands Exporter::import() will never get called.
293 Instead, say the following:
297 @EXPORT_OK = qw ($b);
302 A->export_to_level(1, @_);
305 This will export the symbols one level 'above' the current package - ie: to
306 the program or module that used package A.
308 Note: Be careful not to modify C<@_> at all before you call export_to_level
309 - or people using your package will get very unexplained results!
311 =head2 Exporting Without Inheriting from Exporter
313 By including Exporter in your C<@ISA> you inherit an Exporter's import() method
314 but you also inherit several other helper methods which you probably don't
315 want. To avoid this you can do
318 use Exporter qw( import );
320 which will export Exporter's own import() method into YourModule.
321 Everything will work as before but you won't need to include Exporter in
324 Note: This feature was introduced in version 5.57
325 of Exporter, released with perl 5.8.3.
327 =head2 Module Version Checking
329 The Exporter module will convert an attempt to import a number from a
330 module into a call to C<< $module_name->VERSION($value) >>. This can
331 be used to validate that the version of the module being used is
332 greater than or equal to the required version.
334 For historical reasons, Exporter supplies a C<require_version> method that
335 simply delegates to C<VERSION>. Originally, before C<UNIVERSAL::VERSION>
336 existed, Exporter would call C<require_version>.
338 Since the C<UNIVERSAL::VERSION> method treats the C<$VERSION> number as
339 a simple numeric value it will regard version 1.10 as lower than
340 1.9. For this reason it is strongly recommended that you use numbers
341 with at least two decimal places, e.g., 1.09.
343 =head2 Managing Unknown Symbols
345 In some situations you may want to prevent certain symbols from being
346 exported. Typically this applies to extensions which have functions
347 or constants that may not exist on some systems.
349 The names of any symbols that cannot be exported should be listed
350 in the C<@EXPORT_FAIL> array.
352 If a module attempts to import any of these symbols the Exporter
353 will give the module an opportunity to handle the situation before
354 generating an error. The Exporter will call an export_fail method
355 with a list of the failed symbols:
357 @failed_symbols = $module_name->export_fail(@failed_symbols);
359 If the C<export_fail> method returns an empty list then no error is
360 recorded and all the requested symbols are exported. If the returned
361 list is not empty then an error is generated for each symbol and the
362 export fails. The Exporter provides a default C<export_fail> method which
363 simply returns the list unchanged.
365 Uses for the C<export_fail> method include giving better error messages
366 for some symbols and performing lazy architectural checks (put more
367 symbols into C<@EXPORT_FAIL> by default and then take them out if someone
368 actually tries to use them and an expensive check shows that they are
369 usable on that platform).
371 =head2 Tag Handling Utility Functions
373 Since the symbols listed within C<%EXPORT_TAGS> must also appear in either
374 C<@EXPORT> or C<@EXPORT_OK>, two utility functions are provided which allow
375 you to easily add tagged sets of symbols to C<@EXPORT> or C<@EXPORT_OK>:
377 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
379 Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
380 Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
382 Any names which are not tags are added to C<@EXPORT> or C<@EXPORT_OK>
383 unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
384 names being silently added to C<@EXPORT> or C<@EXPORT_OK>. Future versions
385 may make this a fatal error.
387 =head2 Generating Combined Tags
389 If several symbol categories exist in C<%EXPORT_TAGS>, it's usually
390 useful to create the utility ":all" to simplify "use" statements.
392 The simplest way to do this is:
394 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
396 # add all the other ":class" tags to the ":all" class,
397 # deleting duplicates
401 push @{$EXPORT_TAGS{all}},
402 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
405 F<CGI.pm> creates an ":all" tag which contains some (but not really
406 all) of its categories. That could be done with one small
409 # add some of the other ":class" tags to the ":all" class,
410 # deleting duplicates
414 push @{$EXPORT_TAGS{all}},
415 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
416 foreach qw/html2 html3 netscape form cgi internal/;
419 Note that the tag names in C<%EXPORT_TAGS> don't have the leading ':'.
421 =head2 C<AUTOLOAD>ed Constants
423 Many modules make use of C<AUTOLOAD>ing for constant subroutines to
424 avoid having to compile and waste memory on rarely used values (see
425 L<perlsub> for details on constant subroutines). Calls to such
426 constant subroutines are not optimized away at compile time because
427 they can't be checked at compile time for constancy.
429 Even if a prototype is available at compile time, the body of the
430 subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
431 examine both the C<()> prototype and the body of a subroutine at
432 compile time to detect that it can safely replace calls to that
433 subroutine with the constant value.
435 A workaround for this is to call the constants once in a C<BEGIN> block:
441 foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
443 foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
445 This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
446 SO_LINGER is encountered later in C<My> package.
448 If you are writing a package that C<AUTOLOAD>s, consider forcing
449 an C<AUTOLOAD> for any constants explicitly imported by other packages
450 or which are usually used when your package is C<use>d.
452 =head1 Good Practices
454 =head2 Declaring C<@EXPORT_OK> and Friends
456 When using C<Exporter> with the standard C<strict> and C<warnings>
457 pragmas, the C<our> keyword is needed to declare the package
458 variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc.
460 our @ISA = qw(Exporter);
461 our @EXPORT_OK = qw(munge frobnicate);
463 If backward compatibility for Perls under 5.6 is important,
464 one must write instead a C<use vars> statement.
466 use vars qw(@ISA @EXPORT_OK);
468 @EXPORT_OK = qw(munge frobnicate);
472 There are some caveats with the use of runtime statements
473 like C<require Exporter> and the assignment to package
474 variables, which can very subtle for the unaware programmer.
475 This may happen for instance with mutually recursive
476 modules, which are affected by the time the relevant
477 constructions are executed.
479 The ideal (but a bit ugly) way to never have to think
480 about that is to use C<BEGIN> blocks. So the first part
481 of the L</SYNOPSIS> code could be rewritten as:
488 our (@ISA, @EXPORT_OK);
492 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
495 The C<BEGIN> will assure that the loading of F<Exporter.pm>
496 and the assignments to C<@ISA> and C<@EXPORT_OK> happen
497 immediately, leaving no room for something to get awry
500 With respect to loading C<Exporter> and inheriting, there
501 are alternatives with the use of modules like C<base> and C<parent>.
503 use base qw( Exporter );
505 use parent qw( Exporter );
507 Any of these statements are nice replacements for
508 C<BEGIN { require Exporter; @ISA = qw(Exporter); }>
509 with the same compile-time effect. The basic difference
510 is that C<base> code interacts with declared C<fields>
511 while C<parent> is a streamlined version of the older
512 C<base> code to just establish the IS-A relationship.
514 For more details, see the documentation and code of
515 L<base> and L<parent>.
517 Another thorough remedy to that runtime
518 vs. compile-time trap is to use L<Exporter::Easy>,
519 which is a wrapper of Exporter that allows all
520 boilerplate code at a single gulp in the
524 OK => [ qw(munge frobnicate) ],
526 # @ISA setup is automatic
527 # all assignments happen at compile time
529 =head2 What Not to Export
531 You have been warned already in L</Selecting What to Export>
538 method names (because you don't need to
539 and that's likely to not do what you want),
543 anything by default (because you don't want to surprise your users...
548 anything you don't need to (because less is more)
552 There's one more item to add to this list. Do B<not>
553 export variable names. Just because C<Exporter> lets you
554 do that, it does not mean you should.
556 @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
558 Exporting variables is not a good idea. They can
559 change under the hood, provoking horrible
560 effects at-a-distance, that are too hard to track
561 and to fix. Trust me: they are not worth it.
563 To provide the capability to set/get class-wide
564 settings, it is best instead to provide accessors
565 as subroutines or class methods instead.
569 C<Exporter> is definitely not the only module with
570 symbol exporter capabilities. At CPAN, you may find
571 a bunch of them. Some are lighter. Some
572 provide improved APIs and features. Peek the one
573 that fits your needs. The following is
574 a sample list of such modules.
580 Sub::Exporter / Sub::Installer
581 Perl6::Export / Perl6::Export::Attrs
585 This library is free software. You can redistribute it
586 and/or modify it under the same terms as Perl itself.