lib/Exporter.pm

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