Fix [perl #114812] Configure not finding isblank().
[perl.git] / 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.67';
13 our (%Cache);
14
15 sub as_heavy {
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];
20   $c =~ s/.*:://;
21   \&{"Exporter::Heavy::heavy_$c"};
22 }
23
24 sub export {
25   goto &{as_heavy()};
26 }
27
28 sub import {
29   my $pkg = shift;
30   my $callpkg = caller($ExportLevel);
31
32   if ($pkg eq "Exporter" and @_ and $_[0] eq "import") {
33     *{$callpkg."::import"} = \&import;
34     return;
35   }
36
37   # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-(
38   my $exports = \@{"$pkg\::EXPORT"};
39   # But, avoid creating things if they don't exist, which saves a couple of
40   # hundred bytes per package processed.
41   my $fail = ${$pkg . '::'}{EXPORT_FAIL} && \@{"$pkg\::EXPORT_FAIL"};
42   return export $pkg, $callpkg, @_
43     if $Verbose or $Debug or $fail && @$fail > 1;
44   my $export_cache = ($Cache{$pkg} ||= {});
45   my $args = @_ or @_ = @$exports;
46
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 @$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} if not $SIG{__WARN__};
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 F<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 C<YourModule>:
119
120   use YourModule 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 C<@EXPORT_OK> in preference to C<@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 C<YourModule::item_name> (or C<< $blessed_ref->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 C<@EXPORT_OK> anything but use C<@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 YourModule;>
195
196 This imports all the symbols from YourModule's C<@EXPORT> into the namespace
197 of the C<use> statement.
198
199 =item C<use YourModule ();>
200
201 This causes perl to load your module but does not import any symbols.
202
203 =item C<use YourModule qw(...);>
204
205 This imports only the symbols listed by the caller into their namespace.
206 All listed symbols must be in your C<@EXPORT> or C<@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., F<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
243 Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
244
245 An application using Module can say something like:
246
247     use Module qw(:DEFAULT :T2 !B3 A3);
248
249 Other examples include:
250
251     use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
252     use POSIX  qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
253
254 Remember that most patterns (using //) will need to be anchored
255 with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
256
257 You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
258 specifications are being processed and what is actually being imported
259 into modules.
260
261 =head2 Exporting Without Using Exporter's import Method
262
263 Exporter has a special method, 'export_to_level' which is used in situations
264 where you can't directly call Exporter's
265 import method.  The export_to_level
266 method looks like:
267
268     MyPackage->export_to_level(
269         $where_to_export, $package, @what_to_export
270     );
271
272 where C<$where_to_export> is an integer telling how far up the calling stack
273 to export your symbols, and C<@what_to_export> is an array telling what
274 symbols *to* export (usually this is C<@_>).  The C<$package> argument is
275 currently unused.
276
277 For example, suppose that you have a module, A, which already has an
278 import function:
279
280     package A;
281
282     @ISA = qw(Exporter);
283     @EXPORT_OK = qw ($b);
284
285     sub import
286     {
287         $A::b = 1;     # not a very useful import method
288     }
289
290 and you want to Export symbol C<$A::b> back to the module that called 
291 package A.  Since Exporter relies on the import method to work, via 
292 inheritance, as it stands Exporter::import() will never get called. 
293 Instead, say the following:
294
295     package A;
296     @ISA = qw(Exporter);
297     @EXPORT_OK = qw ($b);
298
299     sub import
300     {
301         $A::b = 1;
302         A->export_to_level(1, @_);
303     }
304
305 This will export the symbols one level 'above' the current package - ie: to 
306 the program or module that used package A. 
307
308 Note: Be careful not to modify C<@_> at all before you call export_to_level
309 - or people using your package will get very unexplained results!
310
311 =head2 Exporting Without Inheriting from Exporter
312
313 By including Exporter in your C<@ISA> you inherit an Exporter's import() method
314 but you also inherit several other helper methods which you probably don't
315 want.  To avoid this you can do
316
317   package YourModule;
318   use Exporter qw( import );
319
320 which will export Exporter's own import() method into YourModule.
321 Everything will work as before but you won't need to include Exporter in
322 C<@YourModule::ISA>.
323
324 Note: This feature was introduced in version 5.57
325 of Exporter, released with perl 5.8.3.
326
327 =head2 Module Version Checking
328
329 The Exporter module will convert an attempt to import a number from a
330 module into a call to C<< $module_name->VERSION($value) >>.  This can
331 be used to validate that the version of the module being used is
332 greater than or equal to the required version.
333
334 For historical reasons, Exporter supplies a C<require_version> method that
335 simply delegates to C<VERSION>.  Originally, before C<UNIVERSAL::VERSION>
336 existed, Exporter would call C<require_version>.
337
338 Since the C<UNIVERSAL::VERSION> method treats the C<$VERSION> number as
339 a simple numeric value it will regard version 1.10 as lower than
340 1.9.  For this reason it is strongly recommended that you use numbers
341 with at least two decimal places, e.g., 1.09.
342
343 =head2 Managing Unknown Symbols
344
345 In some situations you may want to prevent certain symbols from being
346 exported.  Typically this applies to extensions which have functions
347 or constants that may not exist on some systems.
348
349 The names of any symbols that cannot be exported should be listed
350 in the C<@EXPORT_FAIL> array.
351
352 If a module attempts to import any of these symbols the Exporter
353 will give the module an opportunity to handle the situation before
354 generating an error.  The Exporter will call an export_fail method
355 with a list of the failed symbols:
356
357   @failed_symbols = $module_name->export_fail(@failed_symbols);
358
359 If the C<export_fail> method returns an empty list then no error is
360 recorded and all the requested symbols are exported.  If the returned
361 list is not empty then an error is generated for each symbol and the
362 export fails.  The Exporter provides a default C<export_fail> method which
363 simply returns the list unchanged.
364
365 Uses for the C<export_fail> method include giving better error messages
366 for some symbols and performing lazy architectural checks (put more
367 symbols into C<@EXPORT_FAIL> by default and then take them out if someone
368 actually tries to use them and an expensive check shows that they are
369 usable on that platform).
370
371 =head2 Tag Handling Utility Functions
372
373 Since the symbols listed within C<%EXPORT_TAGS> must also appear in either
374 C<@EXPORT> or C<@EXPORT_OK>, two utility functions are provided which allow
375 you to easily add tagged sets of symbols to C<@EXPORT> or C<@EXPORT_OK>:
376
377   %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
378
379   Exporter::export_tags('foo');     # add aa, bb and cc to @EXPORT
380   Exporter::export_ok_tags('bar');  # add aa, cc and dd to @EXPORT_OK
381
382 Any names which are not tags are added to C<@EXPORT> or C<@EXPORT_OK>
383 unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
384 names being silently added to C<@EXPORT> or C<@EXPORT_OK>.  Future versions
385 may make this a fatal error.
386
387 =head2 Generating Combined Tags
388
389 If several symbol categories exist in C<%EXPORT_TAGS>, it's usually
390 useful to create the utility ":all" to simplify "use" statements.
391
392 The simplest way to do this is:
393
394   %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
395
396   # add all the other ":class" tags to the ":all" class,
397   # deleting duplicates
398   {
399     my %seen;
400
401     push @{$EXPORT_TAGS{all}},
402       grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
403   }
404
405 F<CGI.pm> creates an ":all" tag which contains some (but not really
406 all) of its categories.  That could be done with one small
407 change:
408
409   # add some of the other ":class" tags to the ":all" class,
410   # deleting duplicates
411   {
412     my %seen;
413
414     push @{$EXPORT_TAGS{all}},
415       grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
416         foreach qw/html2 html3 netscape form cgi internal/;
417   }
418
419 Note that the tag names in C<%EXPORT_TAGS> don't have the leading ':'.
420
421 =head2 C<AUTOLOAD>ed Constants
422
423 Many modules make use of C<AUTOLOAD>ing for constant subroutines to
424 avoid having to compile and waste memory on rarely used values (see
425 L<perlsub> for details on constant subroutines).  Calls to such
426 constant subroutines are not optimized away at compile time because
427 they can't be checked at compile time for constancy.
428
429 Even if a prototype is available at compile time, the body of the
430 subroutine is not (it hasn't been C<AUTOLOAD>ed yet).  perl needs to
431 examine both the C<()> prototype and the body of a subroutine at
432 compile time to detect that it can safely replace calls to that
433 subroutine with the constant value.
434
435 A workaround for this is to call the constants once in a C<BEGIN> block:
436
437    package My ;
438
439    use Socket ;
440
441    foo( SO_LINGER );  ## SO_LINGER NOT optimized away; called at runtime
442    BEGIN { SO_LINGER }
443    foo( SO_LINGER );  ## SO_LINGER optimized away at compile time.
444
445 This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
446 SO_LINGER is encountered later in C<My> package.
447
448 If you are writing a package that C<AUTOLOAD>s, consider forcing
449 an C<AUTOLOAD> for any constants explicitly imported by other packages
450 or which are usually used when your package is C<use>d.
451
452 =head1 Good Practices
453
454 =head2 Declaring C<@EXPORT_OK> and Friends
455
456 When using C<Exporter> with the standard C<strict> and C<warnings>
457 pragmas, the C<our> keyword is needed to declare the package
458 variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc.
459
460   our @ISA = qw(Exporter);
461   our @EXPORT_OK = qw(munge frobnicate);
462
463 If backward compatibility for Perls under 5.6 is important,
464 one must write instead a C<use vars> statement.
465
466   use vars qw(@ISA @EXPORT_OK);
467   @ISA = qw(Exporter);
468   @EXPORT_OK = qw(munge frobnicate);
469
470 =head2 Playing Safe
471
472 There are some caveats with the use of runtime statements
473 like C<require Exporter> and the assignment to package
474 variables, which can very subtle for the unaware programmer.
475 This may happen for instance with mutually recursive
476 modules, which are affected by the time the relevant
477 constructions are executed.
478
479 The ideal (but a bit ugly) way to never have to think
480 about that is to use C<BEGIN> blocks.  So the first part
481 of the L</SYNOPSIS> code could be rewritten as:
482
483   package YourModule;
484
485   use strict;
486   use warnings;
487
488   our (@ISA, @EXPORT_OK);
489   BEGIN {
490      require Exporter;
491      @ISA = qw(Exporter);
492      @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
493   }
494
495 The C<BEGIN> will assure that the loading of F<Exporter.pm>
496 and the assignments to C<@ISA> and C<@EXPORT_OK> happen
497 immediately, leaving no room for something to get awry
498 or just plain wrong.
499
500 With respect to loading C<Exporter> and inheriting, there
501 are alternatives with the use of modules like C<base> and C<parent>.
502
503   use base qw( Exporter );
504   # or
505   use parent qw( Exporter );
506
507 Any of these statements are nice replacements for
508 C<BEGIN { require Exporter; @ISA = qw(Exporter); }>
509 with the same compile-time effect.  The basic difference
510 is that C<base> code interacts with declared C<fields>
511 while C<parent> is a streamlined version of the older
512 C<base> code to just establish the IS-A relationship.
513
514 For more details, see the documentation and code of
515 L<base> and L<parent>.
516
517 Another thorough remedy to that runtime
518 vs. compile-time trap is to use L<Exporter::Easy>,
519 which is a wrapper of Exporter that allows all
520 boilerplate code at a single gulp in the
521 use statement.
522
523    use Exporter::Easy (
524        OK => [ qw(munge frobnicate) ],
525    );
526    # @ISA setup is automatic
527    # all assignments happen at compile time
528
529 =head2 What Not to Export
530
531 You have been warned already in L</Selecting What to Export>
532 to not export:
533
534 =over 4
535
536 =item *
537
538 method names (because you don't need to
539 and that's likely to not do what you want),
540
541 =item *
542
543 anything by default (because you don't want to surprise your users...
544 badly)
545
546 =item *
547
548 anything you don't need to (because less is more)
549
550 =back
551
552 There's one more item to add to this list.  Do B<not>
553 export variable names.  Just because C<Exporter> lets you
554 do that, it does not mean you should.
555
556   @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
557
558 Exporting variables is not a good idea.  They can
559 change under the hood, provoking horrible
560 effects at-a-distance, that are too hard to track
561 and to fix.  Trust me: they are not worth it.
562
563 To provide the capability to set/get class-wide
564 settings, it is best instead to provide accessors
565 as subroutines or class methods instead.
566
567 =head1 SEE ALSO
568
569 C<Exporter> is definitely not the only module with
570 symbol exporter capabilities.  At CPAN, you may find
571 a bunch of them.  Some are lighter.  Some
572 provide improved APIs and features.  Peek the one
573 that fits your needs.  The following is
574 a sample list of such modules.
575
576     Exporter::Easy
577     Exporter::Lite
578     Exporter::Renaming
579     Exporter::Tidy
580     Sub::Exporter / Sub::Installer
581     Perl6::Export / Perl6::Export::Attrs
582
583 =head1 LICENSE
584
585 This library is free software.  You can redistribute it
586 and/or modify it under the same terms as Perl itself.
587
588 =cut
589
590
591