pod/modpods/Exporter.pod

   1 =head1 NAME
   2
   3 Exporter - module to control namespace manipulations
   4
   5 import - import functions into callers namespace
   6
   7 =head1 SYNOPSYS
   8
   9     package WhatEver;
  10     require Exporter;
  11     @ISA = (Exporter);
  12     @EXPORT    = qw(func1, $foo, %tabs);
  13     @EXPORT_OK = qw(sin cos);
  14     ...
  15     use Whatever;
  16     use WhatEver 'sin';
  17
  18 =head1 DESCRIPTION
  19
  20 The Exporter module is used by well-behaved Perl modules to
  21 control what they will export into their user's namespace.
  22 The WhatEver module above has placed in its export list
  23 the function C<func1()>, the scalar C<$foo>, and the
  24 hash C<%tabs>.  When someone decides to
  25 C<use WhatEver>, they get those identifier grafted
  26 onto their own namespace.  That means the user of
  27 package whatever can use the function func1() instead
  28 of fully qualifying it as WhatEver::func1().
  29
  30 You should be careful of such namespace pollution.
  31 Of course, the user of the WhatEver module is free to
  32 use a C<require> instead of a C<use>, which will
  33 preserve the sanctity of their namespace.
  34
  35 In particular, you almost certainly shouldn't
  36 automatically export functions whose names are
  37 already used in the language.  For this reason,
  38 the @EXPORT_OK list contains those function which
  39 may be selectively imported, as the sin() function
  40 was above.
  41 See L<perlsub/Overriding builtin functions>.
  42
  43 You can't import names that aren't in either the @EXPORT
  44 or the @EXPORT_OK list.
  45
  46 Remember that these two constructs are identical:
  47
  48     use WhatEver;
  49
  50     BEGIN {
  51         require WhatEver;
  52         import Module;
  53     }
  54
  55 The import() function above is not predefined in the
  56 language.  Rather, it's a method in the Exporter module.
  57 A sneaky library writer could conceivably have an import()
  58 method that behaved differently from the standard one, but
  59 that's not very friendly.
  60