1Exporter::Tiny::Manual:U:sIemrpoCrotnitnrgi(b3u)ted PerlExDpoocrutmeern:t:aTtiinoyn::Manual::Importing(3)
2
6 Exporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based
7 modules
8
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 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 Basic importing
20 It's easy to import a single function from a module:
21 use MyUtils "frobnicate";
23 Or a list of functions:
25 use MyUtils "red", "green";
27 Perl's "qw()" shorthand for a list of words is pretty useful:
29 use MyUtils qw( red green );
31 If the module defines tags, you can import them like this:
33 use MyUtils qw( :colours );
35 Or with a hyphen instead of a colon:
37 use MyUtils qw( -colours );
39 Hyphens are good because Perl will autoquote a bareword that follows
41 them:
42 use MyUtils -colours;
44 And it's possible to mix function names and tags in the same list:
46 use MyUtils qw( frobnicate :colours );
48 Renaming imported functions
50 It's possible to rename a function you're importing:
51 use MyUtils "frobnicate" => { -as => "frob" };
53 Or you can apply a prefix and/or suffix. The following imports the
55 function and calls it "my_frobinate_thing".
56 use MyUtils "frobnicate" => { -prefix => "my_", -suffix => "_thing" };
58 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 use MyUtils { prefix => "my_" }, "frobnicate";
64 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 You can import the same function multiple times with different names:
70 use MyUtils
72 "frobnicate" => { -as => "frob" },
73 "frobnicate" => { -as => "frbnct" };
74 Tags can take the "-prefix" and "-suffix" options too. The following
76 imports "colour_red", "colour_green", and "colour_blue":
77 use MyUtils -colours => { -prefix => "colour_" };
79 You can also set "-as" to be a coderef to generate a function name.
81 This imports functions called "RED", "GREEN", and "BLUE":
82 use MyUtils -colours => { -as => sub { uc($_[0]) } };
84 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 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 use MyUtils qw( -all !frobnicate );
95 You can add the bang prefix to tags too. This will import everything
97 except the colours.
98 use MyUtils qw( -all !:colours );
100 Negated imports always "win", so the following will not import
102 "frobnicate", no matter how many times you repeat it...
103 use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
105 Importing by regexp
107 Here's how you could import all functions beginning with an "f":
108 use MyUtils qw( /^F/i );
110 Or import everything except functions beginning with a "z":
112 use MyUtils qw( -all !/^Z/i );
114 Note that regexps are always supplied as strings starting with "/", and
116 not as quoted regexp references ("qr/.../").
117 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 use MyUtils { into => "OtherPkg" }, "frobnicate";
123 OtherPkg::frobincate(...);
125 However, Import::Into will probably provide you with a better approach
127 which doesn't just work with Exporter::Tiny, but all exporters.
128 Lexical subs on Perl 5.37.2 and above
130 Often you want to make use of an exported function, but don't want it
131 to "pollute" your namespace.
132 On newer versions of Perl, Exporter::Tiny can use "export_lexically"
134 from builtin to give you lexical versions of exports.
135 {
137 use MyUtils -lexical, "frobnicate";
138 frobnicate(...); # ok
140 }
141 frobnicate(...); # not ok
143 This functionality should be considered EXPERIMENTAL until
145 "export_lexically" is included in a stable release of Perl.
146 Lexical subs on Perl older than 5.37.2
148 If you install Lexical::Var, then lexical imports should work on
149 versions of Perl as old as 5.12.
150 That module does have issues that prevent it from being installed on
152 Perl 5.22+. The Alt::Lexical::Var::ButSupportModernPerl module includes
153 patches to fix it.
154 Unimporting
156 You can unimport the functions that MyUtils added to your namespace:
157 no MyUtils;
159 Or just specific ones:
161 no MyUtils qw(frobnicate);
163 If you renamed a function when you imported it, you should unimport by
165 the new name:
166 use MyUtils frobnicate => { -as => "frob" };
168 ...;
169 no MyUtils "frob";
170 Unimporting using tags and regexps should mostly do what you want.
172
174 Overwriting existing sub '%s::%s' with sub '%s' exported by %s
175 A warning issued if Exporter::Tiny is asked to export a symbol
176 which will result in an existing sub being overwritten. This
177 warning can be suppressed using either of the following:
178 use MyUtils { replace => 1 }, "frobnicate";
180 use MyUtils "frobnicate" => { -replace => 1 };
181 Or can be upgraded to a fatal error:
183 use MyUtils { replace => "die" }, "frobnicate";
185 use MyUtils "frobnicate" => { -replace => "die" };
186 Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by
188 %s
189 The fatal version of the above warning.
190 Could not find sub '%s' exported by %s
192 You requested to import a sub which the package does not provide.
193 Cannot provide an -as option for tags
195 Because a tag may provide more than one function, it does not make
196 sense to request a single name for it. Instead use "-prefix" or
197 "-suffix".
198 Passing options to unimport '%s' makes no sense
200 When you import a sub, it occasionally makes sense to pass some
201 options for it. However, when unimporting, options do nothing, so
202 this warning is issued.
203
205 Exporter::Shiny, Exporter::Tiny.
206
208 Toby Inkster <tobyink@cpan.org>.
209
211 This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
212 This is free software; you can redistribute it and/or modify it under
214 the same terms as the Perl 5 programming language system itself.
215
217 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
218 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
219 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
220perl v5.36.0 2022-11-2E1xporter::Tiny::Manual::Importing(3)