Exporter::Tiny::Manual::Exporting(3pm)

1Exporter::Tiny::Manual:U:sEexrpoCrotnitnrgi(b3u)ted PerlExDpoocrutmeern:t:aTtiinoyn::Manual::Exporting(3)
2
3
4

NAME

6       Exporter::Tiny::Manual::Exporting - creating an exporter using
7       Exporter::Tiny
8

SYNOPSIS

10       Read Exporter::Tiny::Manual::QuickStart first!
11

DESCRIPTION

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
17       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
24   Advanced Tag Stuff
25       You can define tags using other tags:
26
27          use Exporter::Shiny qw(
28             black white red green blue cyan magenta yellow
29          );
30
31          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
39       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
42   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
47       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
51          push @EXPORT_OK, 'foo';
52
53          sub _generate_foo {
54             my $class = shift;
55             my ($name, $args, $globals) = @_;
56
57             return sub {
58                ...;
59             }
60          }
61
62       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
69       To generate non-code symbols, name your generators like this:
70
71         sub _generateScalar_Foo { ... }  # generate a symbol $Foo
72         sub _generateArray_Bar  { ... }  # generate a symbol @Bar
73         sub _generateHash_Baz   { ... }  # generate a symbol %Baz
74
75       You can also generate tags:
76
77          my %constants;
78          BEGIN {
79             %constants = (FOO => 1, BAR => 2);
80          }
81          use constant \%constants;
82
83          $EXPORT_TAGS{constants} = sub {
84             my $class = shift;
85             my ($name, $args, $globals) = @_;
86
87             return keys(%constants);
88          };
89
90   Hooks
91       Sometimes as well as exporting stuff, you want to do some setup or
92       something.
93
94       You can define a couple of class methods in your package, and they'll
95       get called at the appropriate time:
96
97          package MyUtils;
98
99          ...;
100
101          sub _exporter_validate_opts {
102             my $class = shift;
103             my ($globals) = @_;
104
105             ...;   # do stuff here
106
107             $class->SUPER::_exporter_validate_opts(@_);
108          }
109
110          sub _exporter_validate_unimport_opts {
111             my $class = shift;
112             my ($globals) = @_;
113
114             ...;   # do stuff here
115
116             $class->SUPER::_exporter_validate_unimport_opts(@_);
117          }
118
119       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
123       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
127   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
132       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
137       _exporter_validate_opts($globals)
138           Documented above.
139
140       _exporter_validate_unimport_opts($globals)
141           Documented above.
142
143       "_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
147       "_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
153           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
158           The default implementation uses %EXPORT_TAGS to expand tags, and
159           provides fallbacks for the ":default" and ":all" tags.
160
161       "_exporter_expand_regexp($regexp, $args, $globals)"
162           Like "_exporter_expand_regexp", but given a regexp-like string
163           instead of a tag name.
164
165           The default implementation greps through @EXPORT_OK for imports,
166           and the list of already-imported functions for exports.
167
168       "_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
175              (
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
182           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
188           Despite the name, is also called for non-code symbols.
189
190       _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
197           The default implementation of this method assembles the regexp from
198           @EXPORT and @EXPORT_OK.
199
200       "_exporter_fail($name, $args, $globals)"
201           Called by "_exporter_expand_sub" if it can't find a coderef to
202           export.
203
204           The default implementation just throws an exception. But you could
205           emit a warning instead, or just ignore the failed export.
206
207           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
212       "_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
216           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
222           Despite the name, is also called for non-code symbols.
223
224       "_exporter_uninstall_sub($name, $args, $globals)"
225           The opposite of "_exporter_install_sub".
226

AUTHOR

233       Toby Inkster <tobyink@cpan.org>.
234

COPYRIGHT AND LICENCE

236       This software is copyright (c) 2013-2014, 2017, 2022-2023 by Toby
237       Inkster.
238
239       This is free software; you can redistribute it and/or modify it under
240       the same terms as the Perl 5 programming language system itself.
241

DISCLAIMER OF WARRANTIES

243       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
244       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
245       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
246
247
248
249perl v5.36.0                      2023-04-0E2xporter::Tiny::Manual::Exporting(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENCE

DISCLAIMER OF WARRANTIES