/ 
Venus-4.15
River stage two • 3 direct dependents • 56 total dependents
/ Venus::Gather

NAME

Venus::Gather - Gather Class

ABSTRACT

Gather Class for Perl 5

SYNOPSIS

package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->when(sub{$_ eq 1})->then(sub{"one"});
$gather->when(sub{$_ eq 2})->then(sub{"two"});

$gather->none(sub{"?"});

my $result = $gather->result;

# ["?"]

DESCRIPTION

This package provides an object-oriented interface for complex pattern matching operations on collections of data, e.g. array references. See Venus::Match for operating on scalar values.

ATTRIBUTES

This package has the following attributes:

on_none

on_none(CodeRef)

This attribute is read-write, accepts (CodeRef) values, is optional, and defaults to sub{}.

on_only

on_only(CodeRef)

This attribute is read-write, accepts (CodeRef) values, is optional, and defaults to sub{1}.

on_then

on_then(ArrayRef[CodeRef])

This attribute is read-write, accepts (ArrayRef[CodeRef]) values, is optional, and defaults to [].

on_when

on_when(ArrayRef[CodeRef])

This attribute is read-write, accepts (ArrayRef[CodeRef]) values, is optional, and defaults to [].

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Accessible

Venus::Role::Buildable

Venus::Role::Valuable

METHODS

This package provides the following methods:

clear

clear() (Venus::Gather)

The clear method resets all gather conditions and returns the invocant.

Since 1.55

clear example 1
# given: synopsis

package main;

my $clear = $gather->clear;

# bless(..., "Venus::Gather")

data

data(hashref $data) (Venus::Gather)

The data method takes a hashref (i.e. lookup table) and creates gather conditions and actions based on the keys and values found.

Since 1.55

data example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->data({
  "one" => 1,
  "two" => 2,
  "three" => 3,
  "four" => 4,
  "five" => 5,
  "six" => 6,
  "seven" => 7,
  "eight" => 8,
  "nine" => 9,
  "zero" => 0,
});

my $result = $gather->none('?')->result;

# [1..9, 0]
data example 2
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->data({
  "zero" => 0,
});

my $result = $gather->none('?')->result;

# [0]

expr

expr(string | regexp $expr) (Venus::Gather)

The expr method registers a "when" condition that check if the match value is an exact string match of the $topic if the topic is a string, or that it matches against the topic if the topic is a regular expression.

Since 1.55

