Venus::Match

Match Class

Match Class for Perl 5

method: defined method: boolean method: clear method: data method: expr method: just method: new method: none method: object method: only method: result method: take method: test method: then method: type method: when method: where method: yesno

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 boolean method registers a "then" condition which returns true if the item is matched, and registers a "none" condition which returns false if there are no matches.

boolean() (Venus::Match)

{ since => '4.15', }

=example-1 boolean

package main;

use Venus::Match;

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

$match->just(5)->boolean;

my $result = $match->result;

# true

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

clear() (Venus::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) (Venus::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 defined method registers an "only" condition which only allows matching if the value presented is defined.

defined() (Venus::Match)

{ since => '4.15', }

=example-1 defined

package main;

use Venus::Match;

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

$match->expr(qr/.*/)->then('okay');

my $result = $match->result;

# undef

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(string | regexp $expr) (Venus::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(string $topic) (Venus::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 new method constructs an instance of the package.

new(any @args) (Venus::Match)

{ since => '4.15', }

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

none(any | coderef $code) (Venus::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 object method registers an "only" condition which only allows matching if the value presented is an object.

object() (Venus::Match)

{ since => '4.15', }

=example-1 object

package main;

use Venus::Match;

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

$match->when('isa', 'main')->then('okay');

my $result = $match->result;

# undef

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) (Venus::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 take method registers a "then" condition which returns (i.e. takes) the matched item as-is, and registers a "none" condition which returns undef if there are no matches.

take() (Venus::Match)

{ since => '4.15', }

=example-1 take

package main;

use Venus::Match;

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

$match->just(5)->take;

my $result = $match->result;

# 5

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

{ 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) (Venus::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 type method accepts a "type expression" and registers a "when" condition which matches values conforming to the type expression specified.

type(string $expr) (Venus::Match)

{ since => '4.15', }

=example-1 type

package main;

use Venus::Match;

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

$match->type('string')->then('okay');

my $result = $match->result;

# undef

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(string | coderef $code, any @args) (Venus::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() (Venus::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"

The yesno method registers a "then" condition which returns "yes" if the item is matched, and registers a "none" condition which returns "no" if there are no matches.

yesno() (Venus::Match)

{ since => '4.15', }

=example-1 yesno

package main;

use Venus::Match;

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

$match->just(5)->yesno;

my $result = $match->result;

# "yes"

t/Venus.t: present: authors t/Venus.t: present: license

cpanm Venus

perl -MCPAN -e shell
install Venus