.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Exporter::Tiny::Manual::Importing 3pm"
.TH Exporter::Tiny::Manual::Importing 3pm "2023-06-11" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Exporter::Tiny::Manual::Importing \- importing from Exporter::Tiny\-based modules
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
For the purposes of this discussion we'll assume we have a module called
\&\f(CW\*(C`MyUtils\*(C'\fR which exports functions called \f(CW\*(C`frobnicate\*(C'\fR, \f(CW\*(C`red\*(C'\fR,
\&\f(CW\*(C`blue\*(C'\fR, and \f(CW\*(C`green\*(C'\fR. It has a tag set up called \f(CW\*(C`:colours\*(C'\fR which
corresponds to \f(CW\*(C`red\*(C'\fR, \f(CW\*(C`blue\*(C'\fR, and \f(CW\*(C`green\*(C'\fR.
.PP
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 \s-1API.\s0
.SS "Basic importing"
.IX Subsection "Basic importing"
It's easy to import a single function from a module:
.PP
.Vb 1
\&   use MyUtils "frobnicate";
.Ve
.PP
Or a list of functions:
.PP
.Vb 1
\&   use MyUtils "red", "green";
.Ve
.PP
Perl's \f(CW\*(C`qw()\*(C'\fR shorthand for a list of words is pretty useful:
.PP
.Vb 1
\&   use MyUtils qw( red green );
.Ve
.PP
If the module defines tags, you can import them like this:
.PP
.Vb 1
\&   use MyUtils qw( :colours );
.Ve
.PP
Or with a hyphen instead of a colon:
.PP
.Vb 1
\&   use MyUtils qw( \-colours );
.Ve
.PP
Hyphens are good because Perl will autoquote a bareword that follows
them:
.PP
.Vb 1
\&   use MyUtils \-colours;
.Ve
.PP
And it's possible to mix function names and tags in the same list:
.PP
.Vb 1
\&   use MyUtils qw( frobnicate :colours );
.Ve
.SS "Renaming imported functions"
.IX Subsection "Renaming imported functions"
It's possible to rename a function you're importing:
.PP
.Vb 1
\&   use MyUtils "frobnicate" => { \-as => "frob" };
.Ve
.PP
Or you can apply a prefix and/or suffix. The following imports the
function and calls it \f(CW\*(C`my_frobinate_thing\*(C'\fR.
.PP
.Vb 1
\&   use MyUtils "frobnicate" => { \-prefix => "my_", \-suffix => "_thing" };
.Ve
.PP
You can apply a prefix/suffix to \fBall\fR functions you import by
placing the hashref \fBfirst\fR in the import list. (This first hashref
is referred to as the global options hash, and can do some special
things.)
.PP
.Vb 1
\&   use MyUtils { prefix => "my_" }, "frobnicate";
.Ve
.PP
Did you notice that we used \f(CW\*(C`\-prefix\*(C'\fR and \f(CW\*(C`\-suffix\*(C'\fR in the
normal options hash, but \f(CW\*(C`prefix\*(C'\fR and \f(CW\*(C`suffix\*(C'\fR (no hyphen)
in the global options hash? That's a common pattern with this module.
.PP
You can import the same function multiple times with different names:
.PP
.Vb 3
\&   use MyUtils
\&      "frobnicate" => { \-as => "frob" },
\&      "frobnicate" => { \-as => "frbnct" };
.Ve
.PP
Tags can take the \f(CW\*(C`\-prefix\*(C'\fR and \f(CW\*(C`\-suffix\*(C'\fR options too. The 
following imports \f(CW\*(C`colour_red\*(C'\fR, \f(CW\*(C`colour_green\*(C'\fR, and \f(CW\*(C`colour_blue\*(C'\fR:
.PP
.Vb 1
\&   use MyUtils \-colours => { \-prefix => "colour_" };
.Ve
.PP
You can also set \f(CW\*(C`\-as\*(C'\fR to be a coderef to generate a function
name. This imports functions called \f(CW\*(C`RED\*(C'\fR, \f(CW\*(C`GREEN\*(C'\fR, and \f(CW\*(C`BLUE\*(C'\fR:
.PP
.Vb 1
\&   use MyUtils \-colours => { \-as => sub { uc($_[0]) } };
.Ve
.PP
Note that it doesn't make sense to use \f(CW\*(C`\-as\*(C'\fR with a tag unless
you're doing this coderef thing. Coderef \f(CW\*(C`as\*(C'\fR also works in the
global options hash.
.SS "\s-1DO NOT WANT\s0!"
.IX Subsection "DO NOT WANT!"
Sometimes you want to supply a list of functions you \fBdon't\fR want
to import. To do that, prefix the function with a bang. This imports
everything except \*(L"frobnicate\*(R":
.PP
.Vb 1
\&   use MyUtils qw( \-all !frobnicate );
.Ve
.PP
You can add the bang prefix to tags too. This will import everything
except the colours.
.PP
.Vb 1
\&   use MyUtils qw( \-all !:colours );
.Ve
.PP
Negated imports always \*(L"win\*(R", so the following will not import
\&\*(L"frobnicate\*(R", no matter how many times you repeat it...
.PP
.Vb 1
\&   use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
.Ve
.SS "Importing by regexp"
.IX Subsection "Importing by regexp"
Here's how you could import all functions beginning with an \*(L"f\*(R":
.PP
.Vb 1
\&   use MyUtils qw( /^F/i );
.Ve
.PP
Or import everything except functions beginning with a \*(L"z\*(R":
.PP
.Vb 1
\&   use MyUtils qw( \-all !/^Z/i );
.Ve
.PP
Note that regexps are always supplied as \fIstrings\fR starting with
\&\f(CW"/"\fR, and not as quoted regexp references (\f(CW\*(C`qr/.../\*(C'\fR).
.SS "Import functions into another package"
.IX Subsection "Import functions into another package"
Occasionally you need to import functions not into your own package,
but into a different package. You can do that like this:
.PP
.Vb 1
\&   use MyUtils { into => "OtherPkg" }, "frobnicate";
\&   
\&   OtherPkg::frobincate(...);
.Ve
.PP
However, Import::Into will probably provide you with a better
approach which doesn't just work with Exporter::Tiny, but \fBall\fR
exporters.
.SS "Lexical subs on Perl 5.37.2 and above"
.IX Subsection "Lexical subs on Perl 5.37.2 and above"
Often you want to make use of an exported function, but don't want
it to \*(L"pollute\*(R" your namespace.
.PP
On newer versions of Perl, Exporter::Tiny can use \f(CW\*(C`export_lexically\*(C'\fR
from builtin to give you lexical versions of exports.
.PP
.Vb 2
\&   {
\&      use MyUtils \-lexical, "frobnicate";
\&      
\&      frobnicate(...);  # ok
\&   }
\&   
\&   frobnicate(...);  # not ok
.Ve
.PP
This functionality should be considered \fB\s-1EXPERIMENTAL\s0\fR until
\&\f(CW\*(C`export_lexically\*(C'\fR is included in a stable release of Perl.
.SS "Lexical subs on Perl older than 5.37.2"
.IX Subsection "Lexical subs on Perl older than 5.37.2"
If you install Lexical::Var, then lexical imports should work on versions
of Perl as old as 5.12.
.SS "Unimporting"
.IX Subsection "Unimporting"
You can unimport the functions that MyUtils added to your namespace:
.PP
.Vb 1
\&   no MyUtils;
.Ve
.PP
Or just specific ones:
.PP
.Vb 1
\&   no MyUtils qw(frobnicate);
.Ve
.PP
If you renamed a function when you imported it, you should unimport by
the new name:
.PP
.Vb 3
\&   use MyUtils frobnicate => { \-as => "frob" };
\&   ...;
\&   no MyUtils "frob";
.Ve
.PP
Unimporting using tags and regexps should mostly do what you want.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "\fBOverwriting existing sub '%s::%s' with sub '%s' exported by \f(CB%s\fB\fR" 4
.IX Item "Overwriting existing sub '%s::%s' with sub '%s' exported by %s"
A warning issued if Exporter::Tiny is asked to export a symbol which
will result in an existing sub being overwritten. This warning can be
suppressed using either of the following:
.Sp
.Vb 2
\&   use MyUtils { replace => 1 }, "frobnicate";
\&   use MyUtils "frobnicate" => { \-replace => 1 };
.Ve
.Sp
Or can be upgraded to a fatal error:
.Sp
.Vb 2
\&   use MyUtils { replace => "die" }, "frobnicate";
\&   use MyUtils "frobnicate" => { \-replace => "die" };
.Ve
.IP "\fBRefusing to overwrite existing sub '%s::%s' with sub '%s' exported by \f(CB%s\fB\fR" 4
.IX Item "Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s"
The fatal version of the above warning.
.IP "\fBCould not find sub '%s' exported by \f(CB%s\fB\fR" 4
.IX Item "Could not find sub '%s' exported by %s"
You requested to import a sub which the package does not provide.
.IP "\fBCannot provide an \-as option for tags\fR" 4
.IX Item "Cannot provide an -as option for tags"
Because a tag may provide more than one function, it does not make sense
to request a single name for it. Instead use \f(CW\*(C`\-prefix\*(C'\fR or \f(CW\*(C`\-suffix\*(C'\fR.
.IP "\fBPassing options to unimport '%s' makes no sense\fR" 4
.IX Item "Passing options to unimport '%s' makes no sense"
When you import a sub, it occasionally makes sense to pass some options
for it. However, when unimporting, options do nothing, so this warning
is issued.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<https://exportertiny.github.io/>.
.PP
Exporter::Shiny,
Exporter::Tiny.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013\-2014, 2017, 2022\-2023 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0