cpan exporter modules for perl 5
DESCRIPTION
A review of CPAN exporter modules for Perl 5, when and where you should use them, and things to be aware of.TRANSCRIPT
Exporter modules
Neil Bowers
NEILB
More than you ever wanted to know about Perl 5's
44+ modules
on CPAN!
Function library modules
use Maths qw/ min /;
$min = min(@values);
package Maths;
use parent 'Exporter';
sub min { ... }
package Exporter;
...
sub import {...}
You're writing
one of these
Exporter.pm
package Maths;
use parent 'Exporter';
our @EXPORT = qw/ min max average /;
our @EXPORT_OK = qw/ sin cos tan /;
our %EXPORT_TAGS = (
list => [qw/ min max average /],
trig => [qw/ sin cos tan /],
);
use Maths qw/ :list /;
$minimum = min(@numbers);
My model for function libraries
• Only functions exported• Don't export variables
• No functions exported by default• You have to ask for ask for everything you want
• No (unexpected) namespace pollution
• Documents where functions in your code come from (but: tags)
Function::Exporter
What else might you want?
• Default exports
• Exporting variables
• Different (better?) notation for specifying what and how to export
• Tags
• Constants (creating module which define & export them)
• Import control
• Anonymous subs (on import & export)
• Generators (aka currying)
• Combined class & function module
• Create a mashup module (exporting things from other modules)
Default exports
Specifying what users of your module get when they
don't explicitly list anything for import
Exporter::Auto
• Doesn't export functions that start with an underscore
• Namespace pollution
• All public functions in module exported by default
Simpler than Exporter.pm
When you want more than a completely minimal
exporter, but not as much as Exporter
Exporter::Lite
• Adds the import() function into your namespace
• No support for tags, or other features beyond the above
• A lightweight subset of the classic Exporter functionality
Exporter::Easy
• Basic usage is clean and simple
• Has nice way to build up tags ...
Exporter::Shiny
• Exporter::Shiny is syntactic sugar around Exporter::Tiny
• Simple interface for optional exports:
Tags
Defining named groups of the symbols available for
import
Exporter::Easy
• Good if you've got a lot of functions / groups
• That's a lot of punctuation though ...
Exporter::Easiest
Exporting variables
Don't export variables!
• http://c2.com/cgi/wiki?GlobalVariablesAreBad
• http://programmers.stackexchange.com/questions/14810
8/why-is-global-state-so-evil
• and
• and
• and
Constants
Making it easy to create modules that define and export
constants, for example ones that are system-wide
Exporter + constant
Panda::Export
• Function::Exporter + constants, in XS
Constant::Exporter
• See also• Const::Exporter – exports immutable variables too (deps++)
• Exporter::Constants – support module for Exporter.pm
also supportsdefining of tags
Constant::Export::Lazy
• Where the value of a constant might take a long time to
compute, look up in a database, etc
Import control
More flexible ways for your module's users to specify
which symbols to import, and as what
Exporter
• The import list is basically a query, read left to right
• You can use a regexp to match what to import
• And prefix with ! to negate a clause
Exporter::Tiny
Anonymous functions
Exporting from, and import to, function references
Exporter::AutoClean
• Export anonymous subs
• People can import, but not dip into your namespace
Exporter::Tiny
• Import into a scalar reference
• Doesn't pollute your namespace• For example, if you're making all your public functions exportable
Alternate notations
Other ways to specify what bits of your module to export
Attribute::Exporter
• Good: export status obvious when you look at each function
• Bad: verbose / noisy
• See also: Exporter::Simple, Perl6::Export::Attrs
• Attributes used to annotate each function with export
rules
Exporter::NoWork
Export::Above
• Export config spread through file, but not next to each func
Exporter::Declare
• Declarative syntax, Moose stylee
Exporter::Declare
• Or you can put the export status by each sub:
• Or you can export an anonymous sub:
Exporter::Declare - tags
• You can define tags up front:
• Or specify the tagging with each sub:
Exporter::Declare
• You can rename things when you import them:
• And a bunch more features. Too many perhaps?
• Like Moose/Moo, potential for a lightweight subset?
Exporter::Declare::Magic
• Syntactic sugar for Exporter::Declare
• But: depends on 18 CPAN distributions
Hybrid modules
Creating modules that can be used either as a class, or
as a function library
Class::Exporter
Making mashup modules
Create a module that exports things from multiple other
modules
Exporter::Cluster
• Create module which export things from other modules
Import::Base
Generators, or currying
Fixing arguments to functions at import time
Sub::Exporter
• Basic usage – give list of subs for optional export
• Defines a :all/-all tag
• You can rename on import
• The real power is in export generators though...
Sub::Exporter
Using a Sub::Exporter module
• When importing, you can configure what sub you want
• Adds an overhead to all sub calls
• I've recently hit a case where this might be the right
solution
• How many users of the module are using generators...?
SEE ALSO 1/2
• Badger::Exporter – Exporter + constants + hooks ++
• Sub::Exporter::Progressive – same interface as
Sub::Exporter, which is only loaded if advanced features
are used, otherwise uses Exporter
• Exporter::LexicalVars – create a module that exports
lexical variables (!)
• Exporter::Proxy – like my Function::Exporter, but exports
the whole typeglob and adds exports() for reflection
SEE ALSO 2/2
• Exporter::Renaming – monkey-patches Exporter to
provide a renaming capability
• Export::Lexical, Exporter::Lexical – subs imported into
lexical scope
• Sub::Exporter::Simple – syntactic sugar for basic
exporting with Sub::Exporter (just use Exporter[::Tiny])
• Sub::Import – Sub::Exporter-like semantics, importing
from any module
Dependencies: the good
Dependencies: the bad & the ugly
Reverse dependencies
Observations
• Documentation of exporter modules is often sub-optimal• Particularly for people writing their first exporting module
• Very few modules make use of advanced features
• Very few modules document their import features• If your module provides advanced import features, you need to let
your users know
• There's only one exporter module shipped with Perl• There are gaps above and below it
Conclusion
• Exporter::Tiny is a good default for most users• Or Exporter if you don't want the non-core dependency
• Exporter::Easy if you've got rich tag needs• Would be nice if Exporter::Tiny supported nested tags
• Exporting constants?• Panda::Export for &CONSTANTS• Const::Fast + Exporter::Tiny for immutable variables
• Misc others:• Import::Base for mashup modules• Sub::Exporter for generators• Export::AutoClean / Exporter::Tiny for namespace OCD types
• Yoda says:• variables export you should not• OO or functions: pick one you should