ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/staticperl/perl/lib/Exporter.pm
Revision: 1.1
Committed: Thu Jun 30 14:27:08 2005 UTC (21 years, 4 months ago) by root
Branch: MAIN
CVS Tags: PERL-5-8-7, HEAD
Branch point for: PERL
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.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.58';
13     our (%Cache);
14     $Carp::Internal{Exporter} = 1;
15    
16     sub 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    
25     sub export {
26     goto &{as_heavy()};
27     }
28    
29     sub 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    
70     sub 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    
79     sub export_to_level {
80     goto &{as_heavy()};
81     }
82    
83     sub export_tags {
84     goto &{as_heavy()};
85     }
86    
87     sub export_ok_tags {
88     goto &{as_heavy()};
89     }
90    
91     sub require_version {
92     goto &{as_heavy()};
93     }
94    
95     1;
96     __END__
97    
98     =head1 NAME
99    
100     Exporter - Implements default import method for modules
101    
102     =head1 SYNOPSIS
103    
104     In 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    
111     or
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    
117     In 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    
124     The Exporter module implements an C<import> method which allows a module
125     to export functions and variables to its users' namespaces. Many modules
126     use Exporter rather than implementing their own C<import> method because
127     Exporter provides a highly flexible interface, with an implementation optimised
128     for the common case.
129    
130     Perl automatically calls the C<import> method when processing a
131     C<use> statement for a module. Modules and C<use> are documented
132     in L<perlfunc> and L<perlmod>. Understanding the concept of
133     modules and how the C<use> statement operates is important to
134     understanding the Exporter.
135    
136     =head2 How to Export
137    
138     The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of
139     symbols that are going to be exported into the users name space by
140     default, or which they can request to be exported, respectively. The
141     symbols can represent functions, scalars, arrays, hashes, or typeglobs.
142     The symbols must be given by full name with the exception that the
143     ampersand 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    
148     If you are only exporting function names it is recommended to omit the
149     ampersand, as the implementation is faster this way.
150    
151     =head2 Selecting What To Export
152    
153     Do B<not> export method names!
154    
155     Do B<not> export anything else by default without a good reason!
156    
157     Exports pollute the namespace of the module user. If you must export
158     try to use @EXPORT_OK in preference to @EXPORT and avoid short or
159     common symbol names to reduce the risk of name clashes.
160    
161     Generally anything not exported is still accessible from outside the
162     module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
163     syntax. By convention you can use a leading underscore on names to
164     informally 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    
172     However if you use them for methods it is up to you to figure out
173     how to make inheritance work.)
174    
175     As a general rule, if the module is trying to be object oriented
176     then export nothing. If it's just a collection of functions then
177     @EXPORT_OK anything but use @EXPORT with caution. For function and
178     method names use barewords in preference to names prefixed with
179     ampersands for the export lists.
180    
181     Other module design guidelines can be found in L<perlmod>.
182    
183     =head2 How to Import
184    
185     In other files which wish to use your module there are three basic ways for
186     them to load your module and import its symbols:
187    
188     =over 4
189    
190     =item C<use ModuleName;>
191    
192     This imports all the symbols from ModuleName's @EXPORT into the namespace
193     of the C<use> statement.
194    
195     =item C<use ModuleName ();>
196    
197     This causes perl to load your module but does not import any symbols.
198    
199     =item C<use ModuleName qw(...);>
200    
201     This imports only the symbols listed by the caller into their namespace.
202     All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error
203     occurs. The advanced export features of Exporter are accessed like this,
204     but with list entries that are syntactically distinct from symbol names.
205    
206     =back
207    
208     Unless you want to use its advanced features, this is probably all you
209     need to know to use Exporter.
210    
211     =head1 Advanced features
212    
213     =head2 Specialised Import Lists
214    
215     If any of the entries in an import list begins with !, : or / then
216     the list is treated as a series of specifications which either add to
217     or delete from the list of names to import. They are processed left to
218     right. 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    
225     A leading ! indicates that matching names should be deleted from the
226     list of names to import. If the first specification is a deletion it
227     is treated as though preceded by :DEFAULT. If you just want to import
228     extra names in addition to the default set you will still need to
229     include :DEFAULT explicitly.
230    
231     e.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    
240     An application using Module can say something like:
241    
242     use Module qw(:DEFAULT :T2 !B3 A3);
243    
244     Other examples include:
245    
246     use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
247     use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
248    
249     Remember that most patterns (using //) will need to be anchored
250     with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>.
251    
252     You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the
253     specifications are being processed and what is actually being imported
254     into modules.
255    
256     =head2 Exporting without using Exporter's import method
257    
258     Exporter has a special method, 'export_to_level' which is used in situations
259     where you can't directly call Exporter's import method. The export_to_level
260     method looks like:
261    
262     MyPackage->export_to_level($where_to_export, $package, @what_to_export);
263    
264     where $where_to_export is an integer telling how far up the calling stack
265     to export your symbols, and @what_to_export is an array telling what
266     symbols *to* export (usually this is @_). The $package argument is
267     currently unused.
268    
269     For example, suppose that you have a module, A, which already has an
270     import 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    
282     and you want to Export symbol $A::b back to the module that called
283     package A. Since Exporter relies on the import method to work, via
284     inheritance, as it stands Exporter::import() will never get called.
285     Instead, 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    
297     This will export the symbols one level 'above' the current package - ie: to
298     the program or module that used package A.
299    
300     Note: 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    
305     By including Exporter in your @ISA you inherit an Exporter's import() method
306     but you also inherit several other helper methods which you probably don't
307     want. To avoid this you can do
308    
309     package YourModule;
310     use Exporter qw( import );
311    
312     which will export Exporter's own import() method into YourModule.
313     Everything will work as before but you won't need to include Exporter in
314     @YourModule::ISA.
315    
316     =head2 Module Version Checking
317    
318     The Exporter module will convert an attempt to import a number from a
319     module into a call to $module_name-E<gt>require_version($value). This can
320     be used to validate that the version of the module being used is
321     greater than or equal to the required version.
322    
323     The Exporter module supplies a default require_version method which
324     checks the value of $VERSION in the exporting module.
325    
326     Since the default require_version method treats the $VERSION number as
327     a simple numeric value it will regard version 1.10 as lower than
328     1.9. For this reason it is strongly recommended that you use numbers
329     with at least two decimal places, e.g., 1.09.
330    
331     =head2 Managing Unknown Symbols
332    
333     In some situations you may want to prevent certain symbols from being
334     exported. Typically this applies to extensions which have functions
335     or constants that may not exist on some systems.
336    
337     The names of any symbols that cannot be exported should be listed
338     in the C<@EXPORT_FAIL> array.
339    
340     If a module attempts to import any of these symbols the Exporter
341     will give the module an opportunity to handle the situation before
342     generating an error. The Exporter will call an export_fail method
343     with a list of the failed symbols:
344    
345     @failed_symbols = $module_name->export_fail(@failed_symbols);
346    
347     If the export_fail method returns an empty list then no error is
348     recorded and all the requested symbols are exported. If the returned
349     list is not empty then an error is generated for each symbol and the
350     export fails. The Exporter provides a default export_fail method which
351     simply returns the list unchanged.
352    
353     Uses for the export_fail method include giving better error messages
354     for some symbols and performing lazy architectural checks (put more
355     symbols into @EXPORT_FAIL by default and then take them out if someone
356     actually tries to use them and an expensive check shows that they are
357     usable on that platform).
358    
359     =head2 Tag Handling Utility Functions
360    
361     Since the symbols listed within %EXPORT_TAGS must also appear in either
362     @EXPORT or @EXPORT_OK, two utility functions are provided which allow
363     you 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    
370     Any names which are not tags are added to @EXPORT or @EXPORT_OK
371     unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
372     names being silently added to @EXPORT or @EXPORT_OK. Future versions
373     may make this a fatal error.
374    
375     =head2 Generating combined tags
376    
377     If several symbol categories exist in %EXPORT_TAGS, it's usually
378     useful to create the utility ":all" to simplify "use" statements.
379    
380     The 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    
393     CGI.pm creates an ":all" tag which contains some (but not really
394     all) of its categories. That could be done with one small
395     change:
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    
407     Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
408    
409     =head2 C<AUTOLOAD>ed Constants
410    
411     Many modules make use of C<AUTOLOAD>ing for constant subroutines to
412     avoid having to compile and waste memory on rarely used values (see
413     L<perlsub> for details on constant subroutines). Calls to such
414     constant subroutines are not optimized away at compile time because
415     they can't be checked at compile time for constancy.
416    
417     Even if a prototype is available at compile time, the body of the
418     subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
419     examine both the C<()> prototype and the body of a subroutine at
420     compile time to detect that it can safely replace calls to that
421     subroutine with the constant value.
422    
423     A 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    
433     This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
434     SO_LINGER is encountered later in C<My> package.
435    
436     If you are writing a package that C<AUTOLOAD>s, consider forcing
437     an C<AUTOLOAD> for any constants explicitly imported by other packages
438     or which are usually used when your package is C<use>d.
439    
440     =cut