perlancar > Perinci-Exporter > Perinci::Exporter



Annotate this POD


View/Report Bugs
Module Version: 0.07   Source  


Perinci::Exporter - Metadata-aware Exporter


This document describes version 0.07 of Perinci::Exporter (from Perl distribution Perinci-Exporter), released on 2015-09-29.


 package YourModule;

 # most of the time, you only need to do this
 use Perinci::Exporter;

 our %SPEC;

 # f1 will not be exported by default, but user can import them explicitly using
 # 'use YourModule qw(f1)'
 $SPEC{f1} = { v=>1.1 };
 sub f1 { ... }

 # f2 will be exported by default because it has the export:default tag
 $SPEC{f2} = { v=>1.1, tags=>[qw/a export:default/] };
 sub f2 { ... }

 # f3 will never be exported, and user cannot import them via 'use YourModule
 # qw(f1)' nor via 'use YourModule qw(:a)'
 $SPEC{f3} = { v=>1.1, tags=>[qw/a export:never/] };
 sub f3 { ... }


Perinci::Exporter is an exporter which can utilize information from Rinci metadata. If your package has Rinci metadata, consider using this exporter for convenience and flexibility.

Features of this module:


Most of the time, to set up exporter, you only need to just use() it in your module:

 package YourModule;
 use Perinci::Exporter;

Perinci::Exporter will install an import() routine for your package. If you need to pass some exporting options:

 use Perinci::Exporter default_exports=>[qw/foo bar/], ...;

See install_import() for more details.


Default exports. Your module users can import functions in a variety of ways. The simplest form is:

 use YourModule;

which by default will export all functions marked with export:default tags. For example:

 package YourModule;
 use Perinci::Exporter;
 our %SPEC;
 $SPEC{f1} = { v=>1.1, tags=>[qw/export:default a/] };
 sub   f1    { ... }
 $SPEC{f2} = { v=>1.1, tags=>[qw/export:default a b/] };
 sub   f2    { ... }
 $SPEC{f3} = { v=>1.1, tags=>[qw/b c/] };
 sub   f3    { ... }
 $SPEC{f4} = { v=>1.1, tags=>[qw/a b c export:never/] };
 sub   f4    { ... }

YourModule will by default export f1 and f2. If there are no functions tagged with export:default, there will be no default exports. You can also supply the list of default functions via the default_exports argument:

 use Perinci::Exporter default_exports => [qw/f1 f2/];

or via the @EXPORT package variable, like in Exporter.

Importing individual functions. Your module users can import individual functions:

 use YourModule qw(f1 f2);

Each function can have import options, specified in a hashref:

 use YourModule f1 => {wrap=>0}, f2=>{as=>'bar', args_as=>'array'};
 # imports f1, bar

Importing groups of functions by tags. Your module users can import groups of individual functions using tags. Tags are collected from function metadata, and written with a : prefix to differentiate them from function names. Each tag can also have import options:

 use YourModule 'f3', ':a' => {prefix => 'a_'}; # imports f3, a_f1, a_f2

Some tags are defined automatically: :default (all functions that have the export:default tag), :all (all functions).

Importing to a different name. As can be seen from previous examples, the 'as' and 'prefix' (and also 'suffix') import options can be used to import subroutines using into a different name.

Bailing on name clashes. By default, importing will override existing names in the target package. To warn about this, users can set '-on_clash' to 'bail':

 use YourModule 'f1', f2=>{as=>'f1'}, -on_clash=>'bail'; # dies, imports clash

 use YourModule 'f1', -on_clash=>'bail'; # dies, f1 already exists
 sub f1 { ... }

Customizing wrapping options. Users can specify custom wrapping options when importing functions. The wrapping will then be done just for them (as opposed to wrapped functions which are wrapped using default options, which will be shared among all importers not requesting custom wrapping). See some examples in "FAQ".

See do_export() for more details.



The routine which installs the import() routine to caller package.


do_export($expopts, @args)

The routine which implements the exporting. Will be called from the import() routine. $expopts is a hashref containing exporter options, constructed by install_import(). @args is the same as arguments passed during import: a sequence of function name or tag name (prefixed with :), function/tag name and export option (hashref), or option (prefixed with -).


 do_export('f1', ':tag1', f2 => {import option...}, -option => ...);

Import options:



Why use this module as my exporter?

If you are fine with Exporter, Exporter::Lite, or Sub::Exporter, then you probably won't need this module.

This module is particularly useful if your subs have Rinci metadata, in which case you'll get some nice features. Some examples of the things you can do with this exporter:

What happens to functions that do not have metadata?

They can still be exported if you list them in @EXPORT or @EXPORT_OK.





Please visit the project's homepage at


Source repository is at


Please report any bugs or feature requests on the bugtracker website

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.


perlancar <>


This software is copyright (c) 2015 by

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

syntax highlighting: