NAME

Venus::Assert - Assert Class

ABSTRACT

Assert Class for Perl 5

SYNOPSIS


            
              
              package main;
use Venus::Assert;
my $assert = Venus::Assert->new('Float');
# $assert->accept('float');
# $assert->format(sub{sprintf('%.2f', $_)});
# $assert->result(123.456);
# 123.46

DESCRIPTION

This package provides a mechanism for asserting type constraints and coercions on data. Type constraints are handled via Venus::Constraint, and coercions are handled via Venus::Coercion, using Venus::Check to perform data type validations.

ATTRIBUTES

This package has the following attributes:

name


            
              
              name(string $data) (string)

The name attribute is read-write, accepts (string) values, and is optional.

Since 1.40

name example 1


            
              
              # given: synopsis
package main;
my $set_name = $assert->name("Example");
# "Example"

name example 2


            
              
              # given: synopsis
# given: example-1 name
package main;
my $get_name = $assert->name;
# "Example"

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Buildable

METHODS

This package provides the following methods:

accept


            
              
              accept(string $name, any @args) (Venus::Assert)

The accept method registers a condition via "check" based on the arguments provided. The built-in types are defined as methods in Venus::Check.

Since 1.40

accept example 1


            
              
              # given: synopsis
package main;
$assert = $assert->accept('float');
# bless(..., "Venus::Assert")
# $assert->valid;
# false
# $assert->valid(1.01);
# true

accept example 2


            
              
              # given: synopsis
package main;
$assert = $assert->accept('number');
# bless(..., "Venus::Assert")
# $assert->valid(1.01);
# false
# $assert->valid(1_01);
# true

accept example 3


            
              
              # given: synopsis
package Example1;
sub new {
  bless {};
}
package Example2;
sub new {
  bless {};
}
package main;
$assert = $assert->accept('object');
# bless(..., "Venus::Assert")
# $assert->valid;
# false
# $assert->valid(qr//);
# false
# $assert->valid(Example1->new);
# true
# $assert->valid(Example2->new);
# true

accept example 4


            
              
              # given: synopsis
package Example1;
sub new {
  bless {};
}
package Example2;
sub new {
  bless {};
}
package main;
$assert = $assert->accept('Example1');
# bless(..., "Venus::Assert")
# $assert->valid;
# false
# $assert->valid(qr//);
# false
# $assert->valid(Example1->new);
# true
# $assert->valid(Example2->new);
# false

check


            
              
              check(Venus::Check $data) (Venus::Check)

The check method gets or sets the Venus::Check object used for performing runtime data type validation.

Since 3.55

check example 1


            
              
              # given: synopsis
package main;
my $check = $assert->check(Venus::Check->new);
# bless(..., 'Venus::Check')

check example 2


            
              
              # given: synopsis
package main;
$assert->check(Venus::Check->new);
my $check = $assert->check;
# bless(..., 'Venus::Check')

clear


            
              
              clear() (Venus::Assert)

The clear method resets the "check", "constraint", and "coercion" attributes and returns the invocant.

Since 1.40

clear example 1


            
              
              # given: synopsis
package main;
$assert->accept('string');
$assert = $assert->clear;
# bless(..., "Venus::Assert")

coerce


            
              
              coerce(any $data) (any)

The coerce method dispatches to the "coercion" object and returns the result of the "result" in Venus::Coercion operation.

Since 3.55

coerce example 1


            
              
              # given: synopsis
package main;
$assert->accept('float');
$assert->format(sub{sprintf('%.2f', $_)});
my $coerce = $assert->coerce(123.456);
# 123.46

coerce example 2


            
              
              # given: synopsis
package main;
$assert->accept('string');
$assert->format(sub{ucfirst lc $_});
my $coerce = $assert->coerce('heLLo');
# "Hello"

coercion


            
              
              coercion(Venus::Coercion $data) (Venus::Coercion)

The coercion method gets or sets the Venus::Coercion object used for performing runtime data type coercions.

Since 3.55

coercion example 1


            
              
              # given: synopsis
package main;
my $coercion = $assert->coercion(Venus::Coercion->new);
# bless(..., 'Venus::Coercion')

coercion example 2


            
              
              # given: synopsis
package main;
$assert->coercion(Venus::Coercion->new);
my $coercion = $assert->coercion;
# bless(..., 'Venus::Coercion')

conditions


            
              
              conditions() (Venus::Assert)

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.

