12 our $VERSION = '5.566';
13 $Carp::Internal{Exporter} = 1;
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 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
33 my($exports, $export_cache, $fail)
34 = (\@{"$pkg\::EXPORT"}, \%{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"});
35 return export $pkg, $callpkg, @_
36 if $Verbose or $Debug or @$fail > 1;
37 my $args = @_ or @_ = @$exports;
40 if ($args and not %$export_cache) {
41 s/^&//, $export_cache->{$_} = 1
42 foreach (@$exports, @{"$pkg\::EXPORT_OK"});
45 # Try very hard not to use {} and hence have to enter scope on the foreach
46 # We bomb out of the loop with last as soon as heavy is set.
48 ($heavy = (/\W/ or $args and not exists $export_cache->{$_}
49 or @$fail and $_ eq $fail->[0])) and last
52 ($heavy = /\W/) and last
55 return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy;
56 local $SIG{__WARN__} =
57 sub {require Carp; &Carp::carp};
58 # shortcut for the common case of no type character
59 *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_;
69 # Unfortunately, caller(1)[3] "does not work" if the caller is aliased as
70 # *name = \&foo. Thus the need to create a lot of identical subroutines
71 # Otherwise we could have aliased them to export().
94 Exporter - Implements default import method for modules
98 In module YourModule.pm:
103 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
105 In other files which wish to use YourModule:
107 use ModuleName qw(frobnicate); # import listed symbols
108 frobnicate ($left, $right) # calls YourModule::frobnicate
112 The Exporter module implements an C<import> method which allows a module
113 to export functions and variables to its users' namespaces. Many modules
114 use Exporter rather than implementing their own C<import> method because
115 Exporter provides a highly flexible interface, with an implementation optimised
118 Perl automatically calls the C<import> method when processing a
119 C<use> statement for a module. Modules and C<use> are documented
120 in L<perlfunc> and L<perlmod>. Understanding the concept of
121 modules and how the C<use> statement operates is important to
122 understanding the Exporter.
126 The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
127 symbols that are going to be exported into the users name space by
128 default, or which they can request to be exported, respectively. The
129 symbols can represent functions, scalars, arrays, hashes, or typeglobs.
130 The symbols must be given by full name with the exception that the
131 ampersand in front of a function is optional, e.g.
133 @EXPORT = qw(afunc $scalar @array); # afunc is a function
134 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
136 If you are only exporting function names it is recommended to omit the
137 ampersand, as the implementation is faster this way.
139 =head2 Selecting What To Export
141 Do B<not> export method names!
143 Do B<not> export anything else by default without a good reason!
145 Exports pollute the namespace of the module user. If you must export
146 try to use @EXPORT_OK in preference to @EXPORT and avoid short or
147 common symbol names to reduce the risk of name clashes.
149 Generally anything not exported is still accessible from outside the
150 module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
151 syntax. By convention you can use a leading underscore on names to
152 informally indicate that they are 'internal' and not for public use.
154 (It is actually possible to get private functions by saying:
156 my $subref = sub { ... };
157 $subref->(@args); # Call it as a function
158 $obj->$subref(@args); # Use it as a method
160 However if you use them for methods it is up to you to figure out
161 how to make inheritance work.)
163 As a general rule, if the module is trying to be object oriented
164 then export nothing. If it's just a collection of functions then
165 @EXPORT_OK anything but use @EXPORT with caution. For function and
166 method names use barewords in preference to names prefixed with
167 ampersands for the export lists.
169 Other module design guidelines can be found in L<perlmod>.
173 In other files which wish to use your module there are three basic ways for
174 them to load your module and import its symbols:
178 =item C<use ModuleName;>
180 This imports all the symbols from ModuleName's @EXPORT into the namespace
181 of the C<use> statement.
183 =item C<use ModuleName ();>
185 This causes perl to load your module but does not import any symbols.
187 =item C<use ModuleName qw(...);>
189 This imports only the symbols listed by the caller into their namespace.
190 All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error
191 occurs. The advanced export features of Exporter are accessed like this,
192 but with list entries that are syntactically distinct from symbol names.
196 Unless you want to use its advanced features, this is probably all you
197 need to know to use Exporter.
199 =head1 Advanced features
201 =head2 Specialised Import Lists
203 If the first entry in an import list begins with !, : or / then the
204 list is treated as a series of specifications which either add to or
205 delete from the list of names to import. They are processed left to
206 right. Specifications are in the form:
208 [!]name This name only
209 [!]:DEFAULT All names in @EXPORT
210 [!]:tag All names in $EXPORT_TAGS{tag} anonymous list
211 [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match
213 A leading ! indicates that matching names should be deleted from the
214 list of names to import. If the first specification is a deletion it
215 is treated as though preceded by :DEFAULT. If you just want to import
216 extra names in addition to the default set you will still need to
217 include :DEFAULT explicitly.
219 e.g., Module.pm defines:
221 @EXPORT = qw(A1 A2 A3 A4 A5);
222 @EXPORT_OK = qw(B1 B2 B3 B4 B5);
223 %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
225 Note that you cannot use tags in @EXPORT or @EXPORT_OK.
226 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
228 An application using Module can say something like:
230 use Module qw(:DEFAULT :T2 !B3 A3);
232 Other examples include:
234 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
235 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
237 Remember that most patterns (using //) will need to be anchored
238 with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
240 You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
241 specifications are being processed and what is actually being imported
244 =head2 Exporting without using Exporter's import method
246 Exporter has a special method, 'export_to_level' which is used in situations
247 where you can't directly call Exporter's import method. The export_to_level
250 MyPackage->export_to_level($where_to_export, $package, @what_to_export);
252 where $where_to_export is an integer telling how far up the calling stack
253 to export your symbols, and @what_to_export is an array telling what
254 symbols *to* export (usually this is @_). The $package argument is
257 For example, suppose that you have a module, A, which already has an
263 @EXPORT_OK = qw ($b);
267 $A::b = 1; # not a very useful import method
270 and you want to Export symbol $A::b back to the module that called
271 package A. Since Exporter relies on the import method to work, via
272 inheritance, as it stands Exporter::import() will never get called.
273 Instead, say the following:
277 @EXPORT_OK = qw ($b);
282 A->export_to_level(1, @_);
285 This will export the symbols one level 'above' the current package - ie: to
286 the program or module that used package A.
288 Note: Be careful not to modify '@_' at all before you call export_to_level
289 - or people using your package will get very unexplained results!
292 =head2 Module Version Checking
294 The Exporter module will convert an attempt to import a number from a
295 module into a call to $module_name-E<gt>require_version($value). This can
296 be used to validate that the version of the module being used is
297 greater than or equal to the required version.
299 The Exporter module supplies a default require_version method which
300 checks the value of $VERSION in the exporting module.
302 Since the default require_version method treats the $VERSION number as
303 a simple numeric value it will regard version 1.10 as lower than
304 1.9. For this reason it is strongly recommended that you use numbers
305 with at least two decimal places, e.g., 1.09.
307 =head2 Managing Unknown Symbols
309 In some situations you may want to prevent certain symbols from being
310 exported. Typically this applies to extensions which have functions
311 or constants that may not exist on some systems.
313 The names of any symbols that cannot be exported should be listed
314 in the C<@EXPORT_FAIL> array.
316 If a module attempts to import any of these symbols the Exporter
317 will give the module an opportunity to handle the situation before
318 generating an error. The Exporter will call an export_fail method
319 with a list of the failed symbols:
321 @failed_symbols = $module_name->export_fail(@failed_symbols);
323 If the export_fail method returns an empty list then no error is
324 recorded and all the requested symbols are exported. If the returned
325 list is not empty then an error is generated for each symbol and the
326 export fails. The Exporter provides a default export_fail method which
327 simply returns the list unchanged.
329 Uses for the export_fail method include giving better error messages
330 for some symbols and performing lazy architectural checks (put more
331 symbols into @EXPORT_FAIL by default and then take them out if someone
332 actually tries to use them and an expensive check shows that they are
333 usable on that platform).
335 =head2 Tag Handling Utility Functions
337 Since the symbols listed within %EXPORT_TAGS must also appear in either
338 @EXPORT or @EXPORT_OK, two utility functions are provided which allow
339 you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
341 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
343 Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
344 Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
346 Any names which are not tags are added to @EXPORT or @EXPORT_OK
347 unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
348 names being silently added to @EXPORT or @EXPORT_OK. Future versions
349 may make this a fatal error.
351 =head2 Generating combined tags
353 If several symbol categories exist in %EXPORT_TAGS, it's usually
354 useful to create the utility ":all" to simplify "use" statements.
356 The simplest way to do this is:
358 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
360 # add all the other ":class" tags to the ":all" class,
361 # deleting duplicates
365 push @{$EXPORT_TAGS{all}},
366 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
369 CGI.pm creates an ":all" tag which contains some (but not really
370 all) of its categories. That could be done with one small
373 # add some of the other ":class" tags to the ":all" class,
374 # deleting duplicates
378 push @{$EXPORT_TAGS{all}},
379 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
380 foreach qw/html2 html3 netscape form cgi internal/;
383 Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
385 =head2 C<AUTOLOAD>ed Constants
387 Many modules make use of C<AUTOLOAD>ing for constant subroutines to
388 avoid having to compile and waste memory on rarely used values (see
389 L<perlsub> for details on constant subroutines). Calls to such
390 constant subroutines are not optimized away at compile time because
391 they can't be checked at compile time for constancy.
393 Even if a prototype is available at compile time, the body of the
394 subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
395 examine both the C<()> prototype and the body of a subroutine at
396 compile time to detect that it can safely replace calls to that
397 subroutine with the constant value.
399 A workaround for this is to call the constants once in a C<BEGIN> block:
405 foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
407 foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
409 This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
410 SO_LINGER is encountered later in C<My> package.
412 If you are writing a package that C<AUTOLOAD>s, consider forcing
413 an C<AUTOLOAD> for any constants explicitly imported by other packages
414 or which are usually used when your package is C<use>d.