Venus::Assert

Assert Class

Assert Class for Perl 5

method: any method: accept method: array method: arrayref method: attributes method: boolean method: check method: clear method: code method: coderef method: coerce method: coercion method: coercions method: conditions method: constraint method: constraints method: defined method: either method: enum method: expression method: format method: float method: hash method: hashkeys method: hashref method: identity method: inherits method: integrates method: maybe method: number method: object method: package method: parse method: reference method: regexp method: routines method: scalar method: scalarref method: string method: tuple method: undef method: validate method: validator method: value method: within method: yesno

package main;

use Venus::Assert;

my $assert = Venus::Assert->new('Example');

# $assert->format(float => sub {sprintf('%.2f', $_->value)});

# $assert->accept(float => sub {$_->value > 1});

# $assert->check;

This package provides a mechanism for asserting type constraints and coercions on data.

Venus::Kind::Utility

Venus::Role::Buildable

expects: rw, opt, ArrayRef message: rw, opt, Str name: rw, opt, Str

The any method configures the object to accept any value and returns the invocant.

any() (Assert)

{ since => '1.40', }

=example-1 any

# given: synopsis

package main;

$assert = $assert->any;

# $assert->check;

# true

The accept method registers a constraint based on the built-in type or package name provided as the first argument. The built-in types are "array", "boolean", "code", "float", "hash", "number", "object", "regexp", "scalar", "string", or "undef". Any name given that is not a built-in type is assumed to be a method (i.e. a method call) or an "object" of the name provided. Additional arguments are assumed to be arguments for the dispatched method call. Optionally, you can provide a callback to further constrain/validate the provided value, returning truthy or falsy, for methods that support it.

accept(Str $name, Any @args) (Object)

{ since => '1.40', }

=example-1 accept

# given: synopsis

package main;

$assert = $assert->accept('float');

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

# ...

# $assert->check;

# 0

# $assert->check(1.01);

# 1

The array method configures the object to accept array references and returns the invocant.

