1package Exporter; 2 3require 5.006; 4 5# Be lean. 6#use strict; 7#no strict 'refs'; 8 9our $Debug = 0; 10our $ExportLevel = 0; 11our $Verbose ||= 0; 12our $VERSION = '5.58'; 13our (%Cache); 14$Carp::Internal{Exporter} = 1; 15 16sub as_heavy { 17 require Exporter::Heavy; 18 # Unfortunately, this does not work if the caller is aliased as *name = \&foo 19 # Thus the need to create a lot of identical subroutines 20 my $c = (caller(1))[3]; 21 $c =~ s/.*:://; 22 \&{"Exporter::Heavy::heavy_$c"}; 23} 24 25sub export { 26 goto &{as_heavy()}; 27} 28 29sub import { 30 my $pkg = shift; 31 my $callpkg = caller($ExportLevel); 32 33 if ($pkg eq "Exporter" and @_ and $_[0] eq "import") { 34 *{$callpkg."::import"} = \&import; 35 return; 36 } 37 38 # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-( 39 my($exports, $fail) = (\@{"$pkg\::EXPORT"}, \@{"$pkg\::EXPORT_FAIL"}); 40 return export $pkg, $callpkg, @_ 41 if $Verbose or $Debug or @$fail > 1; 42 my $export_cache = ($Cache{$pkg} ||= {}); 43 my $args = @_ or @_ = @$exports; 44 45 local $_; 46 if ($args and not %$export_cache) { 47 s/^&//, $export_cache->{$_} = 1 48 foreach (@$exports, @{"$pkg\::EXPORT_OK"}); 49 } 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) { 54 ($heavy = (/\W/ or $args and not exists $export_cache->{$_} 55 or @$fail and $_ eq $fail->[0])) and last 56 foreach (@_); 57 } else { 58 ($heavy = /\W/) and last 59 foreach (@_); 60 } 61 return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy; 62 local $SIG{__WARN__} = 63 sub {require Carp; &Carp::carp}; 64 # shortcut for the common case of no type character 65 *{"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_; 66} 67 68# Default methods 69 70sub export_fail { 71 my $self = shift; 72 @_; 73} 74 75# Unfortunately, caller(1)[3] "does not work" if the caller is aliased as 76# *name = \&foo. Thus the need to create a lot of identical subroutines 77# Otherwise we could have aliased them to export(). 78 79sub export_to_level { 80 goto &{as_heavy()}; 81} 82 83sub export_tags { 84 goto &{as_heavy()}; 85} 86 87sub export_ok_tags { 88 goto &{as_heavy()}; 89} 90 91sub require_version { 92 goto &{as_heavy()}; 93} 94 951; 96__END__ 97 98=head1 NAME 99 100Exporter - Implements default import method for modules 101 102=head1 SYNOPSIS 103 104In module YourModule.pm: 105 106 package YourModule; 107 require Exporter; 108 @ISA = qw(Exporter); 109 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request 110 111or 112 113 package YourModule; 114 use Exporter 'import'; # gives you Exporter's import() method directly 115 @EXPORT_OK = qw(munge frobnicate); # symbols to export on request 116 117In other files which wish to use YourModule: 118 119 use ModuleName qw(frobnicate); # import listed symbols 120 frobnicate ($left, $right) # calls YourModule::frobnicate 121 122=head1 DESCRIPTION 123 124The Exporter module implements an C<import> method which allows a module 125to export functions and variables to its users' namespaces. Many modules 126use Exporter rather than implementing their own C<import> method because 127Exporter provides a highly flexible interface, with an implementation optimised 128for the common case. 129 130Perl automatically calls the C<import> method when processing a 131C<use> statement for a module. Modules and C<use> are documented 132in L<perlfunc> and L<perlmod>. Understanding the concept of 133modules and how the C<use> statement operates is important to 134understanding the Exporter. 135 136=head2 How to Export 137 138The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of 139symbols that are going to be exported into the users name space by 140default, or which they can request to be exported, respectively. The 141symbols can represent functions, scalars, arrays, hashes, or typeglobs. 142The symbols must be given by full name with the exception that the 143ampersand in front of a function is optional, e.g. 144 145 @EXPORT = qw(afunc $scalar @array); # afunc is a function 146 @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc 147 148If you are only exporting function names it is recommended to omit the 149ampersand, as the implementation is faster this way. 150 151=head2 Selecting What To Export 152 153Do B<not> export method names! 154 155Do B<not> export anything else by default without a good reason! 156 157Exports pollute the namespace of the module user. If you must export 158try to use @EXPORT_OK in preference to @EXPORT and avoid short or 159common symbol names to reduce the risk of name clashes. 160 161Generally anything not exported is still accessible from outside the 162module using the ModuleName::item_name (or $blessed_ref-E<gt>method) 163syntax. By convention you can use a leading underscore on names to 164informally indicate that they are 'internal' and not for public use. 165 166(It is actually possible to get private functions by saying: 167 168 my $subref = sub { ... }; 169 $subref->(@args); # Call it as a function 170 $obj->$subref(@args); # Use it as a method 171 172However if you use them for methods it is up to you to figure out 173how to make inheritance work.) 174 175As a general rule, if the module is trying to be object oriented 176then export nothing. If it's just a collection of functions then 177@EXPORT_OK anything but use @EXPORT with caution. For function and 178method names use barewords in preference to names prefixed with 179ampersands for the export lists. 180 181Other module design guidelines can be found in L<perlmod>. 182 183=head2 How to Import 184 185In other files which wish to use your module there are three basic ways for 186them to load your module and import its symbols: 187 188=over 4 189 190=item C<use ModuleName;> 191 192This imports all the symbols from ModuleName's @EXPORT into the namespace 193of the C<use> statement. 194 195=item C<use ModuleName ();> 196 197This causes perl to load your module but does not import any symbols. 198 199=item C<use ModuleName qw(...);> 200 201This imports only the symbols listed by the caller into their namespace. 202All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error 203occurs. The advanced export features of Exporter are accessed like this, 204but with list entries that are syntactically distinct from symbol names. 205 206=back 207 208Unless you want to use its advanced features, this is probably all you 209need to know to use Exporter. 210 211=head1 Advanced features 212 213=head2 Specialised Import Lists 214 215If any of the entries in an import list begins with !, : or / then 216the list is treated as a series of specifications which either add to 217or delete from the list of names to import. They are processed left to 218right. Specifications are in the form: 219 220 [!]name This name only 221 [!]:DEFAULT All names in @EXPORT 222 [!]:tag All names in $EXPORT_TAGS{tag} anonymous list 223 [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match 224 225A leading ! indicates that matching names should be deleted from the 226list of names to import. If the first specification is a deletion it 227is treated as though preceded by :DEFAULT. If you just want to import 228extra names in addition to the default set you will still need to 229include :DEFAULT explicitly. 230 231e.g., Module.pm defines: 232 233 @EXPORT = qw(A1 A2 A3 A4 A5); 234 @EXPORT_OK = qw(B1 B2 B3 B4 B5); 235 %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]); 236 237 Note that you cannot use tags in @EXPORT or @EXPORT_OK. 238 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK. 239 240An application using Module can say something like: 241 242 use Module qw(:DEFAULT :T2 !B3 A3); 243 244Other examples include: 245 246 use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); 247 use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/); 248 249Remember that most patterns (using //) will need to be anchored 250with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>. 251 252You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the 253specifications are being processed and what is actually being imported 254into modules. 255 256=head2 Exporting without using Exporter's import method 257 258Exporter has a special method, 'export_to_level' which is used in situations 259where you can't directly call Exporter's import method. The export_to_level 260method looks like: 261 262 MyPackage->export_to_level($where_to_export, $package, @what_to_export); 263 264where $where_to_export is an integer telling how far up the calling stack 265to export your symbols, and @what_to_export is an array telling what 266symbols *to* export (usually this is @_). The $package argument is 267currently unused. 268 269For example, suppose that you have a module, A, which already has an 270import function: 271 272 package A; 273 274 @ISA = qw(Exporter); 275 @EXPORT_OK = qw ($b); 276 277 sub import 278 { 279 $A::b = 1; # not a very useful import method 280 } 281 282and you want to Export symbol $A::b back to the module that called 283package A. Since Exporter relies on the import method to work, via 284inheritance, as it stands Exporter::import() will never get called. 285Instead, say the following: 286 287 package A; 288 @ISA = qw(Exporter); 289 @EXPORT_OK = qw ($b); 290 291 sub import 292 { 293 $A::b = 1; 294 A->export_to_level(1, @_); 295 } 296 297This will export the symbols one level 'above' the current package - ie: to 298the program or module that used package A. 299 300Note: Be careful not to modify C<@_> at all before you call export_to_level 301- or people using your package will get very unexplained results! 302 303=head2 Exporting without inheriting from Exporter 304 305By including Exporter in your @ISA you inherit an Exporter's import() method 306but you also inherit several other helper methods which you probably don't 307want. To avoid this you can do 308 309 package YourModule; 310 use Exporter qw( import ); 311 312which will export Exporter's own import() method into YourModule. 313Everything will work as before but you won't need to include Exporter in 314@YourModule::ISA. 315 316=head2 Module Version Checking 317 318The Exporter module will convert an attempt to import a number from a 319module into a call to $module_name-E<gt>require_version($value). This can 320be used to validate that the version of the module being used is 321greater than or equal to the required version. 322 323The Exporter module supplies a default require_version method which 324checks the value of $VERSION in the exporting module. 325 326Since the default require_version method treats the $VERSION number as 327a simple numeric value it will regard version 1.10 as lower than 3281.9. For this reason it is strongly recommended that you use numbers 329with at least two decimal places, e.g., 1.09. 330 331=head2 Managing Unknown Symbols 332 333In some situations you may want to prevent certain symbols from being 334exported. Typically this applies to extensions which have functions 335or constants that may not exist on some systems. 336 337The names of any symbols that cannot be exported should be listed 338in the C<@EXPORT_FAIL> array. 339 340If a module attempts to import any of these symbols the Exporter 341will give the module an opportunity to handle the situation before 342generating an error. The Exporter will call an export_fail method 343with a list of the failed symbols: 344 345 @failed_symbols = $module_name->export_fail(@failed_symbols); 346 347If the export_fail method returns an empty list then no error is 348recorded and all the requested symbols are exported. If the returned 349list is not empty then an error is generated for each symbol and the 350export fails. The Exporter provides a default export_fail method which 351simply returns the list unchanged. 352 353Uses for the export_fail method include giving better error messages 354for some symbols and performing lazy architectural checks (put more 355symbols into @EXPORT_FAIL by default and then take them out if someone 356actually tries to use them and an expensive check shows that they are 357usable on that platform). 358 359=head2 Tag Handling Utility Functions 360 361Since the symbols listed within %EXPORT_TAGS must also appear in either 362@EXPORT or @EXPORT_OK, two utility functions are provided which allow 363you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK: 364 365 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); 366 367 Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT 368 Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK 369 370Any names which are not tags are added to @EXPORT or @EXPORT_OK 371unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags 372names being silently added to @EXPORT or @EXPORT_OK. Future versions 373may make this a fatal error. 374 375=head2 Generating combined tags 376 377If several symbol categories exist in %EXPORT_TAGS, it's usually 378useful to create the utility ":all" to simplify "use" statements. 379 380The simplest way to do this is: 381 382 %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); 383 384 # add all the other ":class" tags to the ":all" class, 385 # deleting duplicates 386 { 387 my %seen; 388 389 push @{$EXPORT_TAGS{all}}, 390 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS; 391 } 392 393CGI.pm creates an ":all" tag which contains some (but not really 394all) of its categories. That could be done with one small 395change: 396 397 # add some of the other ":class" tags to the ":all" class, 398 # deleting duplicates 399 { 400 my %seen; 401 402 push @{$EXPORT_TAGS{all}}, 403 grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} 404 foreach qw/html2 html3 netscape form cgi internal/; 405 } 406 407Note that the tag names in %EXPORT_TAGS don't have the leading ':'. 408 409=head2 C<AUTOLOAD>ed Constants 410 411Many modules make use of C<AUTOLOAD>ing for constant subroutines to 412avoid having to compile and waste memory on rarely used values (see 413L<perlsub> for details on constant subroutines). Calls to such 414constant subroutines are not optimized away at compile time because 415they can't be checked at compile time for constancy. 416 417Even if a prototype is available at compile time, the body of the 418subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to 419examine both the C<()> prototype and the body of a subroutine at 420compile time to detect that it can safely replace calls to that 421subroutine with the constant value. 422 423A workaround for this is to call the constants once in a C<BEGIN> block: 424 425 package My ; 426 427 use Socket ; 428 429 foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime 430 BEGIN { SO_LINGER } 431 foo( SO_LINGER ); ## SO_LINGER optimized away at compile time. 432 433This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before 434SO_LINGER is encountered later in C<My> package. 435 436If you are writing a package that C<AUTOLOAD>s, consider forcing 437an C<AUTOLOAD> for any constants explicitly imported by other packages 438or which are usually used when your package is C<use>d. 439 440=cut 441