File Coverage

blib/lib/Perinci/Exporter.pm
Criterion Covered Total %
statement 162 174 93.1
branch 92 110 83.6
condition 19 35 54.2
subroutine 8 8 100.0
pod 2 2 100.0
total 283 329 86.0


line stmt bran cond sub pod time code
1             package Perinci::Exporter;
2              
3             our $DATE = '2019-09-11'; # DATE
4             our $VERSION = '0.084'; # VERSION
5              
6             # IFUNBUILT
7             # use strict 'subs', 'vars';
8             # use warnings;
9             # END IFUNBUILT
10              
11             # what a generic name, this hash caches the wrapped functions, so that when
12             # importer asks to import a wrapped function with default wrapping options, we
13             # don't have to call wrap_sub again. customly wrapped functions are not cached
14             # though.
15             my %pkg_cache;
16              
17             sub import {
18 1     1   8 my $package = shift;
19 1         6 my @caller = caller(0);
20 1         4 install_import(@_, into => $caller[0]);
21             }
22              
23             sub install_import {
24 26     26 1 110395 my %instargs = @_;
25 26   50     129 my @caller = caller($instargs{caller_level} || 0);
26 26   33     413 my $into = $instargs{into} || $caller[0];
27 26 50       49 return [400, "Please specify package to install import() to ".
28             "(either via 'into' or 'caller_level')"]
29             unless $into;
30             my $import = sub {
31 28     28   267 my $package = shift;
32              
33 28         61 my @caller = caller(0);
34             do_export(
35             {
36             source => $into,
37             target => $caller[0],
38             default_exports => $instargs{default_exports},
39             extra_exports => $instargs{extra_exports},
40             default_wrap => defined($instargs{default_wrap}) ? $instargs{default_wrap} : 0,
41 28 100       454 default_on_clash => defined($instargs{default_on_clash}) ? $instargs{default_on_clash} : 'force',
    100          
42             },
43             @_,
44             );
45 26         84 };
46              
47 2     2   158892 no strict 'refs';
  2         17  
  2         193  
48 26         33 *{"$into\::import"} = $import;
  26         242  
49             }
50              
51             sub do_export {
52 28     28 1 35 my $expopts;
53 28 50 33     105 if ($_[0] && ref($_[0]) eq 'HASH') {
54 28         41 $expopts = shift;
55             } else {
56 0         0 die "First argument to do_export() must be export options";
57             }
58 28         38 my $source = $expopts->{source};
59 28         47 my $target = $expopts->{target};
60              
61              
62             # collect what symbols are available for exporting, along with their tags,
63             # etc.
64              
65 2     2   11 no strict 'refs';
  2         3  
  2         2639  
66              
67 28         30 my %exports;
68 28         31 my $metas = \%{"$source\::SPEC"};
  28         64  
69 28   50     58 $metas ||= {};
70 28         65 for my $k (keys %$metas) {
71             # for now we limit ourselves to subs
72 159 50       410 next unless $k =~ /\A\w+\z/;
73 159 100       174 my @tags = @{ $metas->{$k}{tags} || [] };
  159         408  
74 159 100       241 next if grep {$_ eq 'export:never'} @tags;
  275         454  
75 134         264 $exports{$k} = {
76             tags => \@tags,
77             };
78             }
79              
80 28 100       44 for my $k (@{$expopts->{default_exports} || []},
  28         82  
81 28         64 @{"$source\::EXPORT"}) {
82 54 100       90 if ($exports{$k}) {
83 29         34 push @{$exports{$k}{tags}}, 'export:default';
  29         59  
84             } else {
85 25         55 $exports{$k} = {
86             tags => [qw/export:default/],
87             };
88             }
89             }
90              
91 28 100       35 for my $k (@{$expopts->{extra_exports} || []},
  28         75  
92 28         55 @{"$source\::EXPORT_OK"}) {
93 54 100       87 if ($exports{$k}) {
94             } else {
95 51         86 $exports{$k} = {
96             tags => [],
97             };
98             }
99             }
100              
101 28         64 for my $k (keys %exports) {
102 210         208 push @{$exports{$k}{tags}}, 'all';
  210         306  
103             }
104              
105             # parse import() arguments
106              
107 28         45 my %impopts; #
108             my @imps; # requested symbols or tags to export, each element is:
109 28         32 while (1) {
110 55 100       94 last unless @_;
111 28         36 my $i = shift;
112 28 100       60 if ($i =~ s!^-!!) {
113 4 100       19 die "Import option -$i requires argument" unless @_;
114 3         4 $impopts{$i} = shift;
115 3         7 next;
116             } else {
117 24         29 my $el = {};
118 24 100 100     74 if (@_ && ref($_[0]) eq 'HASH') {
119 11         12 my $io = shift;
120 11         35 $el->{$_} = $io->{$_} for keys %$io;
121             };
122 24         43 $el->{sym} = $i;
123 24         35 push @imps, $el;
124             }
125             }
126              
127 27 100       43 if (!@imps) {
128 5         11 push @imps, {sym=>':default'};
129             }
130              
131             # find out existing symbols on the target package, so we can die on clash,
132             # if that behavior's what the importer wants
133              
134 27         55 my %existing = _list_package_contents($target);
135              
136             # recap information
137 27         62 my $recap = {wrapped=>[]};
138              
139             # import!
140              
141 27   100     80 $pkg_cache{$source} ||= {};
142              
143 27         42 for my $imp (@imps) {
144 29         32 my @ssyms; # symbols from source package
145 29 100       81 if ($imp->{sym} =~ s!^:!!) {
146 7         18 @ssyms = grep { grep {
147 107 100       268 "export:$imp->{sym}" eq $_ || $imp->{sym} eq $_
148 51         55 } @{ $exports{$_}{tags} } }
  51         67  
149             keys %exports;
150             } else {
151 22         40 @ssyms = ($imp->{sym});
152             }
153              
154 29         66 for my $ssym (sort @ssyms) {
155              
156 49 100       81 if (!$exports{$ssym}) {
157 1         13 die "$ssym is not exported by $source";
158             }
159              
160             # export to what target symbol?
161 48         52 my $tsym;
162 48 100       71 if ($imp->{as}) {
163 1         2 $tsym = $imp->{as};
164             } else {
165 47         74 $tsym = $ssym;
166 47 100       104 if (my $prefix = defined($imp->{prefix}) ? $imp->{prefix} : $impopts{prefix}) {
    100          
167 3         5 $tsym = "$prefix$tsym";
168             }
169 47 100       86 if (my $suffix = defined($imp->{suffix}) ? $imp->{suffix} : $impopts{suffix}) {
    100          
170 3         5 $tsym = "$tsym$suffix";
171             }
172             }
173              
174             # clash?
175 48 100       72 if ($existing{$tsym}) {
176 2 100       21 if ((defined($impopts{on_clash}) ? $impopts{on_clash} : $expopts->{default_on_clash})
    50          
177             eq 'bail') {
178 2 50       31 die "Refusing to export ".
179             ($tsym eq $ssym ? $ssym : "$ssym (as $tsym)").
180             " to an existing symbol in package $target";
181             }
182             }
183              
184 46         57 my $wrap;
185             SET_WRAP_OPTS: {
186 46         51 my $default_wrap = ref $expopts->{default_wrap} eq 'HASH' ?
187 46 50       75 {%{ $expopts->{default_wrap} }} : $expopts->{default_wrap};
  0         0  
188 46         48 my $default_wrap_opts = $default_wrap;
189 46 50       80 $default_wrap_opts = {} if ref $default_wrap_opts ne 'HASH';
190 46 100 66     100 $default_wrap = {} if $default_wrap && ref $default_wrap ne 'HASH';
191              
192             $wrap = ref $imp->{wrap} eq 'HASH' ?
193 46 100       79 {%{ $imp->{wrap} }} : $imp->{wrap};
  1         3  
194 46 50 66     78 $wrap = {} if $wrap && ref $wrap ne 'HASH';
195 46 100       70 if (defined $imp->{convert}) {
196 1 50 33     4 die "Error when exporting $ssym: 'convert' option needs wrap=1 but wrap is disabled"
197             if defined $wrap && !$wrap;
198 1 50       3 $wrap = $default_wrap_opts unless ref $wrap eq 'HASH';
199              
200 1         2 $wrap->{convert} = $imp->{convert};
201             }
202 46         69 for (qw/args_as result_naked curry timeout/) {
203 183 100       275 if (defined $imp->{$_}) {
204 5 100 66     27 die "Error when exporting $ssym: '$_' option needs wrap=1 but wrap is disabled"
205             if defined $wrap && !$wrap;
206 4 50       20 $wrap = $default_wrap_opts unless ref $wrap eq 'HASH';
207              
208 4   50     17 $wrap->{convert} ||= {};
209 4         9 $wrap->{convert}{$_} = $imp->{$_};
210             }
211             }
212              
213 45 100       82 $wrap = $default_wrap unless defined $wrap;
214             #use DD; dd {ssym=>$ssym, wrap=>$wrap};
215             } # SET_WRAP_OPTS
216              
217 45         47 my $sub = \&{"$source\::$ssym"};
  45         94  
218             DO_WRAP: {
219 45 100       48 last unless $wrap;
  45         70  
220              
221 12         14 my $cache;
222 12 100       37 if (keys(%$wrap) == 0) {
223             # using default wrap options, we store the cached version of
224             # these
225 6         9 $cache = $pkg_cache{$source}{$ssym}{sub};
226             }
227 12 100       21 if ($cache) {
228 1         2 $sub = $cache;
229 1         2 push @{ $recap->{wrapped} }, $ssym;
  1         2  
230             } else {
231 11         12 $sub = \&{"$source\::$ssym"};
  11         53  
232 11         16 my $meta = $metas->{$ssym};
233 11 100       20 if (!$meta) {
234             #warn "Exporting $ssym to $target\::$tsym unwrapped ".
235             # "because $ssym does not have metadata";
236             } else {
237 10         994 require Perinci::Sub::Wrapper;
238 10         19398 my $res = Perinci::Sub::Wrapper::wrap_sub(
239             %$wrap,
240             sub_name => "$source\::$ssym",
241             meta => $meta,
242             );
243 10 50       27834 die "Can't wrap $ssym for $target: ".
244             "$res->[0] - $res->[1]" unless $res->[0] == 200;
245 10         19 $sub = $res->[2]{sub};
246 10 100       28 $pkg_cache{$source}{$ssym}{sub} = $sub
247             if keys(%$wrap) == 0;
248 10         16 push @{ $recap->{wrapped} }, $ssym;
  10         53  
249             }
250             }
251             } # DO_WRAP
252              
253             # finally, do the actual exporting!
254             #say "Exporting $ssym -> $target\::$tsym"; #DEBUG#
255 45         50 *{"$target\::$tsym"} = $sub;
  45         150  
256              
257 45         104 $existing{$tsym}++;
258              
259             } # for @ssyms
260              
261             } # for @imps
262              
263 23         1753 $recap;
264             }
265              
266             # borrowed from Package::MoreUtil. this is actually not a proper implementation,
267             # but since we want to avoid extra footprint by loading Package::Stash, we'll
268             # get by for now.
269             sub _list_package_contents {
270 27     27   35 my $pkg = shift;
271              
272 27 50 33     62 return () unless !length($pkg) || _package_exists($pkg);
273 27         41 my $symtbl = \%{$pkg . "::"};
  27         48  
274              
275 27         32 my %res;
276 27         106 while (my ($k, $v) = each %$symtbl) {
277 54 50       100 next if $k =~ /::$/; # subpackage
278 54         57 my $n;
279 54 50       187 if ("$v" !~ /^\*/) {
280             # constant
281 0         0 $res{$k} = $v;
282 0         0 next;
283             }
284 54 100       134 if (defined *$v{CODE}) {
285 3         6 $res{$k} = *$v{CODE}; # subroutine
286 3         5 $n++;
287             }
288 54 50       107 if (defined *$v{HASH}) {
289 0         0 $res{"\%$k"} = \%{*$v}; # hash
  0         0  
290 0         0 $n++;
291             }
292 54 100       104 if (defined *$v{ARRAY}) {
293 24         28 $res{"\@$k"} = \@{*$v}; # array
  24         53  
294 24         37 $n++;
295             }
296 54 50 33     124 if (defined(*$v{SCALAR}) # XXX always defined?
297 54         130 && defined(${*$v})) { # currently we filter undef values
298 0         0 $res{"\$$k"} = \${*$v}; # scalar
  0         0  
299 0         0 $n++;
300             }
301              
302 54 100       134 if (!$n) {
303 27         110 $res{"\*$k"} = $v; # glob
304             }
305             }
306              
307 27         93 %res;
308             }
309              
310             # also borrowed from Package::MoreUtil
311             sub _package_exists {
312 27     27   31 my $pkg = shift;
313              
314             # opt
315             #return unless $pkg =~ /\A\w+(::\w+)*\z/;
316              
317 27 50       57 if ($pkg =~ s!::(\w+)\z!!) {
318 0         0 return !!${$pkg . "::"}{$1 . "::"};
  0         0  
319             } else {
320 27         93 return !!$::{$pkg . "::"};
321             }
322             }
323              
324             1;
325             # ABSTRACT: An exporter that groks Rinci metadata
326              
327             __END__
328              
329             =pod
330              
331             =encoding UTF-8
332              
333             =head1 NAME
334              
335             Perinci::Exporter - An exporter that groks Rinci metadata
336              
337             =head1 VERSION
338              
339             This document describes version 0.084 of Perinci::Exporter (from Perl distribution Perinci-Exporter), released on 2019-09-11.
340              
341             =head1 SYNOPSIS
342              
343             Exporting:
344              
345             package YourModule;
346              
347             # most of the time, you only need to do this
348             use Perinci::Exporter;
349              
350             our %SPEC;
351              
352             # f1 will not be exported by default, but user can import them explicitly using
353             # 'use YourModule qw(f1)'
354             $SPEC{f1} = { v=>1.1 };
355             sub f1 { ... }
356              
357             # f2 will be exported by default because it has the export:default tag
358             $SPEC{f2} = {
359             v=>1.1,
360             args=>{a1=>{schema=>"float*",req=>1, pos=>0}, a2=>{schema=>'float*', req=>1, pos=>1}},
361             tags=>[qw/a export:default/],
362             };
363             sub f2 {
364             my %args = @_;
365             }
366              
367             # f3 will never be exported, and user cannot import them via 'use YourModule
368             # qw(f3)' nor via 'use YourModule qw(:a)'
369             $SPEC{f3} = { v=>1.1, tags=>[qw/a export:never/] };
370             sub f3 { ... }
371              
372             1;
373              
374             Importing:
375              
376             # does not import anything
377             use YourModule ();
378              
379             # imports all functions tagged with 'export:default' (f2)
380             use YourModule;
381              
382             # explicitly import functions by name (f1, f2)
383             use YourModule qw(f1 f2);
384              
385             # explicitly import functions by tag (f2)
386             use YourModule qw(:a);
387              
388             # add per-import options: rename/add prefix/add suffix. both statements below
389             # will cause f2 to be exported as foo_f2_bar. while f1 is simply exported as
390             # f1.
391             use YourModule f2 => { as => 'foo_f2_bar' }, f1 => {};
392             use YourModule ':a' => { prefix => 'foo_', suffix => '_bar' }, f1=>{};
393              
394             # per-import option: timeout to limit execution of each invocation to 3
395             # seconds. requires Perinci::Sub::Wrapper and Perinci::Sub::Property::timeout.
396             use YourModule f2 => { timeout=>3 };
397              
398             # per-import option: change calling convention from named argument to
399             # positional. requires wrapping (Perinci::Sub::Wrapper).
400             use YourModule f2 => { args_as=>'array' };
401             # now instead of calling f2 with f2(a1=>3, a2=>4), you do f2(3, 4)
402              
403             # per-import option: retry on failure. requires wrapping
404             # (Perinci::Sub::Wrapper) and Perinci::Sub::Property::retry. See
405             # Perinci::Sub::Property::retry for more details.
406             use YourModule f2 => { retry=>3 };
407              
408             # XXX other per-import options
409              
410             # import option: set prefix/suffix for all imports. the statement below will
411             # import foo_f1_bar and foo_f2_bar.
412             use YourModule 'f1', 'f2', -prefix=>'foo', -suffix=>'bar';
413              
414             # import option: define behavior when an import clashes with existing symbol.
415             # the default is 'force' which, like Exporter, will force importing anyway
416             # without warning, overriding existing symbol. another option is to 'bail'
417             # (die).
418             use YourModule 'f1', 'f2', -on_clash=>'die';
419              
420             =head1 DESCRIPTION
421              
422             Perinci::Exporter is an exporter which can utilize information from L<Rinci>
423             metadata. If your package has Rinci metadata, consider using this exporter for
424             convenience and flexibility.
425              
426             Features of this module:
427              
428             =over 4
429              
430             =item * List exportable routines from Rinci metadata
431              
432             All functions which have metadata are assumed to be exportable, so you do not
433             have to list them again via C<@EXPORT> or C<@EXPORT_OK>.
434              
435             =item * Read tags from Rinci metadata
436              
437             The exporter can read tags from your function metadata. You do not have to
438             define export tags again.
439              
440             =item * Export to different name
441              
442             See the 'as', 'prefix', 'suffix' import options of the install_import()
443             function.
444              
445             =item * Export wrapped function
446              
447             This allows importer to get additional/modified behavior. See
448             L<Perinci::Sub::Wrapper> for more about wrapping.
449              
450             =item * Export differently wrapped function to different importers
451              
452             See some examples in L</"FAQ">.
453              
454             =item * Warn/bail on clash with existing function
455              
456             For testing or safety precaution.
457              
458             =item * Read @EXPORT and @EXPORT_OK
459              
460             Perinci::Exporter reads these two package variables, so it is quite compatible
461             with L<Exporter> and L<Exporter::Lite>. In fact, it is basically the same as
462             Exporter::Lite if you do not have any metadata for your functions.
463              
464             =back
465              
466             =head1 EXPORTING
467              
468             Most of the time, to set up exporter, you only need to just use() it in your
469             module:
470              
471             package YourModule;
472             use Perinci::Exporter;
473              
474             Perinci::Exporter will install an import() routine for your package. If you need
475             to pass some exporting options:
476              
477             use Perinci::Exporter default_exports=>[qw/foo bar/], ...;
478              
479             See install_import() for more details.
480              
481             =head1 IMPORTING
482              
483             B<Default exports>. Your module users can import functions in a variety of ways.
484             The simplest form is:
485              
486             use YourModule;
487              
488             which by default will export all functions marked with C<export:default> tags.
489             For example:
490              
491             package YourModule;
492             use Perinci::Exporter;
493             our %SPEC;
494             $SPEC{f1} = { v=>1.1, tags=>[qw/export:default a/] };
495             sub f1 { ... }
496             $SPEC{f2} = { v=>1.1, tags=>[qw/export:default a b/] };
497             sub f2 { ... }
498             $SPEC{f3} = { v=>1.1, tags=>[qw/b c/] };
499             sub f3 { ... }
500             $SPEC{f4} = { v=>1.1, tags=>[qw/a b c export:never/] };
501             sub f4 { ... }
502             1;
503              
504             YourModule will by default export C<f1> and C<f2>. If there are no functions
505             tagged with C<export:default>, there will be no default exports. You can also
506             supply the list of default functions via the C<default_exports> argument:
507              
508             use Perinci::Exporter default_exports => [qw/f1 f2/];
509              
510             or via the C<@EXPORT> package variable, like in Exporter.
511              
512             B<Importing individual functions>. Your module users can import individual
513             functions:
514              
515             use YourModule qw(f1 f2);
516              
517             Each function can have import options, specified in a hashref:
518              
519             use YourModule f1 => {wrap=>0}, f2=>{as=>'bar', args_as=>'array'};
520             # imports f1, bar
521              
522             B<Importing groups of functions by tags>. Your module users can import groups of
523             individual functions using tags. Tags are collected from function metadata, and
524             written with a C<:> prefix to differentiate them from function names. Each tag
525             can also have import options:
526              
527             use YourModule 'f3', ':a' => {prefix => 'a_'}; # imports f3, a_f1, a_f2
528              
529             Some tags are defined automatically: C<:default> (all functions that have the
530             C<export:default> tag), C<:all> (all functions).
531              
532             B<Importing to a different name>. As can be seen from previous examples, the
533             'as' and 'prefix' (and also 'suffix') import options can be used to import
534             subroutines using into a different name.
535              
536             B<Bailing on name clashes>. By default, importing will override existing names
537             in the target package. To warn about this, users can set '-on_clash' to 'bail':
538              
539             use YourModule 'f1', f2=>{as=>'f1'}, -on_clash=>'bail'; # dies, imports clash
540              
541             use YourModule 'f1', -on_clash=>'bail'; # dies, f1 already exists
542             sub f1 { ... }
543              
544             B<Customizing wrapping options>. Users can specify custom wrapping options when
545             importing functions. The wrapping will then be done just for them (as opposed to
546             wrapped functions which are wrapped using default options, which will be shared
547             among all importers not requesting custom wrapping). See some examples in
548             L</"FAQ">.
549              
550             See do_export() for more details.
551              
552             =head1 FUNCTIONS
553              
554             =head2 install_import(%args)
555              
556             The routine which installs the import() routine to caller package.
557              
558             Arguments:
559              
560             =over 4
561              
562             =item * into => STR (default: caller package)
563              
564             Explicitly set target package to install the import() routine to.
565              
566             =item * caller_level => INT (default: 0)
567              
568             If C<into> is not set, caller package will be used. The default is to use
569             caller(0), but the caller level can be set using this argument.
570              
571             =item * default_exports => ARRAY
572              
573             Default symbols to export.
574              
575             You can also set default exports by setting C<@EXPORT>.
576              
577             =item * extra_exports => ARRAY
578              
579             Other symbols to export (other than the ones having metadata and those specified
580             with C<default_exports> and C<@EXPORT>).
581              
582             You can also set default exports by setting C<@EXPORT_OK>.
583              
584             =item * default_wrap => BOOL (default: 1)
585              
586             Whether wrap subroutines by default.
587              
588             =item * default_on_clash => STR (default: 'force')
589              
590             What to do when clash of symbols happen.
591              
592             =back
593              
594             =head2 do_export($expopts, @args)
595              
596             The routine which implements the exporting. Will be called from the import()
597             routine. $expopts is a hashref containing exporter options, constructed by
598             install_import(). C<@args> is the same as arguments passed during import: a
599             sequence of function name or tag name (prefixed with C<:>), function/tag name
600             and export option (hashref), or option (prefixed with C<->).
601              
602             Example:
603              
604             do_export('f1', ':tag1', f2 => {import option...}, -option => ...);
605              
606             Import options:
607              
608             =over 4
609              
610             =item * as => STR
611              
612             Export a function to a new name. Will die if new name is invalid. Inapplicable
613             for tags.
614              
615             Example:
616              
617             use YourModule func => {as => 'f'};
618              
619             =item * prefix => STR
620              
621             Export function/tag with a prefix. Will die on invalid prefix.
622              
623             Example:
624              
625             use YourModule ':default' => {prefix => 'your_'};
626              
627             This means, C<foo>, C<bar>, etc. will be exported as C<your_foo>, C<your_bar>,
628             etc.
629              
630             =item * suffix => STR
631              
632             Export function/tag with a prefix. Will die on invalid suffix.
633              
634             Example:
635              
636             use YourModule ':default' => {suffix => '_s'};
637              
638             This means, C<foo>, C<bar>, etc. will be exported as C<foo_s>, C<bar_s>, etc.
639              
640             =item * wrap => 0 | 1 | HASH
641              
642             The default (when value of this option is unset>) is to export the
643             original/unwrapped functions, unless wrapping is necessary. Other options like
644             C<timeout>, C<retry>, C<convert>, C<args_as> require wrapping so they
645             automatically turn on wrapping.
646              
647             You can explicitly turn wrapping on unconditionally by setting the value of this
648             option to 1 (enable wrapping with default wrapping options) or a hashref that
649             will be passed to L<Perinci::Sub::Wrapper>'s C<wrap_sub()> to customize
650             wrapping.
651              
652             You can also explicitly disable wrapping by setting the value of this option to
653             0. If you also specify other options that require wrapping (for example,
654             C<retry>) an exception will be raised.
655              
656             Examples:
657              
658             use YourModule foo => {}; # export unwrapped, original function
659             use YourModule foo => {timeout=>30}; # export wrapped functions
660             use YourModule foo => {wrap=>1}; # export wrapped functions
661             use YourModule foo => {wrap=>0, timeout=>30}; # dies! 'timeout' option requires wrapping
662              
663             Note that when set to 0, the exported function might already be wrapped anyway,
664             e.g. when your module uses embedded wrapping (see
665             L<Dist::Zilla::Plugin::Rinci::Wrap>) or wrap its subroutines manually.
666              
667             Also note that wrapping will not be done if subroutine does not have metadata.
668              
669             =item * convert => HASH
670              
671             This is a shortcut for specifying:
672              
673             wrap => { convert => HASH }
674              
675             =item * args_as => STR
676              
677             This is a shortcut for specifying:
678              
679             wrap => { convert => { args_as => STR } }
680              
681             =item * result_naked => BOOL
682              
683             This is a shortcut for specifying:
684              
685             wrap => { convert => { result_naked => BOOL } }
686              
687             =item * curry => STR
688              
689             This is a shortcut for specifying:
690              
691             wrap => { convert => { curry => STR } }
692              
693             =back
694              
695             Options:
696              
697             =over 4
698              
699             =item * -on_clash => 'force' | 'bail' (default: from install_import()'s default_on_clash)
700              
701             If importer tries to import 'foo' when it already exists, the default is to
702             force importing, without any warnings, like Exporter. Alternatively, you can
703             also bail (dies), which can be more reliable/safe.
704              
705             =item * -prefix => STR
706              
707             Like C<prefix> import option, but to apply to all exports.
708              
709             =item * -suffix => STR
710              
711             Like C<suffix> import option, but to apply to all exports.
712              
713             =back
714              
715             =head1 FAQ
716              
717             =head2 Why use this module as my exporter?
718              
719             If you are fine with Exporter, Exporter::Lite, or L<Sub::Exporter>, then you
720             probably won't need this module.
721              
722             This module is particularly useful if you use Rinci metadata, in which case
723             you'll get some nice features. Some examples of the things you can do with this
724             exporter:
725              
726             =over 4
727              
728             =item * Change calling style from argument to positional
729              
730             use YourModule func => {args_as=>'array'};
731              
732             Then instead of:
733              
734             func(a => 1, b => 2);
735              
736             your function is called with positional arguments:
737              
738             func(1, 2);
739              
740             Note: this requires that the function's argument spec puts the C<pos>
741             information. For example:
742              
743             $SPEC{func} = {
744             v => 1.1,
745             args => {
746             a => { pos=>0 },
747             b => { pos=>1 },
748             }
749             };
750              
751             =item * Set timeout
752              
753             use YourModule ':all' => {wrap=>{convert=>{timeout=>10}}};
754              
755             This means all exported functions will be limited to 10s of execution time.
756              
757             Note: L<Perinci::Sub::property::timeout> (an optional dependency) is needed for
758             this.
759              
760             =item * Set retry
761              
762             use YourModule ':default' => {wrap=>{convert=>{retry=>3}}};
763              
764             This means all exported functions can autoretry up to 3 times.
765              
766             Note: L<Perinci::Sub::property::retry> (an optional dependency) is needed for
767             this.
768              
769             =item * Currying
770              
771             Sub::Exporter supports this. Perinci::Exporter does too:
772              
773             use YourModule f => {as=>'f_a10', wrap=>{convert=>{curry=>{a=>10}}}};
774              
775             This means:
776              
777             f_a10(); # equivalent to f(a=>10)
778             f_a10(b=>20, c=>30); # equivalent to f(a=>10, b=>20, c=>30)
779             f_a10(a=>5); # error, a is already set
780              
781             Note: L<Perinci::Sub::property::curry> (an optional dependency) is needed for
782             this.
783              
784             =back
785              
786             =head2 What happens to functions that do not have metadata?
787              
788             They can still be exported if you list them in C<@EXPORT> or C<@EXPORT_OK>.
789              
790             =head1 HOMEPAGE
791              
792             Please visit the project's homepage at L<https://metacpan.org/release/Perinci-Exporter>.
793              
794             =head1 SOURCE
795              
796             Source repository is at L<https://github.com/perlancar/perl-Perinci-Exporter>.
797              
798             =head1 BUGS
799              
800             Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-Exporter>
801              
802             When submitting a bug or request, please include a test-file or a
803             patch to an existing test-file that illustrates the bug or desired
804             feature.
805              
806             =head1 SEE ALSO
807              
808             L<Perinci>
809              
810             L<Perinci::Sub::Wrapper>
811              
812             If you want something simpler but also groks Rinci metadata, there's
813             L<Exporter::Rinci>. It's just like good old Exporter.pm, but wraps it so
814             C<@EXPORT>, C<@EXPORT_OK>, C<%EXPORT_TAGS> are filled from information from
815             Rinci metadata, if they are empty. You don't get wrapping, renaming, etc. If
816             Perinci::Exporter is like Sub::Exporter + Rinci, then Exporter::Rinci is like
817             Exporter.pm + Rinci.
818              
819             =head1 AUTHOR
820              
821             perlancar <perlancar@cpan.org>
822              
823             =head1 COPYRIGHT AND LICENSE
824              
825             This software is copyright (c) 2019, 2015, 2014, 2013, 2012 by perlancar@cpan.org.
826              
827             This is free software; you can redistribute it and/or modify it under
828             the same terms as the Perl 5 programming language system itself.
829              
830             =cut