array(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 array

# given: synopsis

package main;

$assert = $assert->array;

# $assert->check([]);

# true

The arrayref method configures the object to accept array references and returns the invocant.

arrayref(CodeRef $check) (Assert)

{ since => '1.71', }

=example-1 arrayref

# given: synopsis

package main;

$assert = $assert->arrayref;

# $assert->check([]);

# true

The attributes method configures the object to accept objects containing attributes whose values' match the attribute names and types specified, and returns the invocant.

attributes(Str | ArrayRef[Str] @pairs) (Assert)

{ since => '2.01', }

=example-1 attributes

# given: synopsis

package main;

$assert = $assert->attributes;

# $assert->check(Venus::Assert->new);

# true

The boolean method configures the object to accept boolean values and returns the invocant.

boolean(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 boolean

# given: synopsis

package main;

$assert = $assert->boolean;

# $assert->check(false);

# true

The check method returns true or false if the data provided passes the registered constraints.

check(Any $data) (Bool)

{ since => '1.23', }

=example-1 check

# given: synopsis

package main;

$assert->constraint(float => sub { $_->value > 1 });

my $check = $assert->check;

# 0

The clear method resets all match conditions for both constraints and coercions and returns the invocant.

clear() (Assert)

{ since => '1.40', }

=example-1 clear

# given: synopsis

package main;

$assert = $assert->clear;

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

The code method configures the object to accept code references and returns the invocant.

code(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 code

# given: synopsis

package main;

$assert = $assert->code;

# $assert->check(sub{});

# true

The coderef method configures the object to accept code references and returns the invocant.

coderef(CodeRef $check) (Assert)

{ since => '1.71', }

=example-1 coderef

# given: synopsis

package main;

$assert = $assert->coderef;

# $assert->check(sub{});

# true

The coerce method returns the coerced data if the data provided matches any of the registered coercions.

coerce(Any $data) (Any)

{ since => '1.23', }

=example-1 coerce

# given: synopsis

package main;

$assert->coercion(float => sub { sprintf('%.2f', $_->value) });

my $coerce = $assert->coerce;

# undef

The coercion method registers a coercion based on the type provided.

coercion(Str $type, CodeRef $code) (Object)

{ since => '1.23', }

=example-1 coercion

# given: synopsis

package main;

$assert = $assert->coercion(float => sub { sprintf('%.2f', $_->value) });

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

The coercions method returns the registered coercions as a Venus::Match object.

coercions() (Match)

{ since => '1.23', }

=example-1 coercions

# given: synopsis

package main;

my $coercions = $assert->coercions;

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

The conditions method is an object construction hook that allows subclasses to configure the object on construction setting up constraints and coercions and returning the invocant.

conditions() (Assert)

{ since => '1.40', }

=example-1 conditions

# given: synopsis

package main;

$assert = $assert->conditions;

The constraint method registers a constraint based on the type provided.

constraint(Str $type, CodeRef $code) (Object)

{ since => '1.23', }

=example-1 constraint

# given: synopsis

package main;

$assert = $assert->constraint(float => sub { $_->value > 1 });

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

The constraints method returns the registered constraints as a Venus::Match object.

constraints() (Match)

{ since => '1.23', }

=example-1 constraints

# given: synopsis

package main;

my $constraints = $assert->constraints;

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

The consumes method configures the object to accept objects which consume the role provided, and returns the invocant.

consumes(Str $name) (Assert)

{ since => '1.40', }

=example-1 consumes

# given: synopsis

package main;

$assert = $assert->consumes('Venus::Role::Doable');

# $assert->check(Venus::Assert->new);

# true

The defined method configures the object to accept any value that's not undefined and returns the invocant.

defined(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 defined

# given: synopsis

package main;

$assert = $assert->defined;

# $assert->check(0);

# true

The either method configures the object to accept "either" of the conditions provided, which may be a string or arrayref representing a method call, and returns the invocant.

either(Str | ArrayRef[Str|ArrayRef] $dispatch) (Assert)

{ since => '2.01', }

=example-1 either

# given: synopsis

package main;

$assert = $assert->either('string');

# $assert->check('1');

# true

# $assert->check(1);

# false

The enum method configures the object to accept any one of the provide options, and returns the invocant.

enum(Any @data) (Assert)

{ since => '1.40', }

=example-1 enum

# given: synopsis

package main;

$assert = $assert->enum('s', 'm', 'l', 'xl');

# $assert->check('s');

# true

# $assert->check('xs');

# false

The expression method parses a string representation of an type assertion signature, registers the subexpressions using the "either" and "accept" methods, and returns the invocant.

expression(Str $expr) (Assert)

{ since => '1.71', }

=example-1 expression

# given: synopsis

package main;

$assert = $assert->expression('string');

# $assert->check('hello');

# true

# $assert->check(['goodbye']);

# false

The float method configures the object to accept floating-point values and returns the invocant.

float(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 float

# given: synopsis

package main;

$assert = $assert->float;

# $assert->check(1.23);

# true

The format method registers a coercion based on the built-in type or package name and callback provided. The built-in types are "array", "boolean", "code", "float", "hash", "number", "object", "regexp", "scalar", "string", or "undef". Any name given that is not a built-in type is assumed to be an "object" of the name provided.

format(Str $name, CodeRef $callback) (Object)

{ since => '1.40', }

=example-1 format

# given: synopsis

package main;

$assert = $assert->format('float', sub{int $_->value});

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

# ...

# $assert->coerce;

# undef

# $assert->coerce(1.01);

# 1

The hash method configures the object to accept hash references and returns the invocant.

hash(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 hash

# given: synopsis

package main;

$assert = $assert->hash;

# $assert->check({});

# true

The hashkeys method configures the object to accept hash based values containing the keys whose values' match the specified types, and returns the invocant.

hashkeys(Str | ArrayRef[Str] @pairs) (Assert)

{ since => '2.01', }

=example-1 hashkeys

# given: synopsis

package main;

$assert = $assert->hashkeys;

# $assert->check({});

# false

# $assert->check({random => rand});

# true

The hashref method configures the object to accept hash references and returns the invocant.

hashref(CodeRef $check) (Assert)

{ since => '1.71', }

=example-1 hashref

# given: synopsis

package main;

$assert = $assert->hashref;

# $assert->check({});

# true

The identity method configures the object to accept objects of the type specified as the argument, and returns the invocant.

identity(Str $name) (Assert)

{ since => '1.40', }

=example-1 identity

# given: synopsis

package main;

$assert = $assert->identity('Venus::Assert');

# $assert->check(Venus::Assert->new);

# true

The inherits method configures the object to accept objects of the type specified as the argument, and returns the invocant. This method is a proxy for the "identity" method.

inherits(Str $name) (Assert)

{ since => '2.01', }

=example-1 inherits

# given: synopsis

package main;

$assert = $assert->inherits('Venus::Assert');

# $assert->check(Venus::Assert->new);

# true

The integrates method configures the object to accept objects that support the "does" behavior and consumes the "role" specified as the argument, and returns the invocant.

integrates(Str $name) (Assert)

{ since => '2.01', }

=example-1 integrates

# given: synopsis

package main;

$assert = $assert->integrates('Venus::Role::Doable');

# $assert->check(Venus::Assert->new);

# true

The maybe method configures the object to accept the type provided as an argument, or undef, and returns the invocant.

maybe(Str $type, Any @args) (Assert)

{ since => '1.40', }

=example-1 maybe

# given: synopsis

package main;

$assert = $assert->maybe('code');

# $assert->check(sub{});

# true

# $assert->check(undef);

# true

The number method configures the object to accept numberic values and returns the invocant.

number(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 number

# given: synopsis

package main;

$assert = $assert->number;

# $assert->check(0);

# true

The object method configures the object to accept objects and returns the invocant.

object(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 object

# given: synopsis

package main;

$assert = $assert->object;

# $assert->check(bless{});

# true

The package method configures the object to accept package names (which are loaded) and returns the invocant.

package() (Assert)

{ since => '1.40', }

=example-1 package

# given: synopsis

package main;

$assert = $assert->package;

# $assert->check('Venus');

# true

The parse method accepts a string representation of a type assertion signature and returns a data structure representing one or more method calls to be used for validating the assertion signature.

parse(Str $expr) (Any)

{ since => '2.01', }

=example-1 parse

# given: synopsis

package main;

my $parsed = $assert->parse('');

# ['']

The reference method configures the object to accept references and returns the invocant.

reference(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 reference

# given: synopsis

package main;

$assert = $assert->reference;

# $assert->check(sub{});

# true

The regexp method configures the object to accept regular expression objects and returns the invocant.

regexp(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 regexp

# given: synopsis

package main;

$assert = $assert->regexp;

# $assert->check(qr//);

# true

The routines method configures the object to accept an object having all of the routines provided, and returns the invocant.

routines(Str @names) (Assert)

{ since => '1.40', }

=example-1 routines

# given: synopsis

package main;

$assert = $assert->routines('new', 'print', 'say');

# $assert->check(Venus::Assert->new);

# true

The scalar method configures the object to accept scalar references and returns the invocant.

scalar(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 scalar

# given: synopsis

package main;

$assert = $assert->scalar;

# $assert->check(\1);

# true

The scalarref method configures the object to accept scalar references and returns the invocant.

scalarref(CodeRef $check) (Assert)

{ since => '1.71', }

=example-1 scalarref

# given: synopsis

package main;

$assert = $assert->scalarref;

# $assert->check(\1);

# true

The string method configures the object to accept string values and returns the invocant.

string(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 string

# given: synopsis

package main;

$assert = $assert->string;

# $assert->check('');

# true

The tuple method configures the object to accept array references which conform to a tuple specification, and returns the invocant. The value being evaluated must contain at-least one element to match.

tuple(Str | ArrayRef[Str] @types) (Assert)

{ since => '1.40', }

=example-1 tuple

# given: synopsis

package main;

$assert = $assert->tuple('number', ['maybe', 'array'], 'code');

# $assert->check([200, [], sub{}]);

# true

The undef method configures the object to accept undefined values and returns the invocant.

undef(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 undef

# given: synopsis

package main;

$assert = $assert->undef;

# $assert->check(undef);

# true

The validate method returns the data provided if the data provided passes the registered constraints, or throws an exception.

validate(Any $data) (Any)

{ since => '1.23', }

=example-1 validate

# given: synopsis

package main;

$assert->constraint(float => sub { $_->value > 1 });

my $result = $assert->validate;

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

The validator method returns a coderef that can be used as a value validator, which returns the data provided if the data provided passes the registered constraints, or throws an exception.

validator() (CodeRef)

{ since => '1.40', }

=example-1 validator

# given: synopsis

package main;

$assert->constraint(float => sub { $_->value > 1 });

my $result = $assert->validator;

# sub {...}

The value method configures the object to accept defined, non-reference, values, and returns the invocant.

value(CodeRef $check) (Assert)

{ since => '1.40', }

=example-1 value

# given: synopsis

package main;

$assert = $assert->value;

# $assert->check(1_000_000);

# true

The within method configures the object, registering a constraint action as a sub-match operation, to accept array or hash based values, and returns a Venus::Assert instance for the sub-match operation (not the invocant). This operation can traverse blessed array or hash based values. The value being evaluated must contain at-least one element to match.

within(Str $type) (Assert)

{ since => '1.40', }

=example-1 within

# given: synopsis

package main;

my $within = $assert->within('array')->code;

my $action = $assert;

# $assert->check([]);

# false

# $assert->check([sub{}]);

# true

# $assert->check([{}]);

# false

# $assert->check(bless[]);

# false

# $assert->check(bless[sub{}]);

# true

The yesno method configures the object to accept a string value that's either "yes" or 1, "no" or 0, and returns the invocant.

yesno(CodeRef $check) (Assert)

{ since => '2.01', }

=example-1 yesno

# given: synopsis

package main;

$assert = $assert->yesno;

# $assert->check(undef);

# false

# $assert->check(0);

# true

# $assert->check('No');

# true

# $assert->check('n');

# true

# $assert->check(1);

# true

# $assert->check('Yes');

# true

# $assert->check('y');

# true

# $assert->check('Okay');

# false

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

cpanm Venus

perl -MCPAN -e shell
install Venus