1Exporter::Tiny::Manual:U:sEexrpoCrotnitnrgi(b3u)ted PerlExDpoocrutmeern:t:aTtiinoyn::Manual::Exporting(3)
2
6 Exporter::Tiny::Manual::Exporting - creating an exporter using
7 Exporter::Tiny
8
10 Read Exporter::Tiny::Manual::QuickStart first!
11
13 Simple configuration works the same as Exporter; inherit from
14 Exporter::Tiny, and use the @EXPORT, @EXPORT_OK, and %EXPORT_TAGS
15 package variables to list subs to export.
16 Unlike Exporter, Exporter::Tiny performs most of its internal duties
18 (including resolution of tag names to sub names, resolution of sub
19 names to coderefs, and installation of coderefs into the target
20 package) as method calls, which means that your module (which is a
21 subclass of Exporter::Tiny) can override them to provide interesting
22 behaviour.
23 Advanced Tag Stuff
25 You can define tags using other tags:
26 use Exporter::Shiny qw(
28 black white red green blue cyan magenta yellow
29 );
30 our %EXPORT_TAGS = (
32 rgb => [qw( red green blue )],
33 cym => [qw( cyan magenta yellow )],
34 cymk => [qw( black :cym )],
35 monochrome => [qw( black white )],
36 all => [qw( :rgb :cymk :monochrome )],
37 );
38 CAVEAT: If you create a cycle in the tags, this could put
40 Exporter::Tiny into an infinite loop expanding the tags. Don't do that.
41 More on Generators
43 Exporter::Tiny has always allowed exported subs to be generated (like
44 Sub::Exporter), but until version 0.025 did not have an especially nice
45 API for it.
46 Now, it's easy. If you want to generate a sub "foo" to export, list it
48 in @EXPORT or @EXPORT_OK as usual, and then simply give your exporter
49 module a class method called "_generate_foo".
50 push @EXPORT_OK, 'foo';
52 sub _generate_foo {
54 my $class = shift;
55 my ($name, $args, $globals) = @_;
56 return sub {
58 ...;
59 }
60 }
61 We showed how to do that in Exporter::Tiny::Manual::QuickStart, but one
63 thing we didn't show was that $globals gets passed in there. This is
64 the global options hash, as described in
65 Exporter::Tiny::Manual::Importing. It can often be useful. In
66 particular it will tell you what package the generated sub is destined
67 to be installed into.
68 To generate non-code symbols, name your generators like this:
70 sub _generateScalar_Foo { ... } # generate a symbol $Foo
72 sub _generateArray_Bar { ... } # generate a symbol @Bar
73 sub _generateHash_Baz { ... } # generate a symbol %Baz
74 You can also generate tags:
76 my %constants;
78 BEGIN {
79 %constants = (FOO => 1, BAR => 2);
80 }
81 use constant \%constants;
82 $EXPORT_TAGS{constants} = sub {
84 my $class = shift;
85 my ($name, $args, $globals) = @_;
86 return keys(%constants);
88 };
89 Hooks
91 Sometimes as well as exporting stuff, you want to do some setup or
92 something.
93 You can define a couple of class methods in your package, and they'll
95 get called at the appropriate time:
96 package MyUtils;
98 ...;
100 sub _exporter_validate_opts {
102 my $class = shift;
103 my ($globals) = @_;
104 ...; # do stuff here
106 $class->SUPER::_exporter_validate_opts(@_);
108 }
109 sub _exporter_validate_unimport_opts {
111 my $class = shift;
112 my ($globals) = @_;
113 ...; # do stuff here
115 $class->SUPER::_exporter_validate_unimport_opts(@_);
117 }
118 The $globals variable is that famous global options hash. In
120 particular, "$globals->{into}" is useful because it tells you what
121 package has imported you.
122 As you might have guessed, these methods were originally intended to
124 validate the global options hash, but can be used to perform any
125 general duties before the real exporting work is done.
126 Overriding Internals
128 An important difference between Exporter and Exporter::Tiny is that the
129 latter calls all its internal functions as class methods. This means
130 that your subclass can override them to alter their behaviour.
131 The following methods are available to be overridden. Despite being
133 named with a leading underscore, they are considered public methods.
134 (The underscore is there to avoid accidentally colliding with any of
135 your own function names.)
136 "_exporter_validate_opts($globals)"
138 Documented above.
139 "_exporter_validate_unimport_opts($globals)"
141 Documented above.
142 "_exporter_merge_opts($tag_opts, $globals, @exports)"
144 Called to merge options which have been provided for a tag into the
145 options provided for the exports that the tag expanded to.
146 "_exporter_expand_tag($name, $args, $globals)"
148 This method is called to expand an import tag (e.g. ":constants").
149 It is passed the tag name (minus the leading ":"), an optional
150 hashref of options (like "{ -prefix => "foo_" }"), and the global
151 options hashref.
152 It is expected to return a list of ($name, $args) arrayref pairs.
154 These names can be sub names to export, or further tag names (which
155 must have their ":"). If returning tag names, be careful to avoid
156 creating a tag expansion loop!
157 The default implementation uses %EXPORT_TAGS to expand tags, and
159 provides fallbacks for the ":default" and ":all" tags.
160 "_exporter_expand_regexp($regexp, $args, $globals)"
162 Like "_exporter_expand_regexp", but given a regexp-like string
163 instead of a tag name.
164 The default implementation greps through @EXPORT_OK for imports,
166 and the list of already-imported functions for exports.
167 "_exporter_expand_sub($name, $args, $globals)"
169 This method is called to translate a sub name to a hash of name =>
170 coderef pairs for exporting to the caller. In general, this would
171 just be a hash with one key and one value, but, for example,
172 Type::Library overrides this method so that "+Foo" gets expanded
173 to:
174 (
176 Foo => sub { $type },
177 is_Foo => sub { $type->check(@_) },
178 to_Foo => sub { $type->assert_coerce(@_) },
179 assert_Foo => sub { $type->assert_return(@_) },
180 )
181 The default implementation checks that the name is allowed to be
183 exported (using the "_exporter_permitted_regexp" method), gets the
184 coderef using the generator if there is one (or by calling "can" on
185 your exporter otherwise) and calls "_exporter_fail" if it's unable
186 to generate or retrieve a coderef.
187 Despite the name, is also called for non-code symbols.
189 "_exporter_permitted_regexp($globals)"
191 This method is called to retrieve a regexp for validating the names
192 of exportable subs. If a sub doesn't match the regexp, then the
193 default implementation of "_exporter_expand_sub" will refuse to
194 export it. (Of course, you may override the default
195 "_exporter_expand_sub".)
196 The default implementation of this method assembles the regexp from
198 @EXPORT and @EXPORT_OK.
199 "_exporter_fail($name, $args, $globals)"
201 Called by "_exporter_expand_sub" if it can't find a coderef to
202 export.
203 The default implementation just throws an exception. But you could
205 emit a warning instead, or just ignore the failed export.
206 If you don't throw an exception then you should be aware that this
208 method is called in list context, and any list it returns will be
209 treated as an "_exporter_expand_sub"-style hash of names and
210 coderefs for export.
211 "_exporter_install_sub($name, $args, $globals, $coderef)"
213 This method actually installs the exported sub into its new
214 destination. Its return value is ignored.
215 The default implementation handles sub renaming (i.e. the "-as",
217 "-prefix" and "-suffix" functions. This method does a lot of stuff;
218 if you need to override it, it's probably a good idea to just pre-
219 process the arguments and then call the super method rather than
220 trying to handle all of it yourself.
221 Despite the name, is also called for non-code symbols.
223 "_exporter_uninstall_sub($name, $args, $globals)"
225 The opposite of "_exporter_install_sub".
226
228 Exporter::Shiny, Exporter::Tiny.
229
231 Toby Inkster <tobyink@cpan.org>.
232
234 This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
235 This is free software; you can redistribute it and/or modify it under
237 the same terms as the Perl 5 programming language system itself.
238
240 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
241 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
242 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
243perl v5.34.0 2021-07-2E2xporter::Tiny::Manual::Exporting(3)