blib/lib/Venus/Gather.pm

filter: Statementstmt 96.2% 154 / 160 Branchbran 77.5% 45 / 58 Conditioncond 65.0% 13 / 20 MC/DCmcdc 30.7% 4 / 13 Subroutinesub 100% 39 / 39 Podpod 94.7% 18 / 19 totaltotal 88.3% 273 / 309 CC 39 SCAR 17.4
CC
39
Cov
89%
result
13.0
__ANON__
12.0
__ANON__
8.8
CRAP 5.7
« blib/lib/Venus/Range.pm ↑ Summary blib/lib/Venus/Role/Optional.pm »
1 package Venus::Gather;
2  
3 2 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 2 ▶use Venus::Class 'attr', 'base', 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 2 base 'Venus::Kind::Utility';
15  
16 # INTEGRATES
17  
18 2 with 'Venus::Role::Valuable';
19 2 with 'Venus::Role::Buildable';
20 2 with 'Venus::Role::Accessible';
21  
22 2 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
23  
24 # ATTRIBUTES
25  
26 2 attr 'on_none';
27 2 attr 'on_only';
28 2 attr 'on_then';
29 2 attr 'on_when';
30  
31 # BUILDERS
32  
33 48 ▶sub build_self {
Subroutine build_self: called CC=5 SCAR=17.0
Pod undocumented
34 48 my ($self, $data) = @_;
35  
36 48 ▶ $self->on_none(sub{}) if !$self->on_none;
Subroutine __ANON__: called CC=1 SCAR=0.4
Branch: 1 branch
BranchTrueFalseTotal
unless $self->on_none 48 0 48
37 48 ▶ $self->on_only(sub{1}) if !$self->on_only;
Subroutine __ANON__: called CC=1 SCAR=0.2
Branch: 1 branch
BranchTrueFalseTotal
unless $self->on_only 48 0 48
38 48 ▶ $self->on_then([]) if !$self->on_then;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->on_then 48 0 48
39 48 ▶ $self->on_when([]) if !$self->on_when;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->on_when 48 0 48
40  
41 48 return $self;
42 }
43  
44 # METHODS
45  
46 1 ▶sub clear {
Subroutine clear: called CC=1 SCAR=0.0
Pod documented
47 1 my ($self) = @_;
48  
49 1 ▶ $self->on_none(sub{});
Subroutine __ANON__: called CC=1 SCAR=0.0
50 1 ▶ $self->on_only(sub{1});
Subroutine __ANON__: called CC=1 SCAR=0.0
51 1 $self->on_then([]);
52 1 $self->on_when([]);
53  
54 1 return $self;
55 }
56  
57 1 ▶sub count {
Subroutine count: called CC=1 SCAR=0.0
Pod documented
58 1 my ($self, @args) = @_;
59  
60 1 my $result = $self->result(@args);
61  
62 1 return scalar @$result;
63 }
64  
65 4 ▶sub data {
Subroutine data: called CC=2 SCAR=6.9
Pod documented
66 4 my ($self, $data) = @_;
67  
68 4 ▶ while(my($key, $value) = each(%$data)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$data) 17 4 21
69 17 $self->just($key)->then($value);
70 }
71  
72 4 return $self;
73 }
74  
75 1 ▶sub defined {
Subroutine defined: called CC=1 SCAR=0.0
Pod documented
76 1 my ($self) = @_;
77  
78 1 ▶ $self->when(sub{CORE::defined($_[0])});
Subroutine __ANON__: called CC=1 SCAR=0.0
79  
80 1 return $self;
81 }
82  
83 14 ▶sub expr {
Subroutine expr: called CC=1 SCAR=0.3
Pod documented
84 14 my ($self, $topic) = @_;
85  
86 83 ▶ $self->when(sub{
Subroutine __ANON__: called CC=9 SCAR=24.8
87 83 my $value = $_[0];
88  
89 83 ▶ if (!CORE::defined($value)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $value) 0 83 83
90 0 return false;
91 }
92 83 ▶ if (Scalar::Util::blessed($value) && !overload::Overloaded($value)) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($value) and not overload::Overloaded($value)) 0 83 83
Condition33%1/3
builtin::blessed($value) and not overload::Overloaded($value)
!ll&&!rl&&r
8300
MC/DC0%0/2
builtin::blessed($value) and not overload::Overloaded($value)
builtin::blessed($value) not overload::Overloaded($value)
Truth table33%1/3
A and not(B)
A= builtin::blessed($value)B= not overload::Overloaded($value)
ABresult
0X0
100
111
93 0 return false;
94 }
95 83 ▶ if (!Scalar::Util::blessed($value) && ref($value)) {
Branch: 1 branch
BranchTrueFalseTotal
if (not builtin::blessed($value) and ref $value) 0 83 83
Condition33%1/3
not builtin::blessed($value) and ref $value
!ll&&!rl&&r
0830
MC/DC0%0/2
not builtin::blessed($value) and ref $value
not builtin::blessed($value) ref $value
Truth table33%1/3
not(A) and B
A= not builtin::blessed($value)B= ref $value
ABresult
0X0
100
111
96 0 return false;
97 }
98 83 ▶ if (ref($topic) eq 'Regexp' && "$value" =~ qr/$topic/) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $topic eq 'Regexp' and "$value" =~ qr/$topic/u) { } 28 55 83
elsif ("$value" eq "$topic") { } 1 54 55
Condition100%3/3
ref $topic eq "Regexp" and "$value" =~ qr/$topic/u
!ll&&!rl&&r
104528
MC/DC100%2/2
ref $topic eq "Regexp" and "$value" =~ qr/$topic/u
ref $topic eq "Regexp" "$value" =~ qr/$topic/u
Truth table100%3/3
A and B
A= ref $topic eq "Regexp"B= "$value" =~ qr/$topic/u
ABresult
0X0
100
111
99 28 return true;
100 }
101 elsif ("$value" eq "$topic") {
102 1 return true;
103 }
104 else {
105 54 return false;
106 }
107 14 });
108  
109 14 return $self;
110 }
111  
112 64 ▶sub just {
Subroutine just: called CC=1 SCAR=0.3
Pod documented
113 64 my ($self, $topic) = @_;
114  
115 365 ▶ $self->when(sub{
Subroutine __ANON__: called CC=7 SCAR=21.8
116 365 my $value = $_[0];
117  
118 365 ▶ if (!CORE::defined($value)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $value) 0 365 365
119 0 return false;
120 }
121 365 ▶ if (Scalar::Util::blessed($value) && !overload::Overloaded($value)) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($value) and not overload::Overloaded($value)) 0 365 365
Condition66%2/3
builtin::blessed($value) and not overload::Overloaded($value)
!ll&&!rl&&r
319460
MC/DC0%0/2
builtin::blessed($value) and not overload::Overloaded($value)
builtin::blessed($value) not overload::Overloaded($value)
Truth table66%2/3
A and not(B)
A= builtin::blessed($value)B= not overload::Overloaded($value)
ABresult
0X0
100
111
122 0 return false;
123 }
124 365 ▶ if (!Scalar::Util::blessed($value) && ref($value)) {
Branch: 1 branch
BranchTrueFalseTotal
if (not builtin::blessed($value) and ref $value) 0 365 365
Condition66%2/3
not builtin::blessed($value) and ref $value
!ll&&!rl&&r
463190
MC/DC0%0/2
not builtin::blessed($value) and ref $value
not builtin::blessed($value) ref $value
Truth table66%2/3
not(A) and B
A= not builtin::blessed($value)B= ref $value
ABresult
0X0
100
111
125 0 return false;
126 }
127 365 ▶ if ("$value" eq "$topic") {
Branch: 1 branch
BranchTrueFalseTotal
if ("$value" eq "$topic") { } 37 328 365
128 37 return true;
129 }
130 else {
131 328 return false;
132 }
133 64 });
134  
135 64 return $self;
136 }
137  
138 6 ▶sub none {
Subroutine none: called CC=2 SCAR=6.9
Pod documented
139 6 my ($self, $code) = @_;
140  
141 6 ▶ $self->on_none(UNIVERSAL::isa($code, 'CODE') ? $code : sub{$code});
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
UNIVERSAL::isa($code, 'CODE') ? : 3 3 6
142  
143 6 return $self;
144 }
145  
146 1 ▶sub object {
Subroutine object: called CC=1 SCAR=0.0
Pod documented
147 1 my ($self) = @_;
148  
149 1 require Scalar::Util;
150  
151 1 ▶ $self->when(sub{Scalar::Util::blessed($_[0])});
Subroutine __ANON__: called CC=1 SCAR=0.0
152  
153 1 return $self;
154 }
155  
156 2 ▶sub only {
Subroutine only: called CC=1 SCAR=0.0
Pod documented
157 2 my ($self, $code) = @_;
158  
159 2 $self->on_only($code);
160  
161 2 return $self;
162 }
163  
164 1 ▶sub reduce {
Subroutine reduce: called CC=1 SCAR=0.0
Pod documented
165 1 my ($self, @args) = @_;
166  
167 1 my $result = $self->new(scalar $self->result(@args));
168  
169 1 return $result;
170 }
171  
172 40 ▶sub result {
Subroutine result: called CC=13 SCAR=25.7
Pod documented
173 40 my ($self, $data) = @_;
174  
175 40 ▶ $self->value(ref $data eq 'ARRAY' ? $data : [$data]) if $data;
Branch: 2 branches
BranchTrueFalseTotal
if $data 12 28 40
ref $data eq 'ARRAY' ? : 7 5 12
176  
177 40 my $value = $self->value;
178 40 my $result = [];
179 40 my $matched = 0;
180  
181 40 local $_ = $value;
182 40 ▶ if (!$self->on_only->($value)) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->on_only->($value)) 1 39 40
183 1 local $_ = $value;
184 1 ▶ $result = $self->on_none->($value) || [];
Condition50%1/2
$self->on_none->($value) || []
l!l
01
MC/DC0%0/1
$self->on_none->($value) || []
$self->on_none->($value)
Truth table50%1/2
A
A= $self->on_none->($value)
Aresult
11
00
185 1 ▶ return wantarray ? ($result, $matched) : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
186 }
187  
188 39 for my $item (@$value) {
189 278 local $_ = $item;
190 278 ▶ for (my $i = 0; $i < @{$self->on_when}; $i++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @{$self->on_when;}) 502 201 703
191 502 ▶ if ($self->on_when->[$i]->($item)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->on_when->[$i]->($item)) 77 425 502
192 77 push @$result, $self->on_then->[$i]->($item);
193 77 $matched++;
194 77 last;
195 }
196 }
197 }
198  
199 39 ▶ if (!@$result) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@$result) 10 29 39
200 10 local $_ = $value;
201 10 my @return = ($self->on_none->($value));
202 push @$result,
203 10 ▶ ((@return == 1 && ref($return[0]) eq 'ARRAY') ? @{$return[0]} : @return);
Branch: 1 branch
BranchTrueFalseTotal
@return == 1 && ref $return[0] eq 'ARRAY' ? : 1 9 10
Condition100%3/3
@return == 1 and ref $return[0] eq "ARRAY"
!ll&&!rl&&r
631
MC/DC100%2/2
@return == 1 and ref $return[0] eq "ARRAY"
@return == 1 ref $return[0] eq "ARRAY"
Truth table100%3/3
A and B
A= @return == 1B= ref $return[0] eq "ARRAY"
ABresult
0X0
100
111
204 }
205  
206 39 ▶ return wantarray ? ($result, $matched) : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 2 37 39
207 }
208  
209 1 ▶sub skip {
Subroutine skip: called CC=1 SCAR=0.0
Pod documented
210 1 my ($self) = @_;
211  
212 1 ▶ $self->then(sub{return ()});
Subroutine __ANON__: called CC=1 SCAR=0.0
213  
214 1 return $self;
215 }
216  
217 7 ▶sub take {
Subroutine take: called CC=1 SCAR=0.0
Pod documented
218 7 my ($self) = @_;
219  
220 7 ▶ $self->then(sub{return (@_)});
Subroutine __ANON__: called CC=1 SCAR=0.0
221  
222 7 return $self;
223 }
224  
225 2 ▶sub test {
Subroutine test: called CC=5 SCAR=16.1
Pod documented
226 2 my ($self) = @_;
227  
228 2 my $matched = 0;
229  
230 2 my $value = $self->value;
231  
232 2 local $_ = $value;
233 2 ▶ return $matched if !$self->on_only->($value);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->on_only->($value) 0 2 2
234  
235 2 for my $item (@$value) {
236 20 local $_ = $item;
237 20 ▶ for (my $i = 0; $i < @{$self->on_when}; $i++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @{$self->on_when;}) 39 18 57
238 39 ▶ if ($self->on_when->[$i]->($item)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->on_when->[$i]->($item)) 2 37 39
239 2 $matched++;
240 2 last;
241 }
242 }
243 }
244  
245 2 return $matched;
246 }
247  
248 94 ▶sub then {
Subroutine then: called CC=2 SCAR=6.9
Pod documented
249 94 my ($self, $code) = @_;
250  
251 94 my $next = $#{$self->on_when};
252  
253 94 ▶ $self->on_then->[$next] = UNIVERSAL::isa($code, 'CODE') ? $code : sub{$code};
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
UNIVERSAL::isa($code, 'CODE') ? : 20 74 94
254  
255 94 return $self;
256 }
257  
258 2 ▶sub type {
Subroutine type: called CC=1 SCAR=0.0
Pod documented
259 2 my ($self, $expr) = @_;
260  
261 2 require Venus::Type;
262  
263 2 ▶ $self->when(sub{Venus::Type->new->check($expr)->eval($_[0])});
Subroutine __ANON__: called CC=1 SCAR=0.0
264  
265 2 return $self;
266 }
267  
268 93 ▶sub when {
Subroutine when: called CC=2 SCAR=7.0
Pod documented
269 93 my ($self, $code, @args) = @_;
270  
271 93 ▶ my $next = (@{$self->on_when}-$#{$self->on_then}) > 1 ? -1 : @{$self->on_when};
Branch: 1 branch
BranchTrueFalseTotal
@{$self->on_when;} - $#{$self->on_then;} > 1 ? : 0 93 93
272  
273 541 ▶ $self->on_when->[$next] = sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
274 541 (local $_ = $_[0])->$code(@args);
275 93 };
276  
277 93 return $self;
278 }
279  
280 6 ▶sub where {
Subroutine where: called CC=1 SCAR=0.0
Pod documented
281 6 my ($self) = @_;
282  
283 6 my $where = $self->new;
284  
285 6 ▶ $self->then(sub{@{scalar($where->result(@_))}});
Subroutine __ANON__: called CC=1 SCAR=0.0
286  
287 6 return $where;
288 }
289  
290 2 1;
291  
292  
293  
294 =head1 NAME
295  
296 Venus::Gather - Gather Class
297  
298 =cut
299  
300 =head1 ABSTRACT
301  
302 Gather Class for Perl 5
303  
304 =cut
305  
306 =head1 SYNOPSIS
307  
308 package main;
309  
310 use Venus::Gather;
311  
312 my $gather = Venus::Gather->new([
313 "one",
314 "two",
315 "three",
316 "four",
317 "five",
318 "six",
319 "seven",
320 "eight",
321 "nine",
322 "zero",
323 ]);
324  
325 $gather->when(sub{$_ eq 1})->then(sub{"one"});
326 $gather->when(sub{$_ eq 2})->then(sub{"two"});
327  
328 $gather->none(sub{"?"});
329  
330 my $result = $gather->result;
331  
332 # ["?"]
333  
334 =cut
335  
336 =head1 DESCRIPTION
337  
338 This package provides an object-oriented interface for complex pattern matching
339 operations on collections of data, e.g. array references. See L<Venus::Match>
340 for operating on scalar values.
341  
342 =cut
343  
344 =head1 ATTRIBUTES
345  
346 This package has the following attributes:
347  
348 =cut
349  
350 =head2 on_none
351  
352 on_none(CodeRef)
353  
354 This attribute is read-write, accepts C<(CodeRef)> values, is optional, and defaults to C<sub{}>.
355  
356 =cut
357  
358 =head2 on_only
359  
360 on_only(CodeRef)
361  
362 This attribute is read-write, accepts C<(CodeRef)> values, is optional, and defaults to C<sub{1}>.
363  
364 =cut
365  
366 =head2 on_then
367  
368 on_then(ArrayRef[CodeRef])
369  
370 This attribute is read-write, accepts C<(ArrayRef[CodeRef])> values, is optional, and defaults to C<[]>.
371  
372 =cut
373  
374 =head2 on_when
375  
376 on_when(ArrayRef[CodeRef])
377  
378 This attribute is read-write, accepts C<(ArrayRef[CodeRef])> values, is optional, and defaults to C<[]>.
379  
380 =cut
381  
382 =head1 INHERITS
383  
384 This package inherits behaviors from:
385  
386 L<Venus::Kind::Utility>
387  
388 =cut
389  
390 =head1 INTEGRATES
391  
392 This package integrates behaviors from:
393  
394 L<Venus::Role::Accessible>
395  
396 L<Venus::Role::Buildable>
397  
398 L<Venus::Role::Valuable>
399  
400 =cut
401  
402 =head1 METHODS
403  
404 This package provides the following methods:
405  
406 =cut
407  
408 =head2 clear
409  
410 clear() (Venus::Gather)
411  
412 The clear method resets all gather conditions and returns the invocant.
413  
414 I<Since C<1.55>>
415  
416 =over 4
417  
418 =item clear example 1
419  
420 # given: synopsis
421  
422 package main;
423  
424 my $clear = $gather->clear;
425  
426 # bless(..., "Venus::Gather")
427  
428 =back
429  
430 =cut
431  
432 =head2 count
433  
434 count(any $data) (number)
435  
436 The count method calls L</result> and returns the number of items gathered.
437  
438 I<Since C<4.15>>
439  
440 =over 4
441  
442 =item count example 1
443  
444 package main;
445  
446 use Venus::Gather;
447  
448 my $gather = Venus::Gather->new([
449 "one",
450 "two",
451 "three",
452 "four",
453 "five",
454 "six",
455 "seven",
456 "eight",
457 "nine",
458 "zero",
459 ]);
460  
461 $gather->expr(qr/^t/)->take;
462  
463 my $result = $gather->count;
464  
465 # 2
466  
467 =back
468  
469 =cut
470  
471 =head2 data
472  
473 data(hashref $data) (Venus::Gather)
474  
475 The data method takes a hashref (i.e. lookup table) and creates gather
476 conditions and actions based on the keys and values found.
477  
478 I<Since C<1.55>>
479  
480 =over 4
481  
482 =item data example 1
483  
484 package main;
485  
486 use Venus::Gather;
487  
488 my $gather = Venus::Gather->new([
489 "one",
490 "two",
491 "three",
492 "four",
493 "five",
494 "six",
495 "seven",
496 "eight",
497 "nine",
498 "zero",
499 ]);
500  
501 $gather->data({
502 "one" => 1,
503 "two" => 2,
504 "three" => 3,
505 "four" => 4,
506 "five" => 5,
507 "six" => 6,
508 "seven" => 7,
509 "eight" => 8,
510 "nine" => 9,
511 "zero" => 0,
512 });
513  
514 my $result = $gather->none('?')->result;
515  
516 # [1..9, 0]
517  
518 =back
519  
520 =over 4
521  
522 =item data example 2
523  
524 package main;
525  
526 use Venus::Gather;
527  
528 my $gather = Venus::Gather->new([
529 "one",
530 "two",
531 "three",
532 "four",
533 "five",
534 "six",
535 "seven",
536 "eight",
537 "nine",
538 "zero",
539 ]);
540  
541 $gather->data({
542 "zero" => 0,
543 });
544  
545 my $result = $gather->none('?')->result;
546  
547 # [0]
548  
549 =back
550  
551 =cut
552  
553 =head2 defined
554  
555 defined() (Venus::Gather)
556  
557 The defined method registers a L</when> condition which only allows matching if
558 the value presented is C<defined>.
559  
560 I<Since C<4.15>>
561  
562 =over 4
563  
564 =item defined example 1
565  
566 package main;
567  
568 use Venus::Gather;
569  
570 my $gather = Venus::Gather->new;
571  
572 $gather->defined->take;
573  
574 my $result = $gather->result([0, "", undef, false]);
575  
576 # [0, "", false]
577  
578 =back
579  
580 =cut
581  
582 =head2 expr
583  
584 expr(string | regexp $expr) (Venus::Gather)
585  
586 The expr method registers a L</when> condition that check if the match value is
587 an exact string match of the C<$topic> if the topic is a string, or that it
588 matches against the topic if the topic is a regular expression.
589  
590 I<Since C<1.55>>
591  
592 =over 4
593  
594 =item expr example 1
595  
596 package main;
597  
598 use Venus::Gather;
599  
600 my $gather = Venus::Gather->new([
601 "one",
602 "two",
603 "three",
604 "four",
605 "five",
606 "six",
607 "seven",
608 "eight",
609 "nine",
610 "zero",
611 ]);
612  
613 $gather->expr('one')->then(sub{[split //]});
614  
615 my $result = $gather->result;
616  
617 # [["o", "n", "e"]]
618  
619 =back
620  
621 =over 4
622  
623 =item expr example 2
624  
625 package main;
626  
627 use Venus::Gather;
628  
629 my $gather = Venus::Gather->new([
630 "one",
631 "two",
632 "three",
633 "four",
634 "five",
635 "six",
636 "seven",
637 "eight",
638 "nine",
639 "zero",
640 ]);
641  
642 $gather->expr(qr/^o/)->then(sub{[split //]});
643  
644 my $result = $gather->result;
645  
646 # [["o", "n", "e"]]
647  
648 =back
649  
650 =cut
651  
652 =head2 just
653  
654 just(string $topic) (Venus::Gather)
655  
656 The just method registers a L</when> condition that check if the match value is
657 an exact string match of the C<$topic> provided.
658  
659 I<Since C<1.55>>
660  
661 =over 4
662  
663 =item just example 1
664  
665 package main;
666  
667 use Venus::Gather;
668  
669 my $gather = Venus::Gather->new([
670 "one",
671 "two",
672 "three",
673 "four",
674 "five",
675 "six",
676 "seven",
677 "eight",
678 "nine",
679 "zero",
680 ]);
681  
682 $gather->just('one')->then(1);
683 $gather->just('two')->then(2);
684 $gather->just('three')->then(3);
685  
686 my $result = $gather->result;
687  
688 # [1,2,3]
689  
690 =back
691  
692 =over 4
693  
694 =item just example 2
695  
696 package main;
697  
698 use Venus::Gather;
699 use Venus::String;
700  
701 my $gather = Venus::Gather->new([
702 Venus::String->new("one"),
703 Venus::String->new("two"),
704 Venus::String->new("three"),
705 Venus::String->new("four"),
706 Venus::String->new("five"),
707 Venus::String->new("six"),
708 Venus::String->new("seven"),
709 Venus::String->new("eight"),
710 Venus::String->new("nine"),
711 Venus::String->new("zero"),
712 ]);
713  
714 $gather->just('one')->then(1);
715 $gather->just('two')->then(2);
716 $gather->just('three')->then(3);
717  
718 my $result = $gather->result;
719  
720 # [1,2,3]
721  
722 =back
723  
724 =over 4
725  
726 =item just example 3
727  
728 package main;
729  
730 use Venus::Gather;
731 use Venus::String;
732  
733 my $gather = Venus::Gather->new([
734 Venus::String->new("one"),
735 Venus::String->new("two"),
736 Venus::String->new("three"),
737 Venus::String->new("four"),
738 Venus::String->new("five"),
739 Venus::String->new("six"),
740 Venus::String->new("seven"),
741 Venus::String->new("eight"),
742 Venus::String->new("nine"),
743 Venus::String->new("zero"),
744 ]);
745  
746 $gather->just('one')->then(1);
747 $gather->just('six')->then(6);
748  
749 my $result = $gather->result;
750  
751 # [1,6]
752  
753 =back
754  
755 =cut
756  
757 =head2 new
758  
759 new(any @args) (Venus::Gather)
760  
761 The new method constructs an instance of the package.
762  
763 I<Since C<4.15>>
764  
765 =over 4
766  
767 =item new example 1
768  
769 package main;
770  
771 use Venus::Gather;
772  
773 my $new = Venus::Gather->new;
774  
775 # bless(..., "Venus::Gather")
776  
777 =back
778  
779 =over 4
780  
781 =item new example 2
782  
783 package main;
784  
785 use Venus::Gather;
786  
787 my $new = Venus::Gather->new([
788 "one",
789 "two",
790 "three",
791 "four",
792 "five",
793 "six",
794 "seven",
795 "eight",
796 "nine",
797 "zero",
798 ]);
799  
800 # bless(..., "Venus::Gather")
801  
802 =back
803  
804 =over 4
805  
806 =item new example 3
807  
808 package main;
809  
810 use Venus::Gather;
811  
812 my $new = Venus::Gather->new(value => [
813 "one",
814 "two",
815 "three",
816 "four",
817 "five",
818 "six",
819 "seven",
820 "eight",
821 "nine",
822 "zero",
823 ]);
824  
825 # bless(..., "Venus::Gather")
826  
827 =back
828  
829 =cut
830  
831 =head2 none
832  
833 none(any | coderef $code) (Venus::Gather)
834  
835 The none method registers a special condition that returns a result only when
836 no other conditions have been matched.
837  
838 I<Since C<1.55>>
839  
840 =over 4
841  
842 =item none example 1
843  
844 package main;
845  
846 use Venus::Gather;
847  
848 my $gather = Venus::Gather->new([
849 "one",
850 "two",
851 "three",
852 "four",
853 "five",
854 "six",
855 "seven",
856 "eight",
857 "nine",
858 "zero",
859 ]);
860  
861 $gather->just('ten')->then(10);
862  
863 $gather->none('none');
864  
865 my $result = $gather->result;
866  
867 # ["none"]
868  
869 =back
870  
871 =over 4
872  
873 =item none example 2
874  
875 package main;
876  
877 use Venus::Gather;
878  
879 my $gather = Venus::Gather->new([
880 "one",
881 "two",
882 "three",
883 "four",
884 "five",
885 "six",
886 "seven",
887 "eight",
888 "nine",
889 "zero",
890 ]);
891  
892 $gather->just('ten')->then(10);
893  
894 $gather->none(sub{[map "no $_", @$_]});
895  
896 my $result = $gather->result;
897  
898 # [
899 # "no one",
900 # "no two",
901 # "no three",
902 # "no four",
903 # "no five",
904 # "no six",
905 # "no seven",
906 # "no eight",
907 # "no nine",
908 # "no zero",
909 # ]
910  
911 =back
912  
913 =cut
914  
915 =head2 object
916  
917 object() (Venus::Gather)
918  
919 The object method registers a L</when> condition which only allows matching if
920 the value presented is an object.
921  
922 I<Since C<4.15>>
923  
924 =over 4
925  
926 =item object example 1
927  
928 package main;
929  
930 use Venus::Gather;
931  
932 my $gather = Venus::Gather->new;
933  
934 $gather->object->take;
935  
936 my $result = $gather->result([0, "", undef, false, bless{}]);
937  
938 # [bless({}, 'main')]
939  
940 =back
941  
942 =cut
943  
944 =head2 only
945  
946 only(coderef $code) (Venus::Gather)
947  
948 The only method registers a special condition that only allows matching on the
949 value only if the code provided returns truthy.
950  
951 I<Since C<1.55>>
952  
953 =over 4
954  
955 =item only example 1
956  
957 package main;
958  
959 use Venus::Gather;
960  
961 my $gather = Venus::Gather->new([
962 "one",
963 "two",
964 "three",
965 "four",
966 "five",
967 "six",
968 "seven",
969 "eight",
970 "nine",
971 "zero",
972 ]);
973  
974 $gather->only(sub{grep /^[A-Z]/, @$_});
975  
976 $gather->just('one')->then(1);
977  
978 my $result = $gather->result;
979  
980 # []
981  
982 =back
983  
984 =over 4
985  
986 =item only example 2
987  
988 package main;
989  
990 use Venus::Gather;
991  
992 my $gather = Venus::Gather->new([
993 "one",
994 "two",
995 "three",
996 "four",
997 "five",
998 "six",
999 "seven",
1000 "eight",
1001 "nine",
1002 "zero",
1003 ]);
1004  
1005 $gather->only(sub{grep /e$/, @$_});
1006  
1007 $gather->expr(qr/e$/)->take;
1008  
1009 my $result = $gather->result;
1010  
1011 # [
1012 # "one",
1013 # "three",
1014 # "five",
1015 # "nine",
1016 # ]
1017  
1018 =back
1019  
1020 =cut
1021  
1022 =head2 reduce
1023  
1024 reduce(any $data) (Venus::Gather)
1025  
1026 The reduce method returns a new L<Venus::Gather> object using the values
1027 returned via the L</result> method.
1028  
1029 I<Since C<4.15>>
1030  
1031 =over 4
1032  
1033 =item reduce example 1
1034  
1035 package main;
1036  
1037 use Venus::Gather;
1038  
1039 my $gather = Venus::Gather->new([
1040 "one",
1041 "two",
1042 "three",
1043 "four",
1044 "five",
1045 "six",
1046 "seven",
1047 "eight",
1048 "nine",
1049 "zero",
1050 ]);
1051  
1052 $gather->expr(qr/^s/)->take;
1053  
1054 my $reduce = $gather->reduce;
1055  
1056 # bless(..., "Venus::Gather")
1057  
1058 =back
1059  
1060 =cut
1061  
1062 =head2 result
1063  
1064 result(any $data) (any)
1065  
1066 The result method evaluates the registered conditions and returns the result of
1067 the action (i.e. the L</then> code) or the special L</none> condition if there
1068 were no matches. In list context, this method returns both the result and
1069 whether or not a condition matched. Optionally, when passed an argument this
1070 method assign the argument as the value/topic and then perform the operation.
1071  
1072 I<Since C<1.55>>
1073  
1074 =over 4
1075  
1076 =item result example 1
1077  
1078 package main;
1079  
1080 use Venus::Gather;
1081  
1082 my $gather = Venus::Gather->new([
1083 "one",
1084 "two",
1085 "three",
1086 "four",
1087 "five",
1088 "six",
1089 "seven",
1090 "eight",
1091 "nine",
1092 "zero",
1093 ]);
1094  
1095 $gather->just('one')->then(1);
1096 $gather->just('six')->then(6);
1097  
1098 my $result = $gather->result;
1099  
1100 # [1,6]
1101  
1102 =back
1103  
1104 =over 4
1105  
1106 =item result example 2
1107  
1108 package main;
1109  
1110 use Venus::Gather;
1111  
1112 my $gather = Venus::Gather->new([
1113 "one",
1114 "two",
1115 "three",
1116 "four",
1117 "five",
1118 "six",
1119 "seven",
1120 "eight",
1121 "nine",
1122 "zero",
1123 ]);
1124  
1125 $gather->just('one')->then(1);
1126 $gather->just('six')->then(6);
1127  
1128 my ($result, $gathered) = $gather->result;
1129  
1130 # ([1,6], 2)
1131  
1132 =back
1133  
1134 =over 4
1135  
1136 =item result example 3
1137  
1138 package main;
1139  
1140 use Venus::Gather;
1141  
1142 my $gather = Venus::Gather->new([
1143 "one",
1144 "two",
1145 "three",
1146 "four",
1147 "five",
1148 "six",
1149 "seven",
1150 "eight",
1151 "nine",
1152 "zero",
1153 ]);
1154  
1155 $gather->just('One')->then(1);
1156 $gather->just('Six')->then(6);
1157  
1158 my ($result, $gathered) = $gather->result;
1159  
1160 # ([], 0)
1161  
1162 =back
1163  
1164 =over 4
1165  
1166 =item result example 4
1167  
1168 package main;
1169  
1170 use Venus::Gather;
1171  
1172 my $gather = Venus::Gather->new([
1173 "one",
1174 "two",
1175 "three",
1176 "four",
1177 "five",
1178 "six",
1179 "seven",
1180 "eight",
1181 "nine",
1182 "zero",
1183 ]);
1184  
1185 $gather->just(1)->then(1);
1186 $gather->just(6)->then(6);
1187  
1188 my $result = $gather->result([1..9, 0]);
1189  
1190 # [1,6]
1191  
1192 =back
1193  
1194 =over 4
1195  
1196 =item result example 5
1197  
1198 package main;
1199  
1200 use Venus::Gather;
1201  
1202 my $gather = Venus::Gather->new([
1203 "one",
1204 "two",
1205 "three",
1206 "four",
1207 "five",
1208 "six",
1209 "seven",
1210 "eight",
1211 "nine",
1212 "zero",
1213 ]);
1214  
1215 $gather->just('one')->then(1);
1216 $gather->just('six')->then(6);
1217  
1218 my $result = $gather->result([10..20]);
1219  
1220 # []
1221  
1222 =back
1223  
1224 =cut
1225  
1226 =head2 skip
1227  
1228 skip() (Venus::Gather)
1229  
1230 The skip method registers a L</then> condition which ignores (i.e. skips) the
1231 matched line item.
1232  
1233 I<Since C<1.55>>
1234  
1235 =over 4
1236  
1237 =item skip example 1
1238  
1239 package main;
1240  
1241 use Venus::Gather;
1242  
1243 my $gather = Venus::Gather->new([
1244 "one",
1245 "two",
1246 "three",
1247 "four",
1248 "five",
1249 "six",
1250 "seven",
1251 "eight",
1252 "nine",
1253 "zero",
1254 ]);
1255  
1256 $gather->expr(qr/e$/)->skip;
1257  
1258 $gather->expr(qr/.*/)->take;
1259  
1260 my $result = $gather->result;
1261  
1262 # ["two", "four", "six", "seven", "eight", "zero"]
1263  
1264 =back
1265  
1266 =cut
1267  
1268 =head2 take
1269  
1270 take() (Venus::Gather)
1271  
1272 The take method registers a L</then> condition which returns (i.e. takes) the
1273 matched line item as-is.
1274  
1275 I<Since C<1.55>>
1276  
1277 =over 4
1278  
1279 =item take example 1
1280  
1281 package main;
1282  
1283 use Venus::Gather;
1284  
1285 my $gather = Venus::Gather->new([
1286 "one",
1287 "two",
1288 "three",
1289 "four",
1290 "five",
1291 "six",
1292 "seven",
1293 "eight",
1294 "nine",
1295 "zero",
1296 ]);
1297  
1298 $gather->expr(qr/e$/)->take;
1299  
1300 my $result = $gather->result;
1301  
1302 # ["one", "three", "five", "nine"]
1303  
1304 =back
1305  
1306 =cut
1307  
1308 =head2 test
1309  
1310 test() (boolean)
1311  
1312 The test method evaluates the registered conditions and returns truthy if a
1313 match can be made, without executing any of the actions (i.e. the L</then>
1314 code) or the special L</none> condition.
1315  
1316 I<Since C<1.55>>
1317  
1318 =over 4
1319  
1320 =item test example 1
1321  
1322 package main;
1323  
1324 use Venus::Gather;
1325  
1326 my $gather = Venus::Gather->new([
1327 "one",
1328 "two",
1329 "three",
1330 "four",
1331 "five",
1332 "six",
1333 "seven",
1334 "eight",
1335 "nine",
1336 "zero",
1337 ]);
1338  
1339 $gather->just('one')->then(1);
1340 $gather->just('six')->then(6);
1341  
1342 my $test = $gather->test;
1343  
1344 # 2
1345  
1346 =back
1347  
1348 =over 4
1349  
1350 =item test example 2
1351  
1352 package main;
1353  
1354 use Venus::Gather;
1355  
1356 my $gather = Venus::Gather->new([
1357 "one",
1358 "two",
1359 "three",
1360 "four",
1361 "five",
1362 "six",
1363 "seven",
1364 "eight",
1365 "nine",
1366 "zero",
1367 ]);
1368  
1369 $gather->just('One')->then(1);
1370 $gather->just('Six')->then(6);
1371  
1372 my $test = $gather->test;
1373  
1374 # 0
1375  
1376 =back
1377  
1378 =cut
1379  
1380 =head2 then
1381  
1382 then(any | coderef $code) (Venus::Gather)
1383  
1384 The then method registers an action to be executed if the corresponding gather
1385 condition returns truthy.
1386  
1387 I<Since C<1.55>>
1388  
1389 =over 4
1390  
1391 =item then example 1
1392  
1393 package main;
1394  
1395 use Venus::Gather;
1396  
1397 my $gather = Venus::Gather->new([
1398 "one",
1399 "two",
1400 "three",
1401 "four",
1402 "five",
1403 "six",
1404 "seven",
1405 "eight",
1406 "nine",
1407 "zero",
1408 ]);
1409  
1410 $gather->just('one');
1411 $gather->then(1);
1412  
1413 $gather->just('two');
1414 $gather->then(2);
1415  
1416 my $result = $gather->result;
1417  
1418 # [1,2]
1419  
1420 =back
1421  
1422 =over 4
1423  
1424 =item then example 2
1425  
1426 package main;
1427  
1428 use Venus::Gather;
1429  
1430 my $gather = Venus::Gather->new([
1431 "one",
1432 "two",
1433 "three",
1434 "four",
1435 "five",
1436 "six",
1437 "seven",
1438 "eight",
1439 "nine",
1440 "zero",
1441 ]);
1442  
1443 $gather->just('one');
1444 $gather->then(1);
1445  
1446 $gather->just('two');
1447 $gather->then(2);
1448 $gather->then(0);
1449  
1450 my $result = $gather->result;
1451  
1452 # [1,0]
1453  
1454 =back
1455  
1456 =cut
1457  
1458 =head2 type
1459  
1460 type(string $expr) (Venus::Gather)
1461  
1462 The type method accepts a L<"type expression"|Venus::Type> and registers a
1463 L</when> condition which matches values conforming to the type expression
1464 specified.
1465  
1466 I<Since C<4.15>>
1467  
1468 =over 4
1469  
1470 =item type example 1
1471  
1472 package main;
1473  
1474 use Venus::Gather;
1475  
1476 my $gather = Venus::Gather->new([1, "1"]);
1477  
1478 $gather->type('string');
1479 $gather->then('string');
1480  
1481 $gather->type('number');
1482 $gather->then('number');
1483  
1484 my $result = $gather->result;
1485  
1486 # ["number", "string"]
1487  
1488 =back
1489  
1490 =cut
1491  
1492 =head2 when
1493  
1494 when(string | coderef $code, any @args) (Venus::Gather)
1495  
1496 The when method registers a match condition that will be passed the match value
1497 during evaluation. If the match condition returns truthy the corresponding
1498 action will be used to return a result. If the match value is an object, this
1499 method can take a method name and arguments which will be used as a match
1500 condition.
1501  
1502 I<Since C<1.55>>
1503  
1504 =over 4
1505  
1506 =item when example 1
1507  
1508 package main;
1509  
1510 use Venus::Gather;
1511  
1512 my $gather = Venus::Gather->new([
1513 "one",
1514 "two",
1515 "three",
1516 "four",
1517 "five",
1518 "six",
1519 "seven",
1520 "eight",
1521 "nine",
1522 "zero",
1523 ]);
1524  
1525 $gather->when(sub{$_ eq 'one'});
1526 $gather->then(1);
1527  
1528 $gather->when(sub{$_ eq 'two'});
1529 $gather->then(2);
1530  
1531 $gather->when(sub{$_ eq 'six'});
1532 $gather->then(6);
1533  
1534 my $result = $gather->result;
1535  
1536 # [1,2,6]
1537  
1538 =back
1539  
1540 =cut
1541  
1542 =head2 where
1543  
1544 where() (Venus::Gather)
1545  
1546 The where method registers an action as a sub-match operation, to be executed
1547 if the corresponding match condition returns truthy. This method returns the
1548 sub-match object.
1549  
1550 I<Since C<1.55>>
1551  
1552 =over 4
1553  
1554 =item where example 1
1555  
1556 package main;
1557  
1558 use Venus::Gather;
1559  
1560 my $gather = Venus::Gather->new;
1561  
1562 my $subgather1 = $gather->expr(qr/^p([a-z]+)ch/)->where;
1563  
1564 $subgather1->just('peach')->then('peach-123');
1565 $subgather1->just('patch')->then('patch-456');
1566 $subgather1->just('punch')->then('punch-789');
1567  
1568 my $subgather2 = $gather->expr(qr/^m([a-z]+)ch/)->where;
1569  
1570 $subgather2->just('merch')->then('merch-123');
1571 $subgather2->just('march')->then('march-456');
1572 $subgather2->just('mouch')->then('mouch-789');
1573  
1574 my $result = $gather->result(['peach', 'preach']);
1575  
1576 # ["peach-123"]
1577  
1578 =back
1579  
1580 =over 4
1581  
1582 =item where example 2
1583  
1584 package main;
1585  
1586 use Venus::Gather;
1587  
1588 my $gather = Venus::Gather->new;
1589  
1590 my $subgather1 = $gather->expr(qr/^p([a-z]+)ch/)->where;
1591  
1592 $subgather1->just('peach')->then('peach-123');
1593 $subgather1->just('patch')->then('patch-456');
1594 $subgather1->just('punch')->then('punch-789');
1595  
1596 my $subgather2 = $gather->expr(qr/^m([a-z]+)ch/)->where;
1597  
1598 $subgather2->just('merch')->then('merch-123');
1599 $subgather2->just('march')->then('march-456');
1600 $subgather2->just('mouch')->then('mouch-789');
1601  
1602 my $result = $gather->result(['march', 'merch']);
1603  
1604 # ["march-456", "merch-123"]
1605  
1606 =back
1607  
1608 =over 4
1609  
1610 =item where example 3
1611  
1612 package main;
1613  
1614 use Venus::Gather;
1615  
1616 my $gather = Venus::Gather->new;
1617  
1618 my $subgather1 = $gather->expr(qr/^p([a-z]+)ch/)->where;
1619  
1620 $subgather1->just('peach')->then('peach-123');
1621 $subgather1->just('patch')->then('patch-456');
1622 $subgather1->just('punch')->then('punch-789');
1623  
1624 my $subgather2 = $gather->expr(qr/^m([a-z]+)ch/)->where;
1625  
1626 $subgather2->just('merch')->then('merch-123');
1627 $subgather2->just('march')->then('march-456');
1628 $subgather2->just('mouch')->then('mouch-789');
1629  
1630 my $result = $gather->result(['pirch']);
1631  
1632 # []
1633  
1634 =back
1635  
1636 =cut
1637  
1638 =head1 AUTHORS
1639  
1640 Awncorp, C<awncorp@cpan.org>
1641  
1642 =cut
1643  
1644 =head1 LICENSE
1645  
1646 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
1647  
1648 This program is free software, you can redistribute it and/or modify it under
1649 the terms of the Apache license version 2.0.
1650  
1651 =cut
« blib/lib/Venus/Range.pm ↑ Summary blib/lib/Venus/Role/Optional.pm »