Exporter/Util.pm

filter: Statementstmt 81.8% 72 / 88 Branchbran 85.2% 29 / 34 Conditioncond 100% 4 / 4 MC/DCmcdc 100% 2 / 2 Subroutinesub 80.9% 17 / 21 Podpod 83.3% 5 / 6 totaltotal 83.2% 129 / 155 CC 22 SCAR 15.0
CC
22
Cov
83%
__ANON__
9.0
__ANON__
7.0
__ANON__
6.0
CRAP 4.5
« Exporter.pm ↑ Summary
1 4 ▶use v5.12.0;
Subroutine BEGIN: called CC=1 SCAR=0.0
2 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 package Sub::Exporter::Util 0.992;
4 # ABSTRACT: utilities to make Sub::Exporter easier
5  
6 4 ▶use Data::OptList ();
Subroutine BEGIN: called CC=1 SCAR=0.0
7 4 ▶use Params::SomeUtil ();
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 #pod =head1 DESCRIPTION
10 #pod
11 #pod This module provides a number of utility functions for performing common or
12 #pod useful operations when setting up a Sub::Exporter configuration. All of the
13 #pod utilities may be exported, but none are by default.
14 #pod
15 #pod =head1 THE UTILITIES
16 #pod
17 #pod =head2 curry_method
18 #pod
19 #pod exports => {
20 #pod some_method => curry_method,
21 #pod }
22 #pod
23 #pod This utility returns a generator which will produce an invocant-curried version
24 #pod of a method. In other words, it will export a method call with the exporting
25 #pod class built in as the invocant.
26 #pod
27 #pod A module importing the code some the above example might do this:
28 #pod
29 #pod use Some::Module qw(some_method);
30 #pod
31 #pod my $x = some_method;
32 #pod
33 #pod This would be equivalent to:
34 #pod
35 #pod use Some::Module;
36 #pod
37 #pod my $x = Some::Module->some_method;
38 #pod
39 #pod If Some::Module is subclassed and the subclass's import method is called to
40 #pod import C<some_method>, the subclass will be curried in as the invocant.
41 #pod
42 #pod If an argument is provided for C<curry_method> it is used as the name of the
43 #pod curried method to export. This means you could export a Widget constructor
44 #pod like this:
45 #pod
46 #pod exports => { widget => curry_method('new') }
47 #pod
48 #pod This utility may also be called as C<curry_class>, for backwards compatibility.
49 #pod
50 #pod =cut
51  
52 2 ▶sub curry_method {
Subroutine curry_method: called CC=1 SCAR=0.0
Pod documented
53 2 my $override_name = shift;
54 4 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
55 4 my ($class, $name) = @_;
56 4 ▶ $name = $override_name if defined $override_name;
Branch: 1 branch
BranchTrueFalseTotal
if defined $override_name 2 2 4
57 4 ▶ sub { $class->$name(@_); };
Subroutine __ANON__: called CC=1 SCAR=0.0
58 }
59 2 }
60  
61 4 ▶BEGIN { *curry_class = \&curry_method; }
Subroutine BEGIN: called CC=1 SCAR=0.0
62  
63 #pod =head2 curry_chain
64 #pod
65 #pod C<curry_chain> behaves like C<L</curry_method>>, but is meant for generating
66 #pod exports that will call several methods in succession.
67 #pod
68 #pod exports => {
69 #pod reticulate => curry_chain(
70 #pod new => gather_data => analyze => [ detail => 100 ] => 'results'
71 #pod ),
72 #pod }
73 #pod
74 #pod If imported from Spliner, calling the C<reticulate> routine will be equivalent
75 #pod to:
76 #pod
77 #pod Spliner->new->gather_data->analyze(detail => 100)->results;
78 #pod
79 #pod If any method returns something on which methods may not be called, the routine
80 #pod croaks.
81 #pod
82 #pod The arguments to C<curry_chain> form an optlist. The names are methods to be
83 #pod called and the arguments, if given, are arrayrefs to be dereferenced and passed
84 #pod as arguments to those methods. C<curry_chain> returns a generator like those
85 #pod expected by Sub::Exporter.
86 #pod
87 #pod B<Achtung!> at present, there is no way to pass arguments from the generated
88 #pod routine to the method calls. This will probably be solved in future revisions
89 #pod by allowing the opt list's values to be subroutines that will be called with
90 #pod the generated routine's stack.
91 #pod
92 #pod =cut
93  
94 3 ▶sub curry_chain {
Subroutine curry_chain: called CC=1 SCAR=0.0
Pod documented
95 # In the future, we can make \%arg an optional prepend, like the "special"
96 # args to the default Sub::Exporter-generated import routine.
97 3 my (@opt_list) = @_;
98  
99 3 my $pairs = Data::OptList::mkopt(\@opt_list, 'args', 'ARRAY');
100  
101 3 ▶ sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
102 3 my ($class) = @_;
103  
104 3 ▶ sub {
Subroutine __ANON__: called CC=7 SCAR=19.5
105 3 my $next = $class;
106  
107 3 for my $i (0 .. $#$pairs) {
108 8 my $pair = $pairs->[ $i ];
109  
110 8 ▶ unless (Params::SomeUtil::_INVOCANT($next)) { ## no critic Private
Branch: 1 branch
BranchTrueFalseTotal
unless (&Params::SomeUtil::_INVOCANT($next)) 2 6 8
111 2 ▶ my $str = defined $next ? "'$next'" : 'undef';
Branch: 1 branch
BranchTrueFalseTotal
defined $next ? : 1 1 2
112 2 Carp::croak("can't call $pair->[0] on non-invocant $str")
113 }
114  
115 6 my ($method, $args) = @$pair;
116  
117 6 ▶ if ($i == $#$pairs) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i == $pairs->$#*) { } 1 5 6
118 1 ▶ return $next->$method($args ? @$args : ());
Branch: 1 branch
BranchTrueFalseTotal
$args ? : 0 1 1
119 } else {
120 5 ▶ $next = $next->$method($args ? @$args : ());
Branch: 1 branch
BranchTrueFalseTotal
$args ? : 3 2 5
121 }
122 }
123 3 };
124 }
125 3 }
126  
127 # =head2 name_map
128 #
129 # This utility returns an list to be used in specify export generators. For
130 # example, the following:
131 #
132 # exports => {
133 # name_map(
134 # '_?_gen' => [ qw(fee fie) ],
135 # '_make_?' => [ qw(foo bar) ],
136 # ),
137 # }
138 #
139 # is equivalent to:
140 #
141 # exports => {
142 # name_map(
143 # fee => \'_fee_gen',
144 # fie => \'_fie_gen',
145 # foo => \'_make_foo',
146 # bar => \'_make_bar',
147 # ),
148 # }
149 #
150 # This can save a lot of typing, when providing many exports with similarly-named
151 # generators.
152 #
153 # =cut
154 #
155 # sub name_map {
156 # my (%groups) = @_;
157 #
158 # my %map;
159 #
160 # while (my ($template, $names) = each %groups) {
161 # for my $name (@$names) {
162 # (my $export = $template) =~ s/\?/$name/
163 # or Carp::croak 'no ? found in name_map template';
164 #
165 # $map{ $name } = \$export;
166 # }
167 # }
168 #
169 # return %map;
170 # }
171  
172 #pod =head2 merge_col
173 #pod
174 #pod exports => {
175 #pod merge_col(defaults => {
176 #pod twiddle => \'_twiddle_gen',
177 #pod tweak => \&_tweak_gen,
178 #pod }),
179 #pod }
180 #pod
181 #pod This utility wraps the given generator in one that will merge the named
182 #pod collection into its args before calling it. This means that you can support a
183 #pod "default" collector in multiple exports without writing the code each time.
184 #pod
185 #pod You can specify as many pairs of collection names and generators as you like.
186 #pod
187 #pod =cut
188  
189 1 ▶sub merge_col {
Subroutine merge_col: called CC=3 SCAR=11.0
Pod documented
190 1 my (%groups) = @_;
191  
192 1 my %merged;
193  
194 1 ▶ while (my ($default_name, $group) = each %groups) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %groups) 3 1 4
195 3 ▶ while (my ($export_name, $gen) = each %$group) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$group) 5 3 8
196 5 ▶ $merged{$export_name} = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
197 5 my ($class, $name, $arg, $col) = @_;
198  
199 my $merged_arg = exists $col->{$default_name}
200 5 ▶ ? { %{ $col->{$default_name} }, %$arg }
Branch: 1 branch
BranchTrueFalseTotal
exists $col->{$default_name} ? : 3 2 5
201 : $arg;
202  
203 5 ▶ if (Params::SomeUtil::_CODELIKE($gen)) { ## no critic Private
Branch: 1 branch
BranchTrueFalseTotal
if (&Params::SomeUtil::_CODELIKE($gen)) { } 4 1 5
204 4 $gen->($class, $name, $merged_arg, $col);
205 } else {
206 1 $class->$$gen($name, $merged_arg, $col);
207 }
208 }
209 5 }
210 }
211  
212 1 return %merged;
213 }
214  
215 #pod =head2 mixin_installer
216 #pod
217 #pod use Sub::Exporter -setup => {
218 #pod installer => Sub::Exporter::Util::mixin_installer,
219 #pod exports => [ qw(foo bar baz) ],
220 #pod };
221 #pod
222 #pod This utility returns an installer that will install into a superclass and
223 #pod adjust the ISA importing class to include the newly generated superclass.
224 #pod
225 #pod If the target of importing is an object, the hierarchy is reversed: the new
226 #pod class will be ISA the object's class, and the object will be reblessed.
227 #pod
228 #pod B<Prerequisites>: This utility requires that Package::Generator be installed.
229 #pod
230 #pod =cut
231  
232 0 ▶sub __mixin_class_for {
Subroutine __mixin_class_for: not called CC=2 SCAR=13.7
233 0 my ($class, $mix_into) = @_;
234 0 require Package::Generator;
235 0 my $mixin_class = Package::Generator->new_package({
236 base => "$class\:\:__mixin__",
237 });
238  
239 ## no critic (ProhibitNoStrict)
240 4 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
241 0 ▶ if (ref $mix_into) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $mix_into) { } 0 0 0
242 0 unshift @{"$mixin_class" . "::ISA"}, ref $mix_into;
243 } else {
244 0 unshift @{"$mix_into" . "::ISA"}, $mixin_class;
245 }
246 0 return $mixin_class;
247 }
248  
249 0 ▶sub mixin_installer {
Subroutine mixin_installer: not called CC=1 SCAR=6.9
Pod documented
250 0 ▶ sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
251 0 my ($arg, $to_export) = @_;
252  
253 0 my $mixin_class = __mixin_class_for($arg->{class}, $arg->{into});
254 0 ▶ bless $arg->{into} => $mixin_class if ref $arg->{into};
Branch: 1 branch
BranchTrueFalseTotal
if ref $arg->{"into"} 0 0 0
255  
256 0 Sub::Exporter::default_installer(
257 { %$arg, into => $mixin_class },
258 $to_export,
259 );
260 0 };
261 }
262  
263 0 ▶sub mixin_exporter {
Subroutine mixin_exporter: not called CC=1 SCAR=6.9
Pod undocumented
264 0 Carp::cluck "mixin_exporter is deprecated; use mixin_installer instead; it behaves identically";
265 0 return mixin_installer;
266 }
267  
268 #pod =head2 like
269 #pod
270 #pod It's a collector that adds imports for anything like given regex.
271 #pod
272 #pod If you provide this configuration:
273 #pod
274 #pod exports => [ qw(igrep imap islurp exhausted) ],
275 #pod collectors => { -like => Sub::Exporter::Util::like },
276 #pod
277 #pod A user may import from your module like this:
278 #pod
279 #pod use Your::Iterator -like => qr/^i/; # imports igre, imap, islurp
280 #pod
281 #pod or
282 #pod
283 #pod use Your::Iterator -like => [ qr/^i/ => { -prefix => 'your_' } ];
284 #pod
285 #pod The group-like prefix and suffix arguments are respected; other arguments are
286 #pod passed on to the generators for matching exports.
287 #pod
288 #pod =cut
289  
290 2 ▶sub like {
Subroutine like: called CC=1 SCAR=0.0
Pod documented
291 6 ▶ sub {
Subroutine __ANON__: called CC=9 SCAR=22.0
292 6 my ($value, $arg) = @_;
293 6 ▶ Carp::croak "no regex supplied to regex group generator" unless $value;
Branch: 1 branch
BranchTrueFalseTotal
unless $value 1 5 6
294  
295 # Oh, qr//, how you bother me! See the p5p thread from around now about
296 # fixing this problem... too bad it won't help me. -- rjbs, 2006-04-25
297 5 ▶ my @values = eval { $value->isa('Regexp') } ? ($value, undef)
Branch: 1 branch
BranchTrueFalseTotal
eval { do { $value->isa('Regexp') } } ? : 1 4 5
298 : @$value;
299  
300 5 ▶ while (my ($re, $opt) = splice @values, 0, 2) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@values, 0, 2)) 6 4 10
301 Carp::croak "given pattern for regex group generater is not a Regexp"
302 6 ▶ unless eval { $re->isa('Regexp') };
Branch: 1 branch
BranchTrueFalseTotal
unless eval { do { $re->isa("Regexp") } } 1 5 6
303 5 my @exports = keys %{ $arg->{config}->{exports} };
304 5 my @matching = grep { $_ =~ $re } @exports;
305  
306 5 ▶ my %merge = $opt ? %$opt : ();
Branch: 1 branch
BranchTrueFalseTotal
$opt ? : 2 3 5
307 5 ▶ my $prefix = (delete $merge{-prefix}) || '';
Condition100%2/2
delete $merge{'-prefix'} || ''
l!l
14
MC/DC100%1/1
delete $merge{'-prefix'} || ''
delete $merge{'-prefix'}
Truth table100%2/2
A
A= delete $merge{'-prefix'}
Aresult
11
00
308 5 ▶ my $suffix = (delete $merge{-suffix}) || '';
Condition100%2/2
delete $merge{'-suffix'} || ''
l!l
14
MC/DC100%1/1
delete $merge{'-suffix'} || ''
delete $merge{'-suffix'}
Truth table100%2/2
A
A= delete $merge{'-suffix'}
Aresult
11
00
309  
310 5 for my $name (@matching) {
311 13 my $as = $prefix . $name . $suffix;
312 13 push @{ $arg->{import_args} }, [ $name => { %merge, -as => $as } ];
313 }
314 }
315  
316 4 1;
317 }
318 2 }
319  
320 4 ▶use Sub::Exporter -setup => {
Subroutine BEGIN: called CC=1 SCAR=0.0
321 exports => [ qw(
322 like
323 name_map
324 merge_col
325 curry_method curry_class
326 curry_chain
327 mixin_installer mixin_exporter
328 ) ]
329 4 };
330  
331 4 1;
332  
333 __END__
« Exporter.pm ↑ Summary