Since 1.40

conditions example 1


            
              
              # given: synopsis
package main;
$assert = $assert->conditions;
# bless(..., 'Venus::Assert')

conditions example 2


            
              
              package Example::Type::PositveNumber;
use base 'Venus::Assert';
sub conditions {
  my ($self) = @_;
  $self->accept('number', sub {
    $_ >= 0
  });
  return $self;
}
package main;
my $assert = Example::Type::PositveNumber->new;
# $assert->valid(0);
# true
# $assert->valid(1);
# true
# $assert->valid(-1);
# false

constraint


            
              
              constraint(Venus::Constraint $data) (Venus::Constraint)

The constraint method gets or sets the Venus::Constraint object used for performing runtime data type constraints.

Since 3.55

constraint example 1


            
              
              # given: synopsis
package main;
my $constraint = $assert->constraint(Venus::Constraint->new);
# bless(..., 'Venus::Constraint')

constraint example 2


            
              
              # given: synopsis
package main;
$assert->constraint(Venus::Constraint->new);
my $constraint = $assert->constraint;
# bless(..., 'Venus::Constraint')

ensure


            
              
              ensure(coderef $code) (Venus::Assert)

The ensure method registers a custom (not built-in) constraint condition and returns the invocant.

Since 3.55

ensure example 1


            
              
              # given: synopsis
package main;
$assert->accept('number');
my $ensure = $assert->ensure(sub {
  $_ >= 0
});
# bless(.., "Venus::Assert")

expression


            
              
              expression(string $expr) (Venus::Assert)

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

Since 1.71

expression example 1


            
              
              # given: synopsis
package main;
$assert = $assert->expression('string');
# bless(..., 'Venus::Assert')
# $assert->valid('hello');
# true
# $assert->valid(['goodbye']);
# false

expression example 2


            
              
              # given: synopsis
package main;
$assert = $assert->expression('string | coderef');
# bless(..., 'Venus::Assert')
# $assert->valid('hello');
# true
# $assert->valid(sub{'hello'});
# true
# $assert->valid(['goodbye']);
# false

expression example 3


            
              
              # given: synopsis
package main;
$assert = $assert->expression('string | coderef | Venus::Assert');
# bless(..., 'Venus::Assert')
# $assert->valid('hello');
# true
# $assert->valid(sub{'hello'});
# true
# $assert->valid($assert);
# true
# $assert->valid(['goodbye']);
# false

expression example 4


            
              
              # given: synopsis
package main;
$assert = $assert->expression('Venus::Assert | within[arrayref, Venus::Assert]');
# bless(..., 'Venus::Assert')
# $assert->valid('hello');
# false
# $assert->valid(sub{'hello'});
# false
# $assert->valid($assert);
# true
# $assert->valid(['goodbye']);
# false
# $assert->valid([$assert]);
# true

expression example 5


            
              
              # given: synopsis