expr example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->expr('one')->then(sub{[split //]});

my $result = $gather->result;

# [["o", "n", "e"]]
expr example 2
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->expr(qr/^o/)->then(sub{[split //]});

my $result = $gather->result;

# [["o", "n", "e"]]

just

just(string $topic) (Venus::Gather)

The just method registers a "when" condition that check if the match value is an exact string match of the $topic provided.

Since 1.55

just example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('one')->then(1);
$gather->just('two')->then(2);
$gather->just('three')->then(3);

my $result = $gather->result;

# [1,2,3]
just example 2
package main;

use Venus::Gather;
use Venus::String;

my $gather = Venus::Gather->new([
  Venus::String->new("one"),
  Venus::String->new("two"),
  Venus::String->new("three"),
  Venus::String->new("four"),
  Venus::String->new("five"),
  Venus::String->new("six"),
  Venus::String->new("seven"),
  Venus::String->new("eight"),
  Venus::String->new("nine"),
  Venus::String->new("zero"),
]);

$gather->just('one')->then(1);
$gather->just('two')->then(2);
$gather->just('three')->then(3);

my $result = $gather->result;

# [1,2,3]
just example 3
package main;

use Venus::Gather;
use Venus::String;

my $gather = Venus::Gather->new([
  Venus::String->new("one"),
  Venus::String->new("two"),
  Venus::String->new("three"),
  Venus::String->new("four"),
  Venus::String->new("five"),
  Venus::String->new("six"),
  Venus::String->new("seven"),
  Venus::String->new("eight"),
  Venus::String->new("nine"),
  Venus::String->new("zero"),
]);

$gather->just('one')->then(1);
$gather->just('six')->then(6);

my $result = $gather->result;

# [1,6]

none

none(any | coderef $code) (Venus::Gather)

The none method registers a special condition that returns a result only when no other conditions have been matched.

Since 1.55

none example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('ten')->then(10);

$gather->none('none');

my $result = $gather->result;

# ["none"]
none example 2
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('ten')->then(10);

$gather->none(sub{[map "no $_", @$_]});

my $result = $gather->result;

# [
#   "no one",
#   "no two",
#   "no three",
#   "no four",
#   "no five",
#   "no six",
#   "no seven",
#   "no eight",
#   "no nine",
#   "no zero",
# ]

only

only(coderef $code) (Venus::Gather)

The only method registers a special condition that only allows matching on the value only if the code provided returns truthy.

Since 1.55

only example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->only(sub{grep /^[A-Z]/, @$_});

$gather->just('one')->then(1);

my $result = $gather->result;

# []
only example 2
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->only(sub{grep /e$/, @$_});

$gather->expr(qr/e$/)->take;

my $result = $gather->result;

# [
#   "one",
#   "three",
#   "five",
#   "nine",
# ]

result

result(any $data) (any)

The result method evaluates the registered conditions and returns the result of the action (i.e. the "then" code) or the special "none" condition if there were no matches. In list context, this method returns both the result and whether or not a condition matched. Optionally, when passed an argument this method assign the argument as the value/topic and then perform the operation.

Since 1.55

result example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('one')->then(1);
$gather->just('six')->then(6);

my $result = $gather->result;

# [1,6]
result example 2
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('one')->then(1);
$gather->just('six')->then(6);

my ($result, $gathered) = $gather->result;

# ([1,6], 2)
result example 3
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('One')->then(1);
$gather->just('Six')->then(6);

my ($result, $gathered) = $gather->result;

# ([], 0)
result example 4
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just(1)->then(1);
$gather->just(6)->then(6);

my $result = $gather->result([1..9, 0]);

# [1,6]
result example 5
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('one')->then(1);
$gather->just('six')->then(6);

my $result = $gather->result([10..20]);

# []

skip

skip() (Venus::Gather)

The skip method registers a "then" condition which ignores (i.e. skips) the matched line item.

Since 1.55

skip example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->expr(qr/e$/)->skip;

$gather->expr(qr/.*/)->take;

my $result = $gather->result;

# ["two", "four", "six", "seven", "eight", "zero"]

take

take() (Venus::Gather)

The take method registers a "then" condition which returns (i.e. takes) the matched line item as-is.

Since 1.55

take example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->expr(qr/e$/)->take;

my $result = $gather->result;

# ["one", "three", "five", "nine"]

then

then(any | coderef $code) (Venus::Gather)

The then method registers an action to be executed if the corresponding gather condition returns truthy.

Since 1.55

then example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('one');
$gather->then(1);

$gather->just('two');
$gather->then(2);

my $result = $gather->result;

# [1,2]
then example 2
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->just('one');
$gather->then(1);

$gather->just('two');
$gather->then(2);
$gather->then(0);

my $result = $gather->result;

# [1,0]

when

when(string | coderef $code, any @args) (Venus::Gather)

The when method registers a match condition that will be passed the match value during evaluation. If the match condition returns truthy the corresponding action will be used to return a result. If the match value is an object, this method can take a method name and arguments which will be used as a match condition.

Since 1.55

when example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new([
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
  "zero",
]);

$gather->when(sub{$_ eq 'one'});
$gather->then(1);

$gather->when(sub{$_ eq 'two'});
$gather->then(2);

$gather->when(sub{$_ eq 'six'});
$gather->then(6);

my $result = $gather->result;

# [1,2,6]

where

where() (Venus::Gather)

The where method registers an action as a sub-match operation, to be executed if the corresponding match condition returns truthy. This method returns the sub-match object.

Since 1.55

where example 1
package main;

use Venus::Gather;

my $gather = Venus::Gather->new;

my $subgather1 = $gather->expr(qr/^p([a-z]+)ch/)->where;

$subgather1->just('peach')->then('peach-123');
$subgather1->just('patch')->then('patch-456');
$subgather1->just('punch')->then('punch-789');

my $subgather2 = $gather->expr(qr/^m([a-z]+)ch/)->where;

$subgather2->just('merch')->then('merch-123');
$subgather2->just('march')->then('march-456');
$subgather2->just('mouch')->then('mouch-789');

my $result = $gather->result(['peach', 'preach']);

# ["peach-123"]
where example 2
package main;

use Venus::Gather;

my $gather = Venus::Gather->new;

my $subgather1 = $gather->expr(qr/^p([a-z]+)ch/)->where;

$subgather1->just('peach')->then('peach-123');
$subgather1->just('patch')->then('patch-456');
$subgather1->just('punch')->then('punch-789');

my $subgather2 = $gather->expr(qr/^m([a-z]+)ch/)->where;

$subgather2->just('merch')->then('merch-123');
$subgather2->just('march')->then('march-456');
$subgather2->just('mouch')->then('mouch-789');

my $result = $gather->result(['march', 'merch']);

# ["march-456", "merch-123"]
where example 3
package main;

use Venus::Gather;

my $gather = Venus::Gather->new;

my $subgather1 = $gather->expr(qr/^p([a-z]+)ch/)->where;

$subgather1->just('peach')->then('peach-123');
$subgather1->just('patch')->then('patch-456');
$subgather1->just('punch')->then('punch-789');

my $subgather2 = $gather->expr(qr/^m([a-z]+)ch/)->where;

$subgather2->just('merch')->then('merch-123');
$subgather2->just('march')->then('march-456');
$subgather2->just('mouch')->then('mouch-789');

my $result = $gather->result(['pirch']);

# []

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2022, Awncorp, awncorp@cpan.org.

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.