Codex

Sub::Exporter::Cookbook

Section: User Contributed Perl Documentation (3pm)

Updated: 2013-06-14

Index?action=index Return to Main Contents


NAME

Sub::Exporter::Cookbook - useful, demonstrative, or stupid Sub::Exporter tricks

VERSION

version 0.986

OVERVIEW

Sub::Exporter is a fairly simple tool, and can be used to achieve some very simple goals. Its basic behaviors and their basic application (that is, ``traditional'' exporting of routines) are described in Sub::Exporter::Tutorial and Sub::Exporter. This document presents applications that may not be immediately obvious, or that can demonstrate how certain features can be put to use (for good or evil).

THE RECIPES

Exporting Methods as Routines

With Exporter.pm, exporting methods is a non-starter. Sub::Exporter makes it simple. By using the utility provided in Sub::Exporter::Util, a method can be exported with the invocant built in.

With this configuration, the importing code may contain:

...and this will be equivalent to:

The built-in invocant is determined by the invocant for the method. That means that if we were to subclass Object::Strenuous as follows:
...then importing from the subclass would build-in that subclass.

Finally, since the invocant can be an object, you can write something like this:

with the expectation that will be called on an instantiated Cypher object:
Now there is a globally-available routine which calls the encypher method on an otherwise unavailable Cypher object.

Exporting Methods as Methods

While exporting modules usually export subroutines to be called as subroutines, it's easy to use Sub::Exporter to export subroutines meant to be called as methods on the importing package or its objects.

Here's a trivial (and naive) example:

When writing your own object class, you can then import to be used as a method, called like so:

By assuming that the importing class will provide a certain interface, a method-exporting module can be used as a simple plugin:

The line in the configuration says that this plugin will export, by default, into the Number package, not into the -ing package. It can be exported anyway, though, and will work as long as the destination provides an method like the one it expects. To import it to a different destination, one can just write:

Mixing-in Complex External Behavior

When exporting methods to be used as methods (see above), one very powerful option is to export methods that are generated routines that maintain an enclosed reference to the exporting module. This allows a user to import a single method which is implemented in terms of a complete, well-structured package.

Here is a very small example:

If imported by any package providing a method, this plugin will provide a single method that acts as a simple interface to a more complex set of behaviors.
Even more importantly, because the value will be the invocant on which the was actually called, one can subclass and replace only individual pieces of the complex behavior, making it easy to write complex, subclassable toolkits with simple single points of entry for external interfaces.

Exporting Constants

While Sub::Exporter isn't in the constant-exporting business, it's easy to export constants by using one of its sister modules, Package::Generator.

Then, someone can write:

(The constants must be exported via a collector, because they are effectively altering the importing class in a way other than installing subroutines.)

Altering the Importer's @ISA

It's trivial to make a collector that changes the inheritance of an importing package:

Then, the user of your class can write:

and become a subclass. This can be quite useful in building, for example, a module that helps build plugins. We may want a few utilities imported, but we also want to inherit behavior from some base plugin class;

Now, you can write a plugin like this:

Eating Exporter.pm's Brain

You probably shouldn't actually do this in production. It's offered more as a demonstration than a suggestion.

This routine, given the name of an existing package configured to use Exporter.pm, returns the name of a new package with a Sub::Exporter-powered routine. This lets you import into the current package with the name by writing:

If you're feeling particularly naughty, this routine could have been declared in the UNIVERSAL package, meaning you could write:

The new package will have all the same exporter configuration as the original, but will support export and group renaming, including exporting into scalar references. Further, since Sub::Exporter uses to find the routine being exported, the new package may be subclassed and some of its exports replaced.

AUTHOR

Ricardo Signes <[email protected]>

COPYRIGHT AND LICENSE

This software is copyright (c) 2007 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.


Index

NAME

VERSION

OVERVIEW

THE RECIPES

Exporting Methods as Routines

Exporting Methods as Methods

Mixing-in Complex External Behavior

Exporting Constants

Altering the Importer's @ISA

Eating Exporter.pm's Brain

AUTHOR

COPYRIGHT AND LICENSE