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

NAME

6       Exporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based
7       modules
8

DESCRIPTION

10       For the purposes of this discussion we'll assume we have a module
11       called "MyUtils" which exports functions called "frobnicate", "red",
12       "blue", and "green". It has a tag set up called ":colours" which
13       corresponds to "red", "blue", and "green".
14
15       Many of these tricks may seem familiar from Sub::Exporter. That is
16       intentional. Exporter::Tiny doesn't attempt to provide every feature of
17       Sub::Exporter, but where it does it usually uses a fairly similar API.
18
19   Basic importing
20       It's easy to import a single function from a module:
21
22          use MyUtils "frobnicate";
23
24       Or a list of functions:
25
26          use MyUtils "red", "green";
27
28       Perl's "qw()" shorthand for a list of words is pretty useful:
29
30          use MyUtils qw( red green );
31
32       If the module defines tags, you can import them like this:
33
34          use MyUtils qw( :colours );
35
36       Or with a hyphen instead of a colon:
37
38          use MyUtils qw( -colours );
39
40       Hyphens are good because Perl will autoquote a bareword that follows
41       them:
42
43          use MyUtils -colours;
44
45       And it's possible to mix function names and tags in the same list:
46
47          use MyUtils qw( frobnicate :colours );
48
49   Renaming imported functions
50       It's possible to rename a function you're importing:
51
52          use MyUtils "frobnicate" => { -as => "frob" };
53
54       Or you can apply a prefix and/or suffix. The following imports the
55       function and calls it "my_frobinate_thing".
56
57          use MyUtils "frobnicate" => { -prefix => "my_", -suffix => "_thing" };
58
59       You can apply a prefix/suffix to all functions you import by placing
60       the hashref first in the import list. (This first hashref is referred
61       to as the global options hash, and can do some special things.)
62
63          use MyUtils { prefix => "my_" }, "frobnicate";
64
65       Did you notice that we used "-prefix" and "-suffix" in the normal
66       options hash, but "prefix" and "suffix" (no hyphen) in the global
67       options hash? That's a common pattern with this module.
68
69       You can import the same function multiple times with different names:
70
71          use MyUtils
72             "frobnicate" => { -as => "frob" },
73             "frobnicate" => { -as => "frbnct" };
74
75       Tags can take the "-prefix" and "-suffix" options too. The following
76       imports "colour_red", "colour_green", and "colour_blue":
77
78          use MyUtils -colours => { -prefix => "colour_" };
79
80       You can also set "-as" to be a coderef to generate a function name.
81       This imports functions called "RED", "GREEN", and "BLUE":
82
83          use MyUtils -colours => { -as => sub { uc($_[0]) } };
84
85       Note that it doesn't make sense to use "-as" with a tag unless you're
86       doing this coderef thing. Coderef "as" also works in the global options
87       hash.
88
89   DO NOT WANT!
90       Sometimes you want to supply a list of functions you don't want to
91       import. To do that, prefix the function with a bang. This imports
92       everything except "frobnicate":
93
94          use MyUtils qw( -all !frobnicate );
95
96       You can add the bang prefix to tags too. This will import everything
97       except the colours.
98
99          use MyUtils qw( -all !:colours );
100
101       Negated imports always "win", so the following will not import
102       "frobnicate", no matter how many times you repeat it...
103
104          use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
105
106   Importing by regexp
107       Here's how you could import all functions beginning with an "f":
108
109          use MyUtils qw( /^F/i );
110
111       Or import everything except functions beginning with a "z":
112
113          use MyUtils qw( -all !/^Z/i );
114
115       Note that regexps are always supplied as strings starting with "/", and
116       not as quoted regexp references ("qr/.../").
117
118   Import functions into another package
119       Occasionally you need to import functions not into your own package,
120       but into a different package. You can do that like this:
121
122          use MyUtils { into => "OtherPkg" }, "frobnicate";
123
124          OtherPkg::frobincate(...);
125
126       However, Import::Into will probably provide you with a better approach
127       which doesn't just work with Exporter::Tiny, but all exporters.
128
129   Lexical subs
130       Often you want to make use of an exported function, but don't want it
131       to "pollute" your namespace.
132
133       There is this Sub::Exporter::Lexical thing that was designed as a
134       plugin for Sub::Exporter, but Exporter::Tiny's API is close enough that
135       it will work. Do you remember that global options hash? Just use that
136       to tell Exporter::Tiny to use an alternative sub installer.
137
138          {
139             use Sub::Exporter::Lexical lexical_installer => { -as => "lex" };
140             use MyUtils { installer => lex }, "frobnicate";
141
142             frobnicate(...);  # ok
143          }
144
145          frobnicate(...);  # not ok
146
147       Another way to do lexical functions is to import a function into a
148       scalar variable:
149
150          my $func;
151          use MyUtils "frobnicate" => { -as => \$func };
152
153          $func->(...);
154
155       You can even provide a hashref to put all imported functions into as
156       part of that global options hash I mentioned earlier.
157
158          my %funcs;
159          use MyUtils { into => \%funcs }, "frobnicate";
160
161          $funcs{frobnicate}->(...);
162
163   Unimporting
164       You can unimport the functions that MyUtils added to your namespace:
165
166          no MyUtils;
167
168       Or just specific ones:
169
170          no MyUtils qw(frobnicate);
171
172       If you renamed a function when you imported it, you should unimport by
173       the new name:
174
175          use MyUtils frobnicate => { -as => "frob" };
176          ...;
177          no MyUtils "frob";
178
179       Unimporting using tags and regexps should mostly do what you want.
180

DIAGNOSTICS

182       Overwriting existing sub '%s::%s' with sub '%s' exported by %s
183           A warning issued if Exporter::Tiny is asked to export a symbol
184           which will result in an existing sub being overwritten. This
185           warning can be suppressed using either of the following:
186
187              use MyUtils { replace => 1 }, "frobnicate";
188              use MyUtils "frobnicate" => { -replace => 1 };
189
190           Or can be upgraded to a fatal error:
191
192              use MyUtils { replace => "die" }, "frobnicate";
193              use MyUtils "frobnicate" => { -replace => "die" };
194
195       Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by
196       %s
197           The fatal version of the above warning.
198
199       Could not find sub '%s' exported by %s
200           You requested to import a sub which the package does not provide.
201
202       Cannot provide an -as option for tags
203           Because a tag may provide more than one function, it does not make
204           sense to request a single name for it. Instead use "-prefix" or
205           "-suffix".
206
207       Passing options to unimport '%s' makes no sense
208           When you import a sub, it occasionally makes sense to pass some
209           options for it. However, when unimporting, options do nothing, so
210           this warning is issued.
211

SEE ALSO

213       Exporter::Shiny, Exporter::Tiny.
214

AUTHOR

216       Toby Inkster <tobyink@cpan.org>.
217

219       This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
220
221       This is free software; you can redistribute it and/or modify it under
222       the same terms as the Perl 5 programming language system itself.
223

DISCLAIMER OF WARRANTIES

225       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
226       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
227       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
228
229
230
231perl v5.28.1                      2018-07-1E7xporter::Tiny::Manual::Importing(3)
Impressum