|
Packit Service |
e1cd52 |
NAME
|
|
Packit Service |
e1cd52 |
Exporter - Implements default import method for modules
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
SYNOPSIS
|
|
Packit Service |
e1cd52 |
In module YourModule.pm:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
package YourModule;
|
|
Packit Service |
e1cd52 |
require Exporter;
|
|
Packit Service |
e1cd52 |
@ISA = qw(Exporter);
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw(munge frobnicate); # symbols to export on request
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
or
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
package YourModule;
|
|
Packit Service |
e1cd52 |
use Exporter 'import'; # gives you Exporter's import() method directly
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw(munge frobnicate); # symbols to export on request
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
In other files which wish to use "YourModule":
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use YourModule qw(frobnicate); # import listed symbols
|
|
Packit Service |
e1cd52 |
frobnicate ($left, $right) # calls YourModule::frobnicate
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Take a look at "Good Practices" for some variants you will like to use
|
|
Packit Service |
e1cd52 |
in modern Perl code.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
DESCRIPTION
|
|
Packit Service |
e1cd52 |
The Exporter module implements an "import" method which allows a module
|
|
Packit Service |
e1cd52 |
to export functions and variables to its users' namespaces. Many modules
|
|
Packit Service |
e1cd52 |
use Exporter rather than implementing their own "import" method because
|
|
Packit Service |
e1cd52 |
Exporter provides a highly flexible interface, with an implementation
|
|
Packit Service |
e1cd52 |
optimised for the common case.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Perl automatically calls the "import" method when processing a "use"
|
|
Packit Service |
e1cd52 |
statement for a module. Modules and "use" are documented in perlfunc and
|
|
Packit Service |
e1cd52 |
perlmod. Understanding the concept of modules and how the "use"
|
|
Packit Service |
e1cd52 |
statement operates is important to understanding the Exporter.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
How to Export
|
|
Packit Service |
e1cd52 |
The arrays @EXPORT and @EXPORT_OK in a module hold lists of symbols that
|
|
Packit Service |
e1cd52 |
are going to be exported into the users name space by default, or which
|
|
Packit Service |
e1cd52 |
they can request to be exported, respectively. The symbols can represent
|
|
Packit Service |
e1cd52 |
functions, scalars, arrays, hashes, or typeglobs. The symbols must be
|
|
Packit Service |
e1cd52 |
given by full name with the exception that the ampersand in front of a
|
|
Packit Service |
e1cd52 |
function is optional, e.g.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
@EXPORT = qw(afunc $scalar @array); # afunc is a function
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
If you are only exporting function names it is recommended to omit the
|
|
Packit Service |
e1cd52 |
ampersand, as the implementation is faster this way.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Selecting What To Export
|
|
Packit Service |
e1cd52 |
Do not export method names!
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Do not export anything else by default without a good reason!
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Exports pollute the namespace of the module user. If you must export try
|
|
Packit Service |
e1cd52 |
to use @EXPORT_OK in preference to @EXPORT and avoid short or common
|
|
Packit Service |
e1cd52 |
symbol names to reduce the risk of name clashes.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Generally anything not exported is still accessible from outside the
|
|
Packit Service |
e1cd52 |
module using the "YourModule::item_name" (or "$blessed_ref->method")
|
|
Packit Service |
e1cd52 |
syntax. By convention you can use a leading underscore on names to
|
|
Packit Service |
e1cd52 |
informally indicate that they are 'internal' and not for public use.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
(It is actually possible to get private functions by saying:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
my $subref = sub { ... };
|
|
Packit Service |
e1cd52 |
$subref->(@args); # Call it as a function
|
|
Packit Service |
e1cd52 |
$obj->$subref(@args); # Use it as a method
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
However if you use them for methods it is up to you to figure out how to
|
|
Packit Service |
e1cd52 |
make inheritance work.)
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
As a general rule, if the module is trying to be object oriented then
|
|
Packit Service |
e1cd52 |
export nothing. If it's just a collection of functions then @EXPORT_OK
|
|
Packit Service |
e1cd52 |
anything but use @EXPORT with caution. For function and method names use
|
|
Packit Service |
e1cd52 |
barewords in preference to names prefixed with ampersands for the export
|
|
Packit Service |
e1cd52 |
lists.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Other module design guidelines can be found in perlmod.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
How to Import
|
|
Packit Service |
e1cd52 |
In other files which wish to use your module there are three basic ways
|
|
Packit Service |
e1cd52 |
for them to load your module and import its symbols:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
"use YourModule;"
|
|
Packit Service |
e1cd52 |
This imports all the symbols from YourModule's @EXPORT into the
|
|
Packit Service |
e1cd52 |
namespace of the "use" statement.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
"use YourModule ();"
|
|
Packit Service |
e1cd52 |
This causes perl to load your module but does not import any
|
|
Packit Service |
e1cd52 |
symbols.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
"use YourModule qw(...);"
|
|
Packit Service |
e1cd52 |
This imports only the symbols listed by the caller into their
|
|
Packit Service |
e1cd52 |
namespace. All listed symbols must be in your @EXPORT or @EXPORT_OK,
|
|
Packit Service |
e1cd52 |
else an error occurs. The advanced export features of Exporter are
|
|
Packit Service |
e1cd52 |
accessed like this, but with list entries that are syntactically
|
|
Packit Service |
e1cd52 |
distinct from symbol names.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Unless you want to use its advanced features, this is probably all you
|
|
Packit Service |
e1cd52 |
need to know to use Exporter.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Advanced features
|
|
Packit Service |
e1cd52 |
Specialised Import Lists
|
|
Packit Service |
e1cd52 |
If any of the entries in an import list begins with !, : or / then the
|
|
Packit Service |
e1cd52 |
list is treated as a series of specifications which either add to or
|
|
Packit Service |
e1cd52 |
delete from the list of names to import. They are processed left to
|
|
Packit Service |
e1cd52 |
right. Specifications are in the form:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
[!]name This name only
|
|
Packit Service |
e1cd52 |
[!]:DEFAULT All names in @EXPORT
|
|
Packit Service |
e1cd52 |
[!]:tag All names in $EXPORT_TAGS{tag} anonymous list
|
|
Packit Service |
e1cd52 |
[!]/pattern/ All names in @EXPORT and @EXPORT_OK which match
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
A leading ! indicates that matching names should be deleted from the
|
|
Packit Service |
e1cd52 |
list of names to import. If the first specification is a deletion it is
|
|
Packit Service |
e1cd52 |
treated as though preceded by :DEFAULT. If you just want to import extra
|
|
Packit Service |
e1cd52 |
names in addition to the default set you will still need to include
|
|
Packit Service |
e1cd52 |
:DEFAULT explicitly.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
e.g., Module.pm defines:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
@EXPORT = qw(A1 A2 A3 A4 A5);
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw(B1 B2 B3 B4 B5);
|
|
Packit Service |
e1cd52 |
%EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Note that you cannot use tags in @EXPORT or @EXPORT_OK.
|
|
Packit Service |
e1cd52 |
Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
An application using Module can say something like:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use Module qw(:DEFAULT :T2 !B3 A3);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Other examples include:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
|
|
Packit Service |
e1cd52 |
use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Remember that most patterns (using //) will need to be anchored with a
|
|
Packit Service |
e1cd52 |
leading ^, e.g., "/^EXIT/" rather than "/EXIT/".
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
You can say "BEGIN { $Exporter::Verbose=1 }" to see how the
|
|
Packit Service |
e1cd52 |
specifications are being processed and what is actually being imported
|
|
Packit Service |
e1cd52 |
into modules.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Exporting without using Exporter's import method
|
|
Packit Service |
e1cd52 |
Exporter has a special method, 'export_to_level' which is used in
|
|
Packit Service |
e1cd52 |
situations where you can't directly call Exporter's import method. The
|
|
Packit Service |
e1cd52 |
export_to_level method looks like:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
MyPackage->export_to_level($where_to_export, $package, @what_to_export);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
where $where_to_export is an integer telling how far up the calling
|
|
Packit Service |
e1cd52 |
stack to export your symbols, and @what_to_export is an array telling
|
|
Packit Service |
e1cd52 |
what symbols *to* export (usually this is @_). The $package argument is
|
|
Packit Service |
e1cd52 |
currently unused.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
For example, suppose that you have a module, A, which already has an
|
|
Packit Service |
e1cd52 |
import function:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
package A;
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
@ISA = qw(Exporter);
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw ($b);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
sub import
|
|
Packit Service |
e1cd52 |
{
|
|
Packit Service |
e1cd52 |
$A::b = 1; # not a very useful import method
|
|
Packit Service |
e1cd52 |
}
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
and you want to Export symbol $A::b back to the module that called
|
|
Packit Service |
e1cd52 |
package A. Since Exporter relies on the import method to work, via
|
|
Packit Service |
e1cd52 |
inheritance, as it stands Exporter::import() will never get called.
|
|
Packit Service |
e1cd52 |
Instead, say the following:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
package A;
|
|
Packit Service |
e1cd52 |
@ISA = qw(Exporter);
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw ($b);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
sub import
|
|
Packit Service |
e1cd52 |
{
|
|
Packit Service |
e1cd52 |
$A::b = 1;
|
|
Packit Service |
e1cd52 |
A->export_to_level(1, @_);
|
|
Packit Service |
e1cd52 |
}
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
This will export the symbols one level 'above' the current package - ie:
|
|
Packit Service |
e1cd52 |
to the program or module that used package A.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Note: Be careful not to modify @_ at all before you call export_to_level
|
|
Packit Service |
e1cd52 |
- or people using your package will get very unexplained results!
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Exporting without inheriting from Exporter
|
|
Packit Service |
e1cd52 |
By including Exporter in your @ISA you inherit an Exporter's import()
|
|
Packit Service |
e1cd52 |
method but you also inherit several other helper methods which you
|
|
Packit Service |
e1cd52 |
probably don't want. To avoid this you can do
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
package YourModule;
|
|
Packit Service |
e1cd52 |
use Exporter qw( import );
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
which will export Exporter's own import() method into YourModule.
|
|
Packit Service |
e1cd52 |
Everything will work as before but you won't need to include Exporter in
|
|
Packit Service |
e1cd52 |
@YourModule::ISA.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Note: This feature was introduced in version 5.57 of Exporter, released
|
|
Packit Service |
e1cd52 |
with perl 5.8.3.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Module Version Checking
|
|
Packit Service |
e1cd52 |
The Exporter module will convert an attempt to import a number from a
|
|
Packit Service |
e1cd52 |
module into a call to "$module_name->require_version($value)". This can
|
|
Packit Service |
e1cd52 |
be used to validate that the version of the module being used is greater
|
|
Packit Service |
e1cd52 |
than or equal to the required version.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
The Exporter module supplies a default "require_version" method which
|
|
Packit Service |
e1cd52 |
checks the value of $VERSION in the exporting module.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Since the default "require_version" method treats the $VERSION number as
|
|
Packit Service |
e1cd52 |
a simple numeric value it will regard version 1.10 as lower than 1.9.
|
|
Packit Service |
e1cd52 |
For this reason it is strongly recommended that you use numbers with at
|
|
Packit Service |
e1cd52 |
least two decimal places, e.g., 1.09.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Managing Unknown Symbols
|
|
Packit Service |
e1cd52 |
In some situations you may want to prevent certain symbols from being
|
|
Packit Service |
e1cd52 |
exported. Typically this applies to extensions which have functions or
|
|
Packit Service |
e1cd52 |
constants that may not exist on some systems.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
The names of any symbols that cannot be exported should be listed in the
|
|
Packit Service |
e1cd52 |
@EXPORT_FAIL array.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
If a module attempts to import any of these symbols the Exporter will
|
|
Packit Service |
e1cd52 |
give the module an opportunity to handle the situation before generating
|
|
Packit Service |
e1cd52 |
an error. The Exporter will call an export_fail method with a list of
|
|
Packit Service |
e1cd52 |
the failed symbols:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
@failed_symbols = $module_name->export_fail(@failed_symbols);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
If the "export_fail" method returns an empty list then no error is
|
|
Packit Service |
e1cd52 |
recorded and all the requested symbols are exported. If the returned
|
|
Packit Service |
e1cd52 |
list is not empty then an error is generated for each symbol and the
|
|
Packit Service |
e1cd52 |
export fails. The Exporter provides a default "export_fail" method which
|
|
Packit Service |
e1cd52 |
simply returns the list unchanged.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Uses for the "export_fail" method include giving better error messages
|
|
Packit Service |
e1cd52 |
for some symbols and performing lazy architectural checks (put more
|
|
Packit Service |
e1cd52 |
symbols into @EXPORT_FAIL by default and then take them out if someone
|
|
Packit Service |
e1cd52 |
actually tries to use them and an expensive check shows that they are
|
|
Packit Service |
e1cd52 |
usable on that platform).
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Tag Handling Utility Functions
|
|
Packit Service |
e1cd52 |
Since the symbols listed within %EXPORT_TAGS must also appear in either
|
|
Packit Service |
e1cd52 |
@EXPORT or @EXPORT_OK, two utility functions are provided which allow
|
|
Packit Service |
e1cd52 |
you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
%EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
|
|
Packit Service |
e1cd52 |
Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Any names which are not tags are added to @EXPORT or @EXPORT_OK
|
|
Packit Service |
e1cd52 |
unchanged but will trigger a warning (with "-w") to avoid misspelt tags
|
|
Packit Service |
e1cd52 |
names being silently added to @EXPORT or @EXPORT_OK. Future versions may
|
|
Packit Service |
e1cd52 |
make this a fatal error.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Generating combined tags
|
|
Packit Service |
e1cd52 |
If several symbol categories exist in %EXPORT_TAGS, it's usually useful
|
|
Packit Service |
e1cd52 |
to create the utility ":all" to simplify "use" statements.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
The simplest way to do this is:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
%EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
# add all the other ":class" tags to the ":all" class,
|
|
Packit Service |
e1cd52 |
# deleting duplicates
|
|
Packit Service |
e1cd52 |
{
|
|
Packit Service |
e1cd52 |
my %seen;
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
push @{$EXPORT_TAGS{all}},
|
|
Packit Service |
e1cd52 |
grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
|
|
Packit Service |
e1cd52 |
}
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
CGI.pm creates an ":all" tag which contains some (but not really all) of
|
|
Packit Service |
e1cd52 |
its categories. That could be done with one small change:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
# add some of the other ":class" tags to the ":all" class,
|
|
Packit Service |
e1cd52 |
# deleting duplicates
|
|
Packit Service |
e1cd52 |
{
|
|
Packit Service |
e1cd52 |
my %seen;
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
push @{$EXPORT_TAGS{all}},
|
|
Packit Service |
e1cd52 |
grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
|
|
Packit Service |
e1cd52 |
foreach qw/html2 html3 netscape form cgi internal/;
|
|
Packit Service |
e1cd52 |
}
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
"AUTOLOAD"ed Constants
|
|
Packit Service |
e1cd52 |
Many modules make use of "AUTOLOAD"ing for constant subroutines to avoid
|
|
Packit Service |
e1cd52 |
having to compile and waste memory on rarely used values (see perlsub
|
|
Packit Service |
e1cd52 |
for details on constant subroutines). Calls to such constant subroutines
|
|
Packit Service |
e1cd52 |
are not optimized away at compile time because they can't be checked at
|
|
Packit Service |
e1cd52 |
compile time for constancy.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Even if a prototype is available at compile time, the body of the
|
|
Packit Service |
e1cd52 |
subroutine is not (it hasn't been "AUTOLOAD"ed yet). perl needs to
|
|
Packit Service |
e1cd52 |
examine both the "()" prototype and the body of a subroutine at compile
|
|
Packit Service |
e1cd52 |
time to detect that it can safely replace calls to that subroutine with
|
|
Packit Service |
e1cd52 |
the constant value.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
A workaround for this is to call the constants once in a "BEGIN" block:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
package My ;
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use Socket ;
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
|
|
Packit Service |
e1cd52 |
BEGIN { SO_LINGER }
|
|
Packit Service |
e1cd52 |
foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
This forces the "AUTOLOAD" for "SO_LINGER" to take place before
|
|
Packit Service |
e1cd52 |
SO_LINGER is encountered later in "My" package.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
If you are writing a package that "AUTOLOAD"s, consider forcing an
|
|
Packit Service |
e1cd52 |
"AUTOLOAD" for any constants explicitly imported by other packages or
|
|
Packit Service |
e1cd52 |
which are usually used when your package is "use"d.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Good Practices
|
|
Packit Service |
e1cd52 |
Declaring @EXPORT_OK and Friends
|
|
Packit Service |
e1cd52 |
When using "Exporter" with the standard "strict" and "warnings" pragmas,
|
|
Packit Service |
e1cd52 |
the "our" keyword is needed to declare the package variables @EXPORT_OK,
|
|
Packit Service |
e1cd52 |
@EXPORT, @ISA, etc.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
our @ISA = qw(Exporter);
|
|
Packit Service |
e1cd52 |
our @EXPORT_OK = qw(munge frobnicate);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
If backward compatibility for Perls under 5.6 is important, one must
|
|
Packit Service |
e1cd52 |
write instead a "use vars" statement.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use vars qw(@ISA @EXPORT_OK);
|
|
Packit Service |
e1cd52 |
@ISA = qw(Exporter);
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw(munge frobnicate);
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Playing Safe
|
|
Packit Service |
e1cd52 |
There are some caveats with the use of runtime statements like "require
|
|
Packit Service |
e1cd52 |
Exporter" and the assignment to package variables, which can very subtle
|
|
Packit Service |
e1cd52 |
for the unaware programmer. This may happen for instance with mutually
|
|
Packit Service |
e1cd52 |
recursive modules, which are affected by the time the relevant
|
|
Packit Service |
e1cd52 |
constructions are executed.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
The ideal (but a bit ugly) way to never have to think about that is to
|
|
Packit Service |
e1cd52 |
use "BEGIN" blocks. So the first part of the "SYNOPSIS" code could be
|
|
Packit Service |
e1cd52 |
rewritten as:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
package YourModule;
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use strict;
|
|
Packit Service |
e1cd52 |
use warnings;
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
our (@ISA, @EXPORT_OK);
|
|
Packit Service |
e1cd52 |
BEGIN {
|
|
Packit Service |
e1cd52 |
require Exporter;
|
|
Packit Service |
e1cd52 |
@ISA = qw(Exporter);
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw(munge frobnicate); # symbols to export on request
|
|
Packit Service |
e1cd52 |
}
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
The "BEGIN" will assure that the loading of Exporter.pm and the
|
|
Packit Service |
e1cd52 |
assignments to @ISA and @EXPORT_OK happen immediately, leaving no room
|
|
Packit Service |
e1cd52 |
for something to get awry or just plain wrong.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
With respect to loading "Exporter" and inheriting, there are
|
|
Packit Service |
e1cd52 |
alternatives with the use of modules like "base" and "parent".
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use base qw( Exporter );
|
|
Packit Service |
e1cd52 |
# or
|
|
Packit Service |
e1cd52 |
use parent qw( Exporter );
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Any of these statements are nice replacements for "BEGIN { require
|
|
Packit Service |
e1cd52 |
Exporter; @ISA = qw(Exporter); }" with the same compile-time effect. The
|
|
Packit Service |
e1cd52 |
basic difference is that "base" code interacts with declared "fields"
|
|
Packit Service |
e1cd52 |
while "parent" is a streamlined version of the older "base" code to just
|
|
Packit Service |
e1cd52 |
establish the IS-A relationship.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
For more details, see the documentation and code of base and parent.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Another thorough remedy to that runtime vs. compile-time trap is to use
|
|
Packit Service |
e1cd52 |
Exporter::Easy, which is a wrapper of Exporter that allows all
|
|
Packit Service |
e1cd52 |
boilerplate code at a single gulp in the use statement.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
use Exporter::Easy (
|
|
Packit Service |
e1cd52 |
OK => [ qw(munge frobnicate) ],
|
|
Packit Service |
e1cd52 |
);
|
|
Packit Service |
e1cd52 |
# @ISA setup is automatic
|
|
Packit Service |
e1cd52 |
# all assignments happen at compile time
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
What not to Export
|
|
Packit Service |
e1cd52 |
You have been warned already in "Selecting What To Export" to not
|
|
Packit Service |
e1cd52 |
export:
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
* method names (because you don't need to and that's likely to not do
|
|
Packit Service |
e1cd52 |
what you want),
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
* anything by default (because you don't want to surprise your
|
|
Packit Service |
e1cd52 |
users... badly)
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
* anything you don't need to (because less is more)
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
There's one more item to add to this list. Do not export variable names.
|
|
Packit Service |
e1cd52 |
Just because "Exporter" lets you do that, it does not mean you should.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
@EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Exporting variables is not a good idea. They can change under the hood,
|
|
Packit Service |
e1cd52 |
provoking horrible effects at-a-distance, that are too hard to track and
|
|
Packit Service |
e1cd52 |
to fix. Trust me: they are not worth it.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
To provide the capability to set/get class-wide settings, it is best
|
|
Packit Service |
e1cd52 |
instead to provide accessors as subroutines or class methods instead.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
SEE ALSO
|
|
Packit Service |
e1cd52 |
"Exporter" is definitely not the only module with symbol exporter
|
|
Packit Service |
e1cd52 |
capabilities. At CPAN, you may find a bunch of them. Some are lighter.
|
|
Packit Service |
e1cd52 |
Some provide improved APIs and features. Peek the one that fits your
|
|
Packit Service |
e1cd52 |
needs. The following is a sample list of such modules.
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
Exporter::Easy
|
|
Packit Service |
e1cd52 |
Exporter::Lite
|
|
Packit Service |
e1cd52 |
Exporter::Renaming
|
|
Packit Service |
e1cd52 |
Exporter::Tidy
|
|
Packit Service |
e1cd52 |
Sub::Exporter / Sub::Installer
|
|
Packit Service |
e1cd52 |
Perl6::Export / Perl6::Export::Attrs
|
|
Packit Service |
e1cd52 |
|
|
Packit Service |
e1cd52 |
LICENSE
|
|
Packit Service |
e1cd52 |
This library is free software. You can redistribute it and/or modify it
|
|
Packit Service |
e1cd52 |
under the same terms as Perl itself.
|
|
Packit Service |
e1cd52 |
|