12 our $VERSION = '5.62';
14 # Carp does this now for us, so we can finally live w/o Carp
15 #$Carp::Internal{Exporter} = 1;
18 require Exporter::Heavy;
19 # Unfortunately, this does not work if the caller is aliased as *name = \&foo
20 # Thus the need to create a lot of identical subroutines
21 my $c = (caller(1))[3];
23 \&{"Exporter::Heavy::heavy_$c"};
32 my $callpkg = caller($ExportLevel);
34 if ($pkg eq "Exporter" and @_ and $_[0] eq "import") {
35 *{$callpkg."::import"} = \&import;
39 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
40 my($exports, $fail) = (\@{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
41 return export $pkg, $callpkg, @_
42 if $Verbose or $Debug or @$fail > 1;
43 my $export_cache = ($Cache{$pkg} ||= {});
44 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 $_ 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};
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 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 YourModule:
120 use ModuleName 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 @EXPORT_OK in preference to @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 ModuleName::item_name (or $blessed_ref-E<gt>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 @EXPORT_OK anything but use @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 ModuleName;>
196 This imports all the symbols from ModuleName's @EXPORT into the namespace
197 of the C<use> statement.
199 =item C<use ModuleName ();>
201 This causes perl to load your module but does not import any symbols.
203 =item C<use ModuleName qw(...);>
205 This imports only the symbols listed by the caller into their namespace.
206 All listed symbols must be in your @EXPORT or @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., 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.
242 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
244 An application using Module can say something like:
246 use Module qw(:DEFAULT :T2 !B3 A3);
248 Other examples include:
250 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
251 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
253 Remember that most patterns (using //) will need to be anchored
254 with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
256 You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
257 specifications are being processed and what is actually being imported
260 =head2 Exporting without using Exporter's import method
262 Exporter has a special method, 'export_to_level' which is used in situations
263 where you can't directly call Exporter's import method. The export_to_level
266 MyPackage->export_to_level($where_to_export, $package, @what_to_export);
268 where $where_to_export is an integer telling how far up the calling stack
269 to export your symbols, and @what_to_export is an array telling what
270 symbols *to* export (usually this is @_). The $package argument is
273 For example, suppose that you have a module, A, which already has an
279 @EXPORT_OK = qw ($b);
283 $A::b = 1; # not a very useful import method
286 and you want to Export symbol $A::b back to the module that called
287 package A. Since Exporter relies on the import method to work, via
288 inheritance, as it stands Exporter::import() will never get called.
289 Instead, say the following:
293 @EXPORT_OK = qw ($b);
298 A->export_to_level(1, @_);
301 This will export the symbols one level 'above' the current package - ie: to
302 the program or module that used package A.
304 Note: Be careful not to modify C<@_> at all before you call export_to_level
305 - or people using your package will get very unexplained results!
307 =head2 Exporting without inheriting from Exporter
309 By including Exporter in your @ISA you inherit an Exporter's import() method
310 but you also inherit several other helper methods which you probably don't
311 want. To avoid this you can do
314 use Exporter qw( import );
316 which will export Exporter's own import() method into YourModule.
317 Everything will work as before but you won't need to include Exporter in
320 Note: This feature was introduced in version 5.57
321 of Exporter, released with perl 5.8.3.
323 =head2 Module Version Checking
325 The Exporter module will convert an attempt to import a number from a
326 module into a call to $module_name-E<gt>require_version($value). This can
327 be used to validate that the version of the module being used is
328 greater than or equal to the required version.
330 The Exporter module supplies a default require_version method which
331 checks the value of $VERSION in the exporting module.
333 Since the default require_version method treats the $VERSION number as
334 a simple numeric value it will regard version 1.10 as lower than
335 1.9. For this reason it is strongly recommended that you use numbers
336 with at least two decimal places, e.g., 1.09.
338 =head2 Managing Unknown Symbols
340 In some situations you may want to prevent certain symbols from being
341 exported. Typically this applies to extensions which have functions
342 or constants that may not exist on some systems.
344 The names of any symbols that cannot be exported should be listed
345 in the C<@EXPORT_FAIL> array.
347 If a module attempts to import any of these symbols the Exporter
348 will give the module an opportunity to handle the situation before
349 generating an error. The Exporter will call an export_fail method
350 with a list of the failed symbols:
352 @failed_symbols = $module_name->export_fail(@failed_symbols);
354 If the export_fail method returns an empty list then no error is
355 recorded and all the requested symbols are exported. If the returned
356 list is not empty then an error is generated for each symbol and the
357 export fails. The Exporter provides a default export_fail method which
358 simply returns the list unchanged.
360 Uses for the export_fail method include giving better error messages
361 for some symbols and performing lazy architectural checks (put more
362 symbols into @EXPORT_FAIL by default and then take them out if someone
363 actually tries to use them and an expensive check shows that they are
364 usable on that platform).
366 =head2 Tag Handling Utility Functions
368 Since the symbols listed within %EXPORT_TAGS must also appear in either
369 @EXPORT or @EXPORT_OK, two utility functions are provided which allow
370 you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
372 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
374 Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
375 Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
377 Any names which are not tags are added to @EXPORT or @EXPORT_OK
378 unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
379 names being silently added to @EXPORT or @EXPORT_OK. Future versions
380 may make this a fatal error.
382 =head2 Generating combined tags
384 If several symbol categories exist in %EXPORT_TAGS, it's usually
385 useful to create the utility ":all" to simplify "use" statements.
387 The simplest way to do this is:
389 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
391 # add all the other ":class" tags to the ":all" class,
392 # deleting duplicates
396 push @{$EXPORT_TAGS{all}},
397 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
400 CGI.pm creates an ":all" tag which contains some (but not really
401 all) of its categories. That could be done with one small
404 # add some of the other ":class" tags to the ":all" class,
405 # deleting duplicates
409 push @{$EXPORT_TAGS{all}},
410 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
411 foreach qw/html2 html3 netscape form cgi internal/;
414 Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
416 =head2 C<AUTOLOAD>ed Constants
418 Many modules make use of C<AUTOLOAD>ing for constant subroutines to
419 avoid having to compile and waste memory on rarely used values (see
420 L<perlsub> for details on constant subroutines). Calls to such
421 constant subroutines are not optimized away at compile time because
422 they can't be checked at compile time for constancy.
424 Even if a prototype is available at compile time, the body of the
425 subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
426 examine both the C<()> prototype and the body of a subroutine at
427 compile time to detect that it can safely replace calls to that
428 subroutine with the constant value.
430 A workaround for this is to call the constants once in a C<BEGIN> block:
436 foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
438 foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
440 This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
441 SO_LINGER is encountered later in C<My> package.
443 If you are writing a package that C<AUTOLOAD>s, consider forcing
444 an C<AUTOLOAD> for any constants explicitly imported by other packages
445 or which are usually used when your package is C<use>d.
447 =head1 Good Practices
449 =head2 Declaring C<@EXPORT_OK> and Friends
451 When using C<Exporter> with the standard C<strict> and C<warnings>
452 pragmas, the C<our> keyword is needed to declare the package
453 variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc.
455 our @ISA = qw(Exporter);
456 our @EXPORT_OK = qw(munge frobnicate);
458 If backward compatibility for Perls under 5.6 is important,
459 one must write instead a C<use vars> statement.
461 use vars qw(@ISA @EXPORT_OK);
463 @EXPORT_OK = qw(munge frobnicate);
467 There are some caveats with the use of runtime statements
468 like C<require Exporter> and the assignment to package
469 variables, which can very subtle for the unaware programmer.
470 This may happen for instance with mutually recursive
471 modules, which are affected by the time the relevant
472 constructions are executed.
474 The ideal (but a bit ugly) way to never have to think
475 about that is to use C<BEGIN> blocks. So the first part
476 of the L</SYNOPSIS> code could be rewritten as:
483 our (@ISA, @EXPORT_OK);
487 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
490 The C<BEGIN> will assure that the loading of F<Exporter.pm>
491 and the assignments to C<@ISA> and C<@EXPORT_OK> happen
492 immediately, leaving no room for something to get awry
495 With respect to loading C<Exporter> and inheriting, there
496 are alternatives with the use of modules like C<base> and C<parent>.
498 use base qw( Exporter );
500 use parent qw( Exporter );
502 Any of these statements are nice replacements for
503 C<BEGIN { require Exporter; @ISA = qw(Exporter); }>
504 with the same compile-time effect. The basic difference
505 is that C<base> code interacts with declared C<fields>
506 while C<parent> is a streamlined version of the older
507 C<base> code to just establish the IS-A relationship.
509 For more details, see the documentation and code of
510 L<base> and L<parent>.
512 Another thorough remedy to that runtime vs.
513 compile-time trap is to use L<Exporter::Easy>,
514 which is a wrapper of Exporter that allows all
515 boilerplate code at a single gulp in the
519 OK => [ qw(munge frobnicate) ],
521 # @ISA setup is automatic
522 # all assignments happen at compile time
524 =head2 What not to Export
526 You have been warned already in L</Selecting What To Export>
533 method names (because you don't need to
534 and that's likely to not do what you want),
538 anything by default (because you don't want to surprise your users...
543 anything you don't need to (because less is more)
547 There's one more item to add to this list. Do B<not>
548 export variable names. Just because C<Exporter> lets you
549 do that, it does not mean you should.
551 @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
553 Exporting variables is not a good idea. They can
554 change under the hood, provoking horrible
555 effects at-a-distance, that are too hard to track
556 and to fix. Trust me: they are not worth it.
558 To provide the capability to set/get class-wide
559 settings, it is best instead to provide accessors
560 as subroutines or class methods instead.
564 C<Exporter> is definitely not the only module with
565 symbol exporter capabilities. At CPAN, you may find
566 a bunch of them. Some are lighter. Some
567 provide improved APIs and features. Peek the one
568 that fits your needs. The following is
569 a sample list of such modules.
575 Sub::Exporter / Sub::Installer
576 Perl6::Export / Perl6::Export::Attrs
580 This library is free software. You can redistribute it
581 and/or modify it under the same terms as Perl itself.