Exporter::Tiny::Manual::Importing(3) User Contributed Perl Documentation Exporter::Tiny::Manual::Importing(3)

# [NAME](#NAME)

Exporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based modules

# [DESCRIPTION](#DESCRIPTION)

For the purposes of this discussion we'll assume we have a module called "MyUtils" which exports functions called "frobnicate", "red", "blue", and "green". It has a tag set up called ":colours" which corresponds to "red", "blue", and "green".

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.

## [Basic importing](#Basic_importing)

It's easy to import a single function from a module:

```
   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 );
```

## [Renaming imported functions](#Renaming_imported_functions)

It's possible to rename a function you're importing:

```
   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.

## [DO NOT WANT!](#DO_NOT_WANT!)

Sometimes you want to supply a list of functions you **don't** want to import. To do that, prefix the function with a bang. This imports everything except "frobnicate":

```
   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 );
```

## [Importing by regexp](#Importing_by_regexp)

Here's how you could import all functions beginning with an "f":

```
   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/.../").

## [Import functions into another package](#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:

```
   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.

## [Lexical subs on Perl 5.37.2 and above](#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 "pollute" your namespace.

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.

## [Lexical subs on Perl older than 5.37.2](#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.

## [Importing into a hash](#Importing_into_a_hash)

Another way of avoiding polluting your namespace with imports is to import into a hash.

```
   my %U;
   use MyUtils { into => \%U };
   
   ...
   $U{frobnicate}->(...);
```

## [Unimporting](#Unimporting)

You can unimport the functions that MyUtils added to your namespace:

```
   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.

# [DIAGNOSTICS](#DIAGNOSTICS)

[**Overwriting existing sub '%s::%s' with sub '%s' exported by %s**](#Overwriting)

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:

```
   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" };
    
```

[**Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s**](#Refusing)

The fatal version of the above warning.

[**Could not find sub '%s' exported by %s**](#Could)

You requested to import a sub which the package does not provide.

[**Cannot provide an -as option for tags**](#Cannot)

Because a tag may provide more than one function, it does not make sense to request a single name for it. Instead use "-prefix" or "-suffix".

[**Passing options to unimport '%s' makes no sense**](#Passing)

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.

# [SEE ALSO](#SEE_ALSO)

<https://exportertiny.github.io/>.

Exporter::Shiny, Exporter::Tiny.

# [AUTHOR](#AUTHOR)

Toby Inkster <tobyink@cpan.org>.

# [COPYRIGHT AND LICENCE](#COPYRIGHT_AND_LICENCE)

This software is copyright (c) 2013-2014, 2017, 2022-2025 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

# [DISCLAIMER OF WARRANTIES](#DISCLAIMER_OF_WARRANTIES)

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

2026-10-25 perl v5.44.0

---

Document: Exporter::Tiny::Manual::Importing(3pm) from perl-exporter-tiny 1.006003-r3 (Chainguard OS)
Source: https://github.com/tobyink/p5-exporter-tiny