Venus::Match

Match Class

Match Class for Perl 5

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

package main;

use Venus::Match;

my $match = Venus::Match->new(5);

$match->when(sub{$_ < 5})->then(sub{"< 5"});
$match->when(sub{$_ > 5})->then(sub{"> 5"});

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

my $result = $match->result;

# "?"

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

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 match conditions and returns the invocant.

clear() (Match)

{ since => '1.23', }

=example-1 clear

# given: synopsis

package main;

my $clear = $match->clear;

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

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

data(HashRef $data) (Match)

{ since => '0.07', }

=example-1 data

package main;

use Venus::Match;

my $match = Venus::Match->new('a');

$match->data({
  'a' => 'b',
  'c' => 'd',
  'e' => 'f',
  'g' => 'h',
});

my $result = $match->none('z')->result;

# "b"

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) (Match)

{ since => '0.07', }

=example-1 expr

package main;

use Venus::Match;

my $match = Venus::Match->new('1901-01-01');

$match->expr('1901-01-01')->then(sub{[split /-/]});

my $result = $match->result;

# ["1901", "01", "01"]

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) (Match)

{ since => '0.03', }

=example-1 just

package main;

use Venus::Match;

my $match = Venus::Match->new('a');

$match->just('a')->then('a');
$match->just('b')->then('b');
$match->just('c')->then('c');

my $result = $match->result;

# "a"

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

none(Any | CodeRef $code) (Match)

{ since => '0.03', }

=example-1 none

package main;

use Venus::Match;

my $match = Venus::Match->new('z');

$match->just('a')->then('a');
$match->just('b')->then('b');
$match->just('c')->then('c');

$match->none('z');

my $result = $match->result;

# "z"

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

only(CodeRef $code) (Match)

{ since => '0.03', }

=example-1 only

package main;

use Venus::Match;

my $match = Venus::Match->new(5);

$match->only(sub{$_ != 5});

$match->just(5)->then(5);
$match->just(6)->then(6);

my $result = $match->result;

# undef

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 => '0.03', }

=example-1 result

package main;

use Venus::Match;

my $match = Venus::Match->new('a');

$match->just('a')->then('a');
$match->just('b')->then('b');
$match->just('c')->then('c');

my $result = $match->result;

# "a"

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.02', }

=example-1 test

package Match;

use Venus::Match;

our $TEST = 0;

my $match = Venus::Match->new('a');

$match->just('a')->then(sub{$TEST = 1});
$match->just('b')->then(sub{$TEST = 2});
$match->just('c')->then(sub{$TEST = 3});

my $test = $match->test;

# 1

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

then(Any | CodeRef $code) (Match)

{ since => '0.03', }

=example-1 then

package main;

use Venus::Match;

my $match = Venus::Match->new('b');

$match->just('a');
$match->then('a');

$match->just('b');
$match->then('b');

my $result = $match->result;

# "b"

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) (Match)

{ since => '0.03', }

=example-1 when

package main;

use Venus::Match;

my $match = Venus::Match->new('a');

$match->when(sub{$_ eq 'a'});
$match->then('a');

$match->when(sub{$_ eq 'b'});
$match->then('b');

$match->when(sub{$_ eq 'c'});
$match->then('c');

my $result = $match->result;

# "a"

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() (Match)

{ since => '1.40', }

=example-1 where

package main;

use Venus::Match;

my $match = Venus::Match->new;

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

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

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

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

my $result = $match->result('peach');

# "peach-123"

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

cpanm Venus

perl -MCPAN -e shell
install Venus