1Sub::Exporter::CookbookU(s3e)r Contributed Perl DocumentaStuibo:n:Exporter::Cookbook(3)
2
6 Sub::Exporter::Cookbook - useful, demonstrative, or stupid
7 Sub::Exporter tricks
8
10 version 0.990
11
13 Sub::Exporter is a fairly simple tool, and can be used to achieve some
14 very simple goals. Its basic behaviors and their basic application
15 (that is, "traditional" exporting of routines) are described in
16 Sub::Exporter::Tutorial and Sub::Exporter. This document presents
17 applications that may not be immediately obvious, or that can
18 demonstrate how certain features can be put to use (for good or evil).
19
21 This library should run on perls released even a long time ago. It
22 should work on any version of perl released in the last five years.
23 Although it may work on older versions of perl, no guarantee is made
25 that the minimum required version will not be increased. The version
26 may be increased for any reason, and there is no promise that patches
27 will be accepted to lower the minimum required perl.
28
30 Exporting Methods as Routines
31 With Exporter.pm, exporting methods is a non-starter. Sub::Exporter
32 makes it simple. By using the "curry_method" utility provided in
33 Sub::Exporter::Util, a method can be exported with the invocant built
34 in.
35 package Object::Strenuous;
37 use Sub::Exporter::Util 'curry_method';
39 use Sub::Exporter -setup => {
40 exports => [ objection => curry_method('new') ],
41 };
42 With this configuration, the importing code may contain:
44 my $obj = objection("irrelevant");
46 ...and this will be equivalent to:
48 my $obj = Object::Strenuous->new("irrelevant");
50 The built-in invocant is determined by the invocant for the "import"
52 method. That means that if we were to subclass Object::Strenuous as
53 follows:
54 package Object::Strenuous::Repeated;
56 @ISA = 'Object::Strenuous';
57 ...then importing "objection" from the subclass would build-in that
59 subclass.
60 Finally, since the invocant can be an object, you can write something
62 like this:
63 package Cypher;
65 use Sub::Exporter::Util 'curry_method';
66 use Sub::Exporter -setup => {
67 exports => [ encypher => curry_method ],
68 };
69 with the expectation that "import" will be called on an instantiated
71 Cypher object:
72 BEGIN {
74 my $cypher = Cypher->new( ... );
75 $cypher->import('encypher');
76 }
77 Now there is a globally-available "encypher" routine which calls the
79 encypher method on an otherwise unavailable Cypher object.
80 Exporting Methods as Methods
82 While exporting modules usually export subroutines to be called as
83 subroutines, it's easy to use Sub::Exporter to export subroutines meant
84 to be called as methods on the importing package or its objects.
85 Here's a trivial (and naive) example:
87 package Mixin::DumpObj;
89 use Data::Dumper;
91 use Sub::Exporter -setup => {
93 exports => [ qw(dump) ]
94 };
95 sub dump {
97 my ($self) = @_;
98 return Dumper($self);
99 }
100 When writing your own object class, you can then import "dump" to be
102 used as a method, called like so:
103 $object->dump;
105 By assuming that the importing class will provide a certain interface,
107 a method-exporting module can be used as a simple plugin:
108 package Number::Plugin::Upto;
110 use Sub::Exporter -setup => {
111 into => 'Number',
112 exports => [ qw(upto) ],
113 groups => [ default => [ qw(upto) ] ],
114 };
115 sub upto {
117 my ($self) = @_;
118 return 1 .. abs($self->as_integer);
119 }
120 The "into" line in the configuration says that this plugin will export,
122 by default, into the Number package, not into the "use"-ing package.
123 It can be exported anyway, though, and will work as long as the
124 destination provides an "as_integer" method like the one it expects.
125 To import it to a different destination, one can just write:
126 use Number::Plugin::Upto { into => 'Quantity' };
128 Mixing-in Complex External Behavior
130 When exporting methods to be used as methods (see above), one very
131 powerful option is to export methods that are generated routines that
132 maintain an enclosed reference to the exporting module. This allows a
133 user to import a single method which is implemented in terms of a
134 complete, well-structured package.
135 Here is a very small example:
137 package Data::Analyzer;
139 use Sub::Exporter -setup => {
141 exports => [ analyze => \'_generate_analyzer' ],
142 };
143 sub _generate_analyzer {
145 my ($mixin, $name, $arg, $col) = @_;
146 return sub {
148 my ($self) = @_;
149 my $values = [ $self->values ];
151 my $analyzer = $mixin->new($values);
153 $analyzer->perform_analysis;
154 $analyzer->aggregate_results;
155 return $analyzer->summary;
157 };
158 }
159 If imported by any package providing a "values" method, this plugin
161 will provide a single "analyze" method that acts as a simple interface
162 to a more complex set of behaviors.
163 Even more importantly, because the $mixin value will be the invocant on
165 which the "import" was actually called, one can subclass
166 "Data::Analyzer" and replace only individual pieces of the complex
167 behavior, making it easy to write complex, subclassable toolkits with
168 simple single points of entry for external interfaces.
169 Exporting Constants
171 While Sub::Exporter isn't in the constant-exporting business, it's easy
172 to export constants by using one of its sister modules,
173 Package::Generator.
174 package Important::Constants;
176 use Sub::Exporter -setup => {
178 collectors => [ constants => \'_set_constants' ],
179 };
180 sub _set_constants {
182 my ($class, $value, $data) = @_;
183 Package::Generator->assign_symbols(
185 $data->{into},
186 [
187 MEANING_OF_LIFE => \42,
188 ONE_TRUE_BASE => \13,
189 FACTORS => [ 6, 9 ],
190 ],
191 );
192 return 1;
194 }
195 Then, someone can write:
197 use Important::Constants 'constants';
199 print "The factors @FACTORS produce $MEANING_OF_LIFE in $ONE_TRUE_BASE.";
201 (The constants must be exported via a collector, because they are
203 effectively altering the importing class in a way other than installing
204 subroutines.)
205 Altering the Importer's @ISA
207 It's trivial to make a collector that changes the inheritance of an
208 importing package:
209 use Sub::Exporter -setup => {
211 collectors => { -base => \'_make_base' },
212 };
213 sub _make_base {
215 my ($class, $value, $data) = @_;
216 my $target = $data->{into};
218 push @{"$target\::ISA"}, $class;
219 }
220 Then, the user of your class can write:
222 use Some::Class -base;
224 and become a subclass. This can be quite useful in building, for
226 example, a module that helps build plugins. We may want a few
227 utilities imported, but we also want to inherit behavior from some base
228 plugin class;
229 package Framework::Util;
231 use Sub::Exporter -setup => {
233 exports => [ qw(log global_config) ],
234 groups => [ _plugin => [ qw(log global_config) ]
235 collectors => { '-plugin' => \'_become_plugin' },
236 };
237 sub _become_plugin {
239 my ($class, $value, $data) = @_;
240 my $target = $data->{into};
242 push @{"$target\::ISA"}, $class->plugin_base_class;
243 push @{ $data->{import_args} }, '-_plugin';
245 }
246 Now, you can write a plugin like this:
248 package Framework::Plugin::AirFreshener;
250 use Framework::Util -plugin;
251 Eating Exporter.pm's Brain
253 You probably shouldn't actually do this in production. It's offered
254 more as a demonstration than a suggestion.
255 sub exporter_upgrade {
257 my ($pkg) = @_;
258 my $new_pkg = "$pkg\::UsingSubExporter";
259 return $new_pkg if $new_pkg->isa($pkg);
261 Sub::Exporter::setup_exporter({
263 as => 'import',
264 into => $new_pkg,
265 exports => [ @{"$pkg\::EXPORT_OK"} ],
266 groups => {
267 %{"$pkg\::EXPORT_TAG"},
268 default => [ @{"$pkg\::EXPORTS"} ],
269 },
270 });
271 @{"$new_pkg\::ISA"} = $pkg;
273 return $new_pkg;
274 }
275 This routine, given the name of an existing package configured to use
277 Exporter.pm, returns the name of a new package with a
278 Sub::Exporter-powered "import" routine. This lets you import
279 "Toolkit::exported_sub" into the current package with the name "foo" by
280 writing:
281 BEGIN {
283 require Toolkit;
284 exporter_upgrade('Toolkit')->import(exported_sub => { -as => 'foo' })
285 }
286 If you're feeling particularly naughty, this routine could have been
288 declared in the UNIVERSAL package, meaning you could write:
289 BEGIN {
291 require Toolkit;
292 Toolkit->exporter_upgrade->import(exported_sub => { -as => 'foo' })
293 }
294 The new package will have all the same exporter configuration as the
296 original, but will support export and group renaming, including
297 exporting into scalar references. Further, since Sub::Exporter uses
298 "can" to find the routine being exported, the new package may be
299 subclassed and some of its exports replaced.
300
302 Ricardo Signes <cpan@semiotic.systems>
303
305 This software is copyright (c) 2007 by Ricardo Signes.
306 This is free software; you can redistribute it and/or modify it under
308 the same terms as the Perl 5 programming language system itself.
309perl v5.38.0 2023-07-22 Sub::Exporter::Cookbook(3)