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 |