package main;
$assert = $assert->expression('
  string
  | within[
      arrayref, within[
        hashref, string
      ]
    ]
');
# bless(..., 'Venus::Assert')
# $assert->valid('hello');
# true
# $assert->valid(sub{'hello'});
# false
# $assert->valid($assert);
# false
# $assert->valid([]);
# false
# $assert->valid([{'test' => ['okay']}]);
# false
# $assert->valid([{'test' => 'okay'}]);
# true

format


            
              
              format(coderef $code) (Venus::Assert)

The format method registers a custom (not built-in) coercion condition and returns the invocant.

Since 3.55

format example 1


            
              
              # given: synopsis
package main;
$assert->accept('number');
my $format = $assert->format(sub {
  sprintf '%.2f', $_
});
# bless(.., "Venus::Assert")

parse


            
              
              parse(string $expr) (any)

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

Since 2.01

parse example 1


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('');
# ['']

parse example 2


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('any');
# ['any']

parse example 3


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('string | number');
# ['either', 'string', 'number']

parse example 4


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('enum[up,down,left,right]');
# [['enum', 'up', 'down', 'left', 'right']]

parse example 5


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('number | float | boolean');
# ['either', 'number', 'float', 'boolean']

parse example 6


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('Example');
# ['Example']

parse example 7


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('coderef | Venus::Code');
# ['either', 'coderef', 'Venus::Code']

parse example 8


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('tuple[number, arrayref, coderef]');
# [['tuple', 'number', 'arrayref', 'coderef']]

parse example 9


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse('tuple[number, within[arrayref, hashref], coderef]');
# [['tuple', 'number', ['within', 'arrayref', 'hashref'], 'coderef']]

parse example 10


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse(
  'tuple[number, within[arrayref, hashref] | arrayref, coderef]'
);
# [
#   ['tuple', 'number',
#     ['either', ['within', 'arrayref', 'hashref'], 'arrayref'], 'coderef']
# ]

parse example 11


            
              
              # given: synopsis
package main;
my $parsed = $assert->parse(
  'hashkeys["id", number | float, "upvotes", within[arrayref, boolean]]'
);
# [[
#   'hashkeys',
#   'id',
#     ['either', 'number', 'float'],
#   'upvotes',
#     ['within', 'arrayref', 'boolean']
# ]]

render


            
              
              render(string $into, string $expression) (string)

The render method builds and returns a type expressions suitable for providing to "expression" based on the data provided.

Since 2.55

render example 1


            
              
              # given: synopsis
package main;
$assert = $assert->render;
# undef

render example 2


            
              
              # given: synopsis
package main;
$assert = $assert->render(undef, 'string');
# "string"

render example 3


            
              
              # given: synopsis
package main;
$assert = $assert->render('routines', ['say', 'say_pretty']);
# 'routines["say", "say_pretty"]'

render example 4


            
              
              # given: synopsis
package main;
$assert = $assert->render('hashkeys', {id => 'number', name => 'string'});
# 'hashkeys["id", number, "name", string]'

render example 5


            
              
              # given: synopsis
package main;
$assert = $assert->render('hashkeys', {
  id => 'number',
  profile => {
    level => 'string',
  },
});
# 'hashkeys["id", number, "profile", hashkeys["level", string]]'

result


            
              
              result(any $data) (any)

The result method validates the value provided against the registered constraints and if valid returns the result of the value having any registered coercions applied. If the value is invalid an exception from Venus::Check will be thrown.

Since 3.55

result example 1


            
              
              # given: synopsis
package main;
$assert->accept('number')->format(sub{sprintf '%.2f', $_});
my $result = $assert->result(1);
# "1.00"

result example 2


            
              
              # given: synopsis
package main;
$assert->accept('number')->format(sub{sprintf '%.2f', $_});
my $result = $assert->result('hello');
# Exception! (isa Venus::Check::Error) (see error_on_coded)

valid


            
              
              valid(any $data) (any)

The valid method dispatches to the "constraint" object and returns the result of the "result" in Venus::Constraint operation.

Since 3.55

valid example 1


            
              
              # given: synopsis
package main;
$assert->accept('float');
$assert->ensure(sub{$_ >= 1});
my $valid = $assert->valid('1.00');
# true

valid example 2


            
              
              # given: synopsis
package main;
$assert->accept('float');
$assert->ensure(sub{$_ >= 1});
my $valid = $assert->valid('0.99');
# false

validate


            
              
              validate(any $data) (any)

The validate method validates the value provided against the registered constraints and if valid returns the value. If the value is invalid an exception from Venus::Check will be thrown.

Since 3.55

validate example 1


            
              
              # given: synopsis
package main;
$assert->accept('number');
my $validate = $assert->validate(1);
# 1

validate example 2


            
              
              # given: synopsis
package main;
$assert->accept('number');
my $validate = $assert->validate('hello');
# Exception! (isa Venus::Check::Error) (see error_on_coded)

validator


            
              
              validator(any @args) (coderef)

The validator method returns a coderef which calls the "validate" method with the invocant when called.

Since 3.55

validator example 1


            
              
              # given: synopsis
package main;
$assert->accept('string');
my $validator = $assert->validator;
# sub{...}
# my $result = $validator->();
# Exception! (isa Venus::Check::Error) (see error_on_coded)

validator example 2


            
              
              # given: synopsis
package main;
$assert->accept('string');
my $validator = $assert->validator;
# sub{...}
# my $result = $validator->('hello');
# "hello"

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.

To install Venus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Venus

CPAN shell

perl -MCPAN -e shell
install Venus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

ABSTRACT

SYNOPSIS

DESCRIPTION

ATTRIBUTES

name

INHERITS

INTEGRATES

METHODS

accept

check

clear

coerce

coercion

conditions

constraint

ensure

expression

format

parse

render

result

valid

validate

validator

AUTHORS

LICENSE

Module Install Instructions