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

NAME

Venus::Schema - Schema Class

ABSTRACT

Schema Class for Perl 5

SYNOPSIS

package main;

use Venus::Schema;

my $schema = Venus::Schema->new;

# bless({...}, 'Venus::Schema')

# $schema->validate;

# ([], undef)

DESCRIPTION

This package provides a mechanism for validating complex data structures using data validation rules provided as a ruleset.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Encaseable

METHODS

This package provides the following methods:

new

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

The new method constructs an instance of the package.

Since 4.15

new example 1
package main;

use Venus::Schema;

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

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

rule

rule(hashref $rule) (Venus::Schema)

The rule method appends a new rule to the "ruleset" to be used during "validate", and returns the invocant. A "rule" is a hashref that consists of an optional selector key whose value will be provided to the "select" in Venus::Validate method, a presence key whose value must be one of the "required", "optional", or "present" Venus::Validate methods, and a executes key whose value must be an arrayref where each element is a Venus::Validate validation method name or an arrayref with a method name and arguments.

Since 4.15

rule example 1
# given: synopsis

package main;

my $rule = $schema->rule;

# bless({...}, 'Venus::Schema')
rule example 2
# given: synopsis

package main;

my $rule = $schema->rule({
  presence => 'required',
  executes => ['string'],
});

# bless({...}, 'Venus::Schema')
rule example 3
# given: synopsis

package main;

my $rule = $schema->rule({
  selector => 'name',
  presence => 'required',
  executes => ['string'],
});

# bless({...}, 'Venus::Schema')
rule example 4
# given: synopsis

package main;

my $rule = $schema->rule({
  selector => 'name',
  presence => 'required',
  executes => [['type', 'string']],
});

# bless({...}, 'Venus::Schema')

rules

rules(hashref @rules) (Venus::Schema)

The rules method appends new rules to the "ruleset" using the "rule" method and returns the invocant.

Since 4.15

rules example 1
# given: synopsis

package main;

my $rules = $schema->rules;

# bless(..., "Venus::Schema")
rules example 2
# given: synopsis

package main;

my $rules = $schema->rules({
  presence => 'required',
  executes => ['string'],
});

# bless(..., "Venus::Schema")
rules example 3
# given: synopsis

package main;

my $rules = $schema->rules(
  {
    selector => 'first_name',
    presence => 'required',
    executes => ['string'],
  },
  {
    selector => 'last_name',
    presence => 'required',
    executes => ['string'],
  }
);

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

ruleset

ruleset(arrayref $ruleset) (arrayref)

The ruleset method gets and sets the "rules" to be used during "validation".

Since 4.15

ruleset example 1
# given: synopsis

package main;

my $ruleset = $schema->ruleset;

# []
ruleset example 2
# given: synopsis

package main;

my $ruleset = $schema->ruleset([
  {
    selector => 'first_name',
    presence => 'required',
    executes => ['string'],
  },
  {
    selector => 'last_name',
    presence => 'required',
    executes => ['string'],
  }
]);

# [
#   {
#     selector => 'first_name',
#     presence => 'required',
#     executes => ['string'],
#   },
#   {
#     selector => 'last_name',
#     presence => 'required',
#     executes => ['string'],
#   }
# ]

shorthand

shorthand(arrayref | hashref $data) (arrayref)

The shorthand method accepts an arrayref or hashref of shorthand notation and returns a ruleset arrayref. This provides a concise way to define validation rules. Keys can have suffixes to indicate presence: ! for (explicit) required, ? (explicit) for optional, * for (explicit) present (i.e., must exist but can be null), and no suffix means (implicit) required. Keys using dot notation (e.g., website.url) result in arrayref selectors for nested path validation.

Since 4.15

shorthand example 1
# given: synopsis

package main;

my $shorthand = $schema->shorthand([
  'fname!' => 'string',
  'lname!' => 'string',
]);

# [
#   {
#     selector => 'fname',
#     presence => 'required',
#     execute => 'string',
#   },
#   {
#     selector => 'lname',
#     presence => 'required',
#     execute => 'string',
#   },
# ]
shorthand example 2
# given: synopsis

