# ABSTRACT: useful, demonstrative, or stupid Sub::Exporter tricks
# PODNAME: Sub::Exporter::Cookbook
__END__
=pod
=head1 NAME
Sub::Exporter::Cookbook - useful, demonstrative, or stupid Sub::Exporter tricks
=head1 VERSION
version 0.987
=head1 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
L and L. 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).
=head1 THE RECIPES
=head2 Exporting Methods as Routines
With Exporter.pm, exporting methods is a non-starter. Sub::Exporter makes it
simple. By using the C utility provided in
L, a method can be exported with the invocant built in.
package Object::Strenuous;
use Sub::Exporter::Util 'curry_method';
use Sub::Exporter -setup => {
exports => [ objection => curry_method('new') ],
};
With this configuration, the importing code may contain:
my $obj = objection("irrelevant");
...and this will be equivalent to:
my $obj = Object::Strenuous->new("irrelevant");
The built-in invocant is determined by the invocant for the C method.
That means that if we were to subclass Object::Strenuous as follows:
package Object::Strenuous::Repeated;
@ISA = 'Object::Strenuous';
...then importing C from the subclass would build-in that subclass.
Finally, since the invocant can be an object, you can write something like
this:
package Cypher;
use Sub::Exporter::Util 'curry_method';
use Sub::Exporter -setup => {
exports => [ encypher => curry_method ],
};
with the expectation that C will be called on an instantiated Cypher
object:
BEGIN {
my $cypher = Cypher->new( ... );
$cypher->import('encypher');
}
Now there is a globally-available C routine which calls the encypher
method on an otherwise unavailable Cypher object.
=head2 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:
package Mixin::DumpObj;
use Data::Dumper;
use Sub::Exporter -setup => {
exports => [ qw(dump) ]
};
sub dump {
my ($self) = @_;
return Dumper($self);
}
When writing your own object class, you can then import C to be used as a
method, called like so:
$object->dump;
By assuming that the importing class will provide a certain interface, a
method-exporting module can be used as a simple plugin:
package Number::Plugin::Upto;
use Sub::Exporter -setup => {
into => 'Number',
exports => [ qw(upto) ],
groups => [ default => [ qw(upto) ] ],
};
sub upto {
my ($self) = @_;
return 1 .. abs($self->as_integer);
}
The C line in the configuration says that this plugin will export, by
default, into the Number package, not into the C