Venus::Gather

Gather Class

Gather Class for Perl 5

method: clear method: data method: expr method: just method: none method: only method: result method: skip method: take method: then method: when method: where

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;

# ["?"]

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.

Venus::Kind::Utility

Venus::Role::Accessible Venus::Role::Buildable Venus::Role::Valuable

on_none: rw, opt, CodeRef, sub{} on_only: rw, opt, CodeRef, sub{1} on_then: rw, opt, ArrayRef[CodeRef], [] on_when: rw, opt, ArrayRef[CodeRef], []

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

clear() (Gather)

{ since => '1.55', }

=example-1 clear

# given: synopsis

package main;

my $clear = $gather->clear;

# bless(..., "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.

data(HashRef $data) (Gather)

{ since => '1.55', }

=example-1 data

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]

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.

expr(Str | RegexpRef $expr) (Gather)

{ since => '1.55', }

=example-1 expr

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"]]

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

just(Str $topic) (Gather)

{ since => '1.55', }

=example-1 just

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]

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

none(Any | CodeRef $code) (Gather)

{ since => '1.55', }

=example-1 none

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"]

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

only(CodeRef $code) (Gather)

{ since => '1.55', }

=example-1 only

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;

# []

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.

result(Any $data) (Any)

{ since => '1.55', }

=example-1 result

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]

The test method evaluates the registered conditions and returns truthy if a match can be made, without executing any of the actions (i.e. the "then" code) or the special "none" condition.

test() (Bool)

{ since => '1.55', }

=example-1 test

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 $test = $gather->test;

# 2

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

skip() (Gather)

{ since => '1.55', }

=example-1 skip

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"]

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

take() (Gather)

{ since => '1.55', }

=example-1 take

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"]

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

then(Any | CodeRef $code) (Gather)

{ since => '1.55', }

=example-1 then

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]

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.

when(Str | CodeRef $code, Any @args) (Gather)

{ since => '1.55', }

=example-1 when

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]

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.

where() (Gather)

{ since => '1.55', }

=example-1 where

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"]

t/Venus.t: pdml: authors t/Venus.t: pdml: license

cpanm Venus

perl -MCPAN -e shell
install Venus