/usr/share/perl5/Sub/Exporter/Cookbook.pod is in libsub-exporter-perl 0.984-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 | # 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.984
=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<Sub::Exporter::Tutorial> and L<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).
=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<curry_method> utility provided in
L<Sub::Exporter::Util>, 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<import> method.
That means that if we were to subclass Object::Strenuous as follows:
package Object::Strenuous::Repeated;
@ISA = 'Object::Strenuous';
...then importing C<objection> 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<import> will be called on an instantiated Cypher
object:
BEGIN {
my $cypher = Cypher->new( ... );
$cypher->import('encypher');
}
Now there is a globally-available C<encypher> 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<dump> 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<into> line in the configuration says that this plugin will export, by
default, into the Number package, not into the C<use>-ing package. It can be
exported anyway, though, and will work as long as the destination provides an
C<as_integer> method like the one it expects. To import it to a different
destination, one can just write:
use Number::Plugin::Upto { into => 'Quantity' };
=head2 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:
package Data::Analyzer;
use Sub::Exporter -setup => {
exports => [ analyze => \'_generate_analyzer' ],
};
sub _generate_analyzer {
my ($mixin, $name, $arg, $col) = @_;
return sub {
my ($self) = @_;
my $values = [ $self->values ];
my $analyzer = $mixin->new($values);
$analyzer->perform_analysis;
$analyzer->aggregate_results;
return $analyzer->summary;
};
}
If imported by any package providing a C<values> method, this plugin will
provide a single C<analyze> method that acts as a simple interface to a more
complex set of behaviors.
Even more importantly, because the C<$mixin> value will be the invocant on
which the C<import> was actually called, one can subclass C<Data::Analyzer> 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.
=head2 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.
package Important::Constants;
use Sub::Exporter -setup => {
collectors => [ constants => \'_set_constants' ],
};
sub _set_constants {
my ($class, $value, $data) = @_;
Package::Generator->assign_symbols(
$data->{into},
[
MEANING_OF_LIFE => \42,
ONE_TRUE_BASE => \13,
FACTORS => [ 6, 9 ],
],
);
return 1;
}
Then, someone can write:
use Important::Constants 'constants';
print "The factors @FACTORS produce $MEANING_OF_LIFE in $ONE_TRUE_BASE.";
(The constants must be exported via a collector, because they are effectively
altering the importing class in a way other than installing subroutines.)
=head2 Altering the Importer's @ISA
It's trivial to make a collector that changes the inheritance of an importing
package:
use Sub::Exporter -setup => {
collectors => { -base => \'_make_base' },
};
sub _make_base {
my ($class, $value, $data) = @_;
my $target = $data->{into};
push @{"$target\::ISA"}, $class;
}
Then, the user of your class can write:
use Some::Class -base;
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;
package Framework::Util;
use Sub::Exporter -setup => {
exports => [ qw(log global_config) ],
groups => [ _plugin => [ qw(log global_config) ]
collectors => { '-plugin' => \'_become_plugin' },
};
sub _become_plugin {
my ($class, $value, $data) = @_;
my $target = $data->{into};
push @{"$target\::ISA"}, $class->plugin_base_class;
push @{ $data->{import_args} }, '-_plugin';
}
Now, you can write a plugin like this:
package Framework::Plugin::AirFreshener;
use Framework::Util -plugin;
=head2 Eating Exporter.pm's Brain
You probably shouldn't actually do this in production. It's offered more as a
demonstration than a suggestion.
sub exporter_upgrade {
my ($pkg) = @_;
my $new_pkg = "$pkg\::UsingSubExporter";
return $new_pkg if $new_pkg->isa($pkg);
Sub::Exporter::setup_exporter({
as => 'import',
into => $new_pkg,
exports => [ @{"$pkg\::EXPORT_OK"} ],
groups => {
%{{"$pkg\::EXPORT_TAG"},
default => [ @{"$pkg\::EXPORTS"} ],
},
});
@{"$new_pkg\::ISA"} = $class;
return $new_pkg;
}
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
C<import> routine. This lets you write:
BEGIN {
require Toolkit;
exporter_upgrade('Toolkit')->import(exported_sub => { -as => 'foo' })
}
If you're feeling particularly naughty, this routine could have been declared
in the UNIVERSAL package, meaning you could write:
BEGIN {
require Toolkit;
Toolkit->exporter_upgrade->import(exported_sub => { -as => 'foo' })
}
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 C<can> to find the routine being
exported, the new package may be subclassed and some of its exports replaced.
=head1 AUTHOR
Ricardo Signes <rjbs@cpan.org>
=head1 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.
=cut
|