Exporter modules

Neil Bowers

NEILB

neil@bowers.com

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