package main;

my $shorthand = $schema->shorthand([
  'email?' => 'string',
  'age*' => 'number',
]);

# [
#   {
#     selector => 'email',
#     presence => 'optional',
#     execute => 'string',
#   },
#   {
#     selector => 'age',
#     presence => 'present',
#     execute => 'number',
#   },
# ]
shorthand example 3
# given: synopsis

package main;

my $shorthand = $schema->shorthand([
  'login' => 'string',
  'password' => 'string',
]);

# [
#   {
#     selector => 'login',
#     presence => 'required',
#     execute => 'string',
#   },
#   {
#     selector => 'password',
#     presence => 'required',
#     execute => 'string',
#   },
# ]
shorthand example 4
# given: synopsis

package main;

my $shorthand = $schema->shorthand([
  'website.url' => 'string',
  'profile.bio.text' => 'string',
]);

# [
#   {
#     selector => ['website', 'url'],
#     presence => 'required',
#     execute => 'string',
#   },
#   {
#     selector => ['profile', 'bio', 'text'],
#     presence => 'required',
#     execute => 'string',
#   },
# ]
shorthand example 5
package main;

use Venus::Schema;

my $schema = Venus::Schema->new;

my $ruleset = $schema->shorthand([
  'fname!' => 'string',
  'lname!' => 'string',
  'email?' => 'string',
  'login' => 'string',
]);

$schema->rules(@{$ruleset});

my $input = {
  fname => 'Elliot',
  lname => 'Alderson',
  login => 'mrrobot',
};

my $errors = $schema->validate($input);

# []

validate

validate(any $data) (arrayref)

The validate method validates the data provided using the "ruleset" and returns an arrayref containing the errors encountered, if any. Returns the errors arrayref, and the data validated in list context.

Since 4.15

validate example 1
package main;

use Venus::Schema;

my $schema = Venus::Schema->new;

my $errors = $schema->validate;

# []
validate example 2
package main;

use Venus::Schema;

my $schema = Venus::Schema->new;

$schema->rule({
  selector => 'handles',
  presence => 'required',
  executes => [['type', 'arrayref']],
});

my $errors = $schema->validate;

# [['handles', ['required', []]]]
validate example 3
package main;

use Venus::Schema;

my $schema = Venus::Schema->new;

my $input = {
  fname => 'Elliot',
  lname => 'Alderson',
  handles => [
    {name => 'mrrobot'},
    {name => 'fsociety'},
  ],
  level => 5,
  skills => undef,
  role => 'Engineer',
};

$schema->rule({
  selector => 'fname',
  presence => 'required',
  executes => ['string', 'trim', 'strip'],
});

$schema->rule({
  selector => 'lname',
  presence => 'required',
  executes => ['string', 'trim', 'strip'],
});

$schema->rule({
  selector => 'skills',
  presence => 'present',
});

$schema->rule({
  selector => 'handles',
  presence => 'required',
  executes => [['type', 'arrayref']],
});

$schema->rule({
  selector => ['handles', 'name'],
  presence => 'required',
  executes => ['string', 'trim', 'strip'],
});

my $errors = $schema->validate($input);

# []
validate example 4
package main;

use Venus::Schema;

my $schema = Venus::Schema->new;

my $input = {
  fname => 'Elliot',
  lname => 'Alderson',
  handles => [
    {name => 'mrrobot'},
    {name => 'fsociety'},
  ],
  level => 5,
  skills => undef,
  role => 'Engineer',
};

$schema->rule({
  selector => 'fname',
  presence => 'required',
  executes => ['string', 'trim', 'strip'],
});

$schema->rule({
  selector => 'lname',
  presence => 'required',
  executes => ['string', 'trim', 'strip'],
});

$schema->rule({
  selector => 'skills',
  presence => 'required',
});

$schema->rule({
  selector => 'handles',
  presence => 'required',
  executes => [['type', 'arrayref']],
});

$schema->rule({
  selector => ['handles', 'name'],
  presence => 'required',
  executes => ['string', 'trim', 'strip'],
});

my $errors = $schema->validate($input);

# [['skills', ['required', []]]]

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.