/ 
Venus-5.01
River stage two • 3 direct dependents • 56 total dependents
⭐ Starred 2 GitHub stars
/ Venus::Result

NAME

Venus::Result - Result Class

ABSTRACT

Result Class for Perl 5

SYNOPSIS

package main;

use Venus::Result;

my $result = Venus::Result->new;

# $result->is_valid;

# true

DESCRIPTION

This package provides a container for representing success and error states in a more structured and predictable way, and a mechanism for chaining subsequent operations.

ATTRIBUTES

This package has the following attributes:

issue

issue(any $issue) (any)

The issue attribute is read/write, accepts (any) values, and is optional.

Since 4.15

issue example 1
# given: synopsis;

my $issue = $result->issue("Failed!");

# "Failed!"
issue example 2
# given: synopsis;

# given: example-1 issue;

$issue = $result->issue;

# "Failed!"

value

value(any $value) (any)

The valid attribute is read/write, accepts (any) values, and is optional.

Since 4.15

value example 1
# given: synopsis;

my $value = $result->value("Success!");

# "Success!"
value example 2
# given: synopsis;

# given: example-1 value;

$value = $result->value;

# "Success!"

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Buildable

Venus::Role::Tryable

Venus::Role::Catchable

METHODS

This package provides the following methods:

attest

attest(string $name, string $expr) (any)

The attest method validates the value of the attribute named, i.e. "issue" or "value", using the Venus::Assert expression provided and returns the result.

Since 4.15

attest example 1
# given: synopsis

package main;

my $attest = $result->attest;

# undef
attest example 2
# given: synopsis

package main;

$result->value("Success!");

my $attest = $result->attest('value', 'number | string');

# "Success!"
attest example 3
# given: synopsis

package main;

my $attest = $result->attest('value', 'number | string');

# Exception! (isa Venus::Check::Error)
attest example 4
# given: synopsis

package main;

$result->issue("Failed!");

my $attest = $result->attest('issue', 'number | string');

# "Failed!"
attest example 5
# given: synopsis

package main;

my $attest = $result->attest('issue', 'number | string');

# Exception! (isa Venus::Check::Error)

check

check(string $name, string $expr) (boolean)

The check method validates the value of the attribute named, i.e. "issue" or "value", using the Venus::Assert expression provided and returns the true if the value is valid, and false otherwise.

Since 4.15

check example 1
# given: synopsis

package main;

my $check = $result->check;

# true
check example 2
# given: synopsis

package main;

$result->value("Success!");

my $check = $result->check('value', 'number | string');

# true
check example 3
# given: synopsis

package main;

my $check = $result->check('value', 'number | string');

# false
check example 4
# given: synopsis

package main;

$result->issue("Failed!");

my $check = $result->check('issue', 'number | string');

# true
check example 5
# given: synopsis

package main;

my $check = $result->check('issue', 'number | string');

# false

invalid

invalid(any $error) (Venus::Result)

The invalid method returns a Venus::Result object representing an issue and error state.

Since 4.15

invalid example 1
package main;

use Venus::Result;

my $invalid = Venus::Result->invalid("Failed!");

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

is_invalid

is_invalid() (boolean)

The is_invalid method returns true if an error exists, and false otherwise.

Since 4.15

is_invalid example 1
# given: synopsis;

my $is_invalid = $result->is_invalid;

# false
is_invalid example 2
# given: synopsis;

$result->value("Success!");

my $is_invalid = $result->is_invalid;

# false
is_invalid example 3
# given: synopsis;

$result->issue("Failed!");

my $is_invalid = $result->is_invalid;

# true

is_valid

is_valid() (boolean)

The is_valid method returns true if no error exists, and false otherwise.

Since 4.15

is_valid example 1
# given: synopsis;

my $is_valid = $result->is_valid;

# true
is_valid example 2
# given: synopsis;

$result->value("Success!");

my $is_valid = $result->is_valid;

# true
is_valid example 3
# given: synopsis;

$result->issue("Failed!");

my $is_valid = $result->is_valid;

# false

new

new(hashref $data) (Venus::Result)

The new method returns a Venus::Result object.

Since 4.15

new example 1
package main;

use Venus::Result;

my $new = Venus::Result->new;

# bless(..., "Venus::Result")
new example 2
package main;

use Venus::Result;

my $new = Venus::Result->new(value => "Success!");

# bless(..., "Venus::Result")
new example 3
package main;

use Venus::Result;

my $new = Venus::Result->new({value => "Success!"});

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

on_invalid

on_invalid(coderef $callback) (Venus::Result)

The on_invalid method chains an operations by passing the issue value of the result to the callback provided and returns a Venus::Result object.

Since 4.15

on_invalid example 1
# given: synopsis;

my $on_invalid = $result->on_invalid;

# bless(..., "Venus::Result")
on_invalid example 2
# given: synopsis;

my $on_invalid = $result->on_invalid(sub{
  return "New success!";
});

# bless(..., "Venus::Result")
on_invalid example 3
# given: synopsis;

$result->issue("Failed!");

my $on_invalid = $result->on_invalid(sub{
  return "New success!";
});

# bless(..., "Venus::Result")
on_invalid example 4
# given: synopsis;

$result->issue("Failed!");

my $on_invalid = $result->on_invalid(sub{
  die "New failure!";
});

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

on_valid

on_valid(coderef $callback) (Venus::Result)

The on_valid method chains an operations by passing the success value of the result to the callback provided and returns a Venus::Result object.

Since 4.15

on_valid example 1
# given: synopsis;

my $on_valid = $result->on_valid;

# bless(..., "Venus::Result")
on_valid example 2
# given: synopsis;

my $on_valid = $result->on_valid(sub{
  return "New success!";
});

# bless(..., "Venus::Result")
on_valid example 3
# given: synopsis;

$result->issue("Failed!");

my $on_valid = $result->on_valid(sub{
  return "New success!";
});

# bless(..., "Venus::Result")
on_valid example 4
# given: synopsis;

my $on_valid = $result->on_valid(sub{
  die "New failure!";
});

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

then

then(string | coderef $callback, any @args) (Venus::Result)

The then method chains an operations by passing the value or issue of the result to the callback provided and returns a Venus::Result object.

Since 4.15

then example 1
# given: synopsis;

my $then = $result->then;

# bless(..., "Venus::Result")
then example 2
# given: synopsis;

my $then = $result->then(sub{
  return "New success!";
});

# bless(..., "Venus::Result")
then example 3
# given: synopsis;

$result->issue("Failed!");

my $then = $result->then(sub{
  return "New success!";
});

# bless(..., "Venus::Result")
then example 4
# given: synopsis;

my $then = $result->then(sub{
  die "New failure!";
});

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

valid

valid(any $value) (Venus::Result)

The valid method returns a Venus::Result object representing a value and success state.

Since 4.15

valid example 1
package main;

use Venus::Result;

my $valid = Venus::Result->valid("Success!");

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

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.