Many of these tricks may seem familiar from Sub::Exporter. That is intentional. Exporter::Tiny doesn't attempt to provide every feature of Sub::Exporter, but where it does it usually uses a fairly similar API.
use MyUtils "frobnicate";
Or a list of functions:
use MyUtils "red", "green";
Perl's "qw()" shorthand for a list of words is pretty useful:
use MyUtils qw( red green );
If the module defines tags, you can import them like this:
use MyUtils qw( :colours );
Or with a hyphen instead of a colon:
use MyUtils qw( -colours );
Hyphens are good because Perl will autoquote a bareword that follows them:
use MyUtils -colours;
And it's possible to mix function names and tags in the same list:
use MyUtils qw( frobnicate :colours );
use MyUtils "frobnicate" => { -as => "frob" };
Or you can apply a prefix and/or suffix. The following imports the function and calls it "my_frobinate_thing".
use MyUtils "frobnicate" => { -prefix => "my_", -suffix => "_thing" };
You can apply a prefix/suffix to all functions you import by placing the hashref first in the import list. (This first hashref is referred to as the global options hash, and can do some special things.)
use MyUtils { prefix => "my_" }, "frobnicate";
Did you notice that we used "-prefix" and "-suffix" in the normal options hash, but "prefix" and "suffix" (no hyphen) in the global options hash? That's a common pattern with this module.
You can import the same function multiple times with different names:
use MyUtils "frobnicate" => { -as => "frob" }, "frobnicate" => { -as => "frbnct" };
Tags can take the "-prefix" and "-suffix" options too. The following imports "colour_red", "colour_green", and "colour_blue":
use MyUtils -colours => { -prefix => "colour_" };
You can also set "-as" to be a coderef to generate a function name. This imports functions called "RED", "GREEN", and "BLUE":
use MyUtils -colours => { -as => sub { uc($_[0]) } };
Note that it doesn't make sense to use "-as" with a tag unless you're doing this coderef thing. Coderef "as" also works in the global options hash.
use MyUtils qw( -all !frobnicate );
You can add the bang prefix to tags too. This will import everything except the colours.
use MyUtils qw( -all !:colours );
Negated imports always ``win'', so the following will not import ``frobnicate'', no matter how many times you repeat it...
use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
use MyUtils qw( /^F/i );
Or import everything except functions beginning with a ``z'':
use MyUtils qw( -all !/^Z/i );
Note that regexps are always supplied as strings starting with "/", and not as quoted regexp references ("qr/.../").
use MyUtils { into => "OtherPkg" }, "frobnicate"; OtherPkg::frobincate(...);
However, Import::Into will probably provide you with a better approach which doesn't just work with Exporter::Tiny, but all exporters.
On newer versions of Perl, Exporter::Tiny can use "export_lexically" from builtin to give you lexical versions of exports.
{ use MyUtils -lexical, "frobnicate"; frobnicate(...); # ok } frobnicate(...); # not ok
This functionality should be considered EXPERIMENTAL until "export_lexically" is included in a stable release of Perl.
That module does have issues that prevent it from being installed on Perl 5.22+. The Alt::Lexical::Var::ButSupportModernPerl module includes patches to fix it.
no MyUtils;
Or just specific ones:
no MyUtils qw(frobnicate);
If you renamed a function when you imported it, you should unimport by the new name:
use MyUtils frobnicate => { -as => "frob" }; ...; no MyUtils "frob";
Unimporting using tags and regexps should mostly do what you want.
use MyUtils { replace => 1 }, "frobnicate"; use MyUtils "frobnicate" => { -replace => 1 };
Or can be upgraded to a fatal error:
use MyUtils { replace => "die" }, "frobnicate"; use MyUtils "frobnicate" => { -replace => "die" };
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.