[Summary view] [Print] [Text view]

   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.62';
  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  Take a look at L</Good Practices> for some variants
 124  you will like to use in modern Perl code.
 125  
 126  =head1 DESCRIPTION
 127  
 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
 132  for the common case.
 133  
 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.
 139  
 140  =head2 How to Export
 141  
 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.
 148  
 149      @EXPORT    = qw(afunc $scalar @array);   # afunc is a function
 150      @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
 151  
 152  If you are only exporting function names it is recommended to omit the
 153  ampersand, as the implementation is faster this way.
 154  
 155  =head2 Selecting What To Export
 156  
 157  Do B<not> export method names!
 158  
 159  Do B<not> export anything else by default without a good reason!
 160  
 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.
 164  
 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.
 169  
 170  (It is actually possible to get private functions by saying:
 171  
 172    my $subref = sub { ... };
 173    $subref->(@args);            # Call it as a function
 174    $obj->$subref(@args);        # Use it as a method
 175  
 176  However if you use them for methods it is up to you to figure out
 177  how to make inheritance work.)
 178  
 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.
 184  
 185  Other module design guidelines can be found in L<perlmod>.
 186  
 187  =head2 How to Import
 188  
 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:
 191  
 192  =over 4
 193  
 194  =item C<use ModuleName;>
 195  
 196  This imports all the symbols from ModuleName's @EXPORT into the namespace
 197  of the C<use> statement.
 198  
 199  =item C<use ModuleName ();>
 200  
 201  This causes perl to load your module but does not import any symbols.
 202  
 203  =item C<use ModuleName qw(...);>
 204  
 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.
 209  
 210  =back
 211  
 212  Unless you want to use its advanced features, this is probably all you
 213  need to know to use Exporter.
 214  
 215  =head1 Advanced features
 216  
 217  =head2 Specialised Import Lists
 218  
 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:
 223  
 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
 228  
 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.
 234  
 235  e.g., Module.pm defines:
 236  
 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)]);
 240  
 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.
 243  
 244  An application using Module can say something like:
 245  
 246      use Module qw(:DEFAULT :T2 !B3 A3);
 247  
 248  Other examples include:
 249  
 250      use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
 251      use POSIX  qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
 252  
 253  Remember that most patterns (using //) will need to be anchored
 254  with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
 255  
 256  You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
 257  specifications are being processed and what is actually being imported
 258  into modules.
 259  
 260  =head2 Exporting without using Exporter's import method
 261  
 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
 264  method looks like:
 265  
 266      MyPackage->export_to_level($where_to_export, $package, @what_to_export);
 267  
 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
 271  currently unused.
 272  
 273  For example, suppose that you have a module, A, which already has an
 274  import function:
 275  
 276      package A;
 277  
 278      @ISA = qw(Exporter);
 279      @EXPORT_OK = qw ($b);
 280  
 281      sub import
 282      {
 283      $A::b = 1;     # not a very useful import method
 284      }
 285  
 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:
 290  
 291      package A;
 292      @ISA = qw(Exporter);
 293      @EXPORT_OK = qw ($b);
 294  
 295      sub import
 296      {
 297      $A::b = 1;
 298      A->export_to_level(1, @_);
 299      }
 300  
 301  This will export the symbols one level 'above' the current package - ie: to 
 302  the program or module that used package A. 
 303  
 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!
 306  
 307  =head2 Exporting without inheriting from Exporter
 308  
 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
 312  
 313    package YourModule;
 314    use Exporter qw( import );
 315  
 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
 318  @YourModule::ISA.
 319  
 320  Note: This feature was introduced in version 5.57
 321  of Exporter, released with perl 5.8.3.
 322  
 323  =head2 Module Version Checking
 324  
 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.
 329  
 330  The Exporter module supplies a default require_version method which
 331  checks the value of $VERSION in the exporting module.
 332  
 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.
 337  
 338  =head2 Managing Unknown Symbols
 339  
 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.
 343  
 344  The names of any symbols that cannot be exported should be listed
 345  in the C<@EXPORT_FAIL> array.
 346  
 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:
 351  
 352    @failed_symbols = $module_name->export_fail(@failed_symbols);
 353  
 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.
 359  
 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).
 365  
 366  =head2 Tag Handling Utility Functions
 367  
 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:
 371  
 372    %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
 373  
 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
 376  
 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.
 381  
 382  =head2 Generating combined tags
 383  
 384  If several symbol categories exist in %EXPORT_TAGS, it's usually
 385  useful to create the utility ":all" to simplify "use" statements.
 386  
 387  The simplest way to do this is:
 388  
 389    %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
 390  
 391    # add all the other ":class" tags to the ":all" class,
 392    # deleting duplicates
 393    {
 394      my %seen;
 395  
 396      push @{$EXPORT_TAGS{all}},
 397        grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
 398    }
 399  
 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
 402  change:
 403  
 404    # add some of the other ":class" tags to the ":all" class,
 405    # deleting duplicates
 406    {
 407      my %seen;
 408  
 409      push @{$EXPORT_TAGS{all}},
 410        grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
 411          foreach qw/html2 html3 netscape form cgi internal/;
 412    }
 413  
 414  Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
 415  
 416  =head2 C<AUTOLOAD>ed Constants
 417  
 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.
 423  
 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.
 429  
 430  A workaround for this is to call the constants once in a C<BEGIN> block:
 431  
 432     package My ;
 433  
 434     use Socket ;
 435  
 436     foo( SO_LINGER );     ## SO_LINGER NOT optimized away; called at runtime
 437     BEGIN { SO_LINGER }
 438     foo( SO_LINGER );     ## SO_LINGER optimized away at compile time.
 439  
 440  This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
 441  SO_LINGER is encountered later in C<My> package.
 442  
 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.
 446  
 447  =head1 Good Practices
 448  
 449  =head2 Declaring C<@EXPORT_OK> and Friends
 450  
 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.
 454  
 455    our @ISA = qw(Exporter);
 456    our @EXPORT_OK = qw(munge frobnicate);
 457  
 458  If backward compatibility for Perls under 5.6 is important,
 459  one must write instead a C<use vars> statement.
 460  
 461    use vars qw(@ISA @EXPORT_OK);
 462    @ISA = qw(Exporter);
 463    @EXPORT_OK = qw(munge frobnicate);
 464  
 465  =head2 Playing Safe
 466  
 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.
 473  
 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:
 477  
 478    package YourModule;
 479  
 480    use strict;
 481    use warnings;
 482  
 483    our (@ISA, @EXPORT_OK);
 484    BEGIN {
 485       require Exporter;
 486       @ISA = qw(Exporter);
 487       @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
 488    }
 489  
 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
 493  or just plain wrong.
 494  
 495  With respect to loading C<Exporter> and inheriting, there
 496  are alternatives with the use of modules like C<base> and C<parent>.
 497  
 498    use base qw( Exporter );
 499    # or
 500    use parent qw( Exporter );
 501  
 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.
 508  
 509  For more details, see the documentation and code of
 510  L<base> and L<parent>.
 511  
 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
 516  use statement.
 517  
 518     use Exporter::Easy (
 519         OK => [ qw(munge frobnicate) ],
 520     );
 521     # @ISA setup is automatic
 522     # all assignments happen at compile time
 523  
 524  =head2 What not to Export
 525  
 526  You have been warned already in L</Selecting What To Export>
 527  to not export:
 528  
 529  =over 4
 530  
 531  =item *
 532  
 533  method names (because you don't need to
 534  and that's likely to not do what you want),
 535  
 536  =item *
 537  
 538  anything by default (because you don't want to surprise your users...
 539  badly)
 540  
 541  =item *
 542  
 543  anything you don't need to (because less is more)
 544  
 545  =back
 546  
 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.
 550  
 551    @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
 552  
 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.
 557  
 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.
 561  
 562  =head1 SEE ALSO
 563  
 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.
 570  
 571      Exporter::Easy
 572      Exporter::Lite
 573      Exporter::Renaming
 574      Exporter::Tidy
 575      Sub::Exporter / Sub::Installer
 576      Perl6::Export / Perl6::Export::Attrs
 577  
 578  =head1 LICENSE
 579  
 580  This library is free software. You can redistribute it
 581  and/or modify it under the same terms as Perl itself.
 582  
 583  =cut