/ 
Venus-4.15
River stage two • 3 direct dependents • 56 total dependents
/ Venus::Unpack

NAME

Venus::Unpack - Unpack Class

ABSTRACT

Unpack Class for Perl 5

SYNOPSIS

package main;

use Venus::Unpack;

my $unpack = Venus::Unpack->new(args => ["hello", 123, 1.23]);

# my $args = $unpack->all->types('string', 'number', 'float')->args;

# ["hello", 123, 1.23]

DESCRIPTION

This package provides methods for validating, coercing, and otherwise operating on lists of arguments.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

METHODS

This package provides the following methods:

all

all() (Venus::Unpack)

The all method selects all arguments for processing returns the invocant.

Since 2.01

all example 1
# given: synopsis

package main;

$unpack = $unpack->all;

# bless(..., 'Venus::Unpack')

arg

arg(string $index) (any)

The arg method returns the argument at the index specified.

Since 2.01

arg example 1
# given: synopsis

package main;

my $arg = $unpack->arg(0);

# "hello"
arg example 2
# given: synopsis

package main;

my $arg = $unpack->arg(1);

# 123
arg example 3
# given: synopsis

package main;

my $arg = $unpack->arg(2);

# 1.23

args

args(any @args) (arrayref)

The args method returns all arugments as an arrayref, or list in list context. If arguments are provided they will overwrite the existing arugment list.

Since 2.01

args example 1
# given: synopsis

package main;

my $args = $unpack->args;

# ["hello", 123, 1.23]
args example 2
# given: synopsis

package main;

my $args = $unpack->args(1.23, 123, "hello");

# [1.23, 123, "hello"]

array

array() (Venus::Array)

The array method returns the argument list as a Venus::Array object.

Since 2.01

array example 1
# given: synopsis

package main;

my $array = $unpack->array;

# bless(..., 'Venus::Array')

cast

cast(string $name) (arrayref)

The cast method processes the selected arguments, passing each value to the class name specified, or the "cast" in Venus::Type method, and returns results.

Since 2.01

cast example 1
# given: synopsis

package main;

my $cast = $unpack->all->cast;

# [
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::Number'),
#   bless(..., 'Venus::Float'),
# ]
cast example 2
# given: synopsis

package main;

my $cast = $unpack->all->cast('scalar');

# [
#   bless(..., 'Venus::Scalar'),
#   bless(..., 'Venus::Scalar'),
#   bless(..., 'Venus::Scalar'),
# ]

checks

checks(string @types) (arrayref)

The checks method processes the selected arguments, passing each value to the "check" in Venus::Assert method with the type expression provided, and returns results.

Since 2.01

checks example 1
# given: synopsis

package main;

my $checks = $unpack->all->checks('string');

# [true, false, false]
checks example 2
# given: synopsis

package main;

my $checks = $unpack->all->checks('string | number');

# [true, true, false]
checks example 3
# given: synopsis

package main;

my $checks = $unpack->all->checks('string | number', 'float');

# [true, false, true]
checks example 4
# given: synopsis

package main;

my $checks = $unpack->all->checks('string', 'number', 'float');

# [true, true, true]
checks example 5
# given: synopsis

package main;

my $checks = $unpack->all->checks('boolean', 'value');

# [false, true, true]

copy

copy(string @pairs) (Venus::Unpack)

The copy method copies values from the arugment list as properties of the underlying object and returns the invocant.

Since 2.01

copy example 1
# given: synopsis

package main;

$unpack = $unpack->copy(0 => 'arg1');

# bless({..., arg1 => 'hello'}, 'Venus::Unpack')
copy example 2
# given: synopsis

package main;

$unpack = $unpack->copy(0 => 'arg1', 2 => 'arg3');

# bless({..., arg1 => 'hello', arg3 => 1.23}, 'Venus::Unpack')
copy example 3
# given: synopsis

package main;

$unpack = $unpack->copy(0 => 'arg1', 1 => 'arg2', 2 => 'arg3');

# bless({..., arg1 => 'hello', arg2 => 123, arg3 => 1.23}, 'Venus::Unpack')

first

first() (Venus::Unpack)

The first method selects the first argument for processing returns the invocant.

Since 2.01

first example 1
# given: synopsis

package main;

$unpack = $unpack->first;

# bless(..., 'Venus::Unpack')

from

from(string $data) (Venus::Unpack)

The from method names the source of the unpacking operation and is used in exception messages whenever the "signature" in Venus::Unpack operation fails. This method returns the invocant.

Since 2.23

from example 1
# given: synopsis

package main;

$unpack = $unpack->from;

# bless(..., 'Venus::Unpack')
from example 2
# given: synopsis

package main;

$unpack = $unpack->from('Example');

# bless(..., 'Venus::Unpack')

get

get(string $index) (any)

The get method returns the argument at the index specified.

Since 2.01

get example 1
# given: synopsis

package main;

my $get = $unpack->get;

# undef
get example 2
# given: synopsis

package main;

my $get = $unpack->get(0);

# "hello"
get example 3
# given: synopsis

package main;

my $get = $unpack->get(1);

# 123
get example 4
# given: synopsis

package main;

my $get = $unpack->get(2);

# 1.23
get example 5
# given: synopsis

package main;

my $get = $unpack->get(3);

# undef

into

into(string @args) (any)

The into method processes the selected arguments, passing each value to the class name specified, and returns results.

Since 2.01

into example 1
# given: synopsis

package main;

my $cast = $unpack->all->into('Venus::String');

# [
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::String'),
# ]
into example 2
# given: synopsis

package main;

my $cast = $unpack->all->into('Venus::String', 'Venus::Number');

# [
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::Number'),
#   bless(..., 'Venus::Number'),
# ]
into example 3
# given: synopsis

package main;

my $cast = $unpack->all->into('Venus::String', 'Venus::Number', 'Venus::Float');

# [
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::Number'),
#   bless(..., 'Venus::Float'),
# ]

last

last() (Venus::Unpack)

The last method selects the last argument for processing returns the invocant.

Since 2.01

last example 1
# given: synopsis

package main;

$unpack = $unpack->last;

# bless(..., 'Venus::Unpack')

list

list(string | coderef $code, any @args) (arrayref)

The list method returns the result of the dispatched method call as an arrayref, or list in list context.

Since 2.01

list example 1
# given: synopsis

package main;

my (@args) = $unpack->all->list('cast');

# (
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::Number'),
#   bless(..., 'Venus::Float'),
# )
list example 2
# given: synopsis

package main;

my ($string) = $unpack->all->list('cast');

# (
#   bless(..., 'Venus::String'),
# )
list example 3
# given: synopsis

package main;

my (@args) = $unpack->all->list('cast', 'string');

# (
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::String'),
# )
list example 4
# given: synopsis

package main;

my (@args) = $unpack->use(0,2)->list('cast', 'string', 'float');

# (
#   bless(..., 'Venus::String'),
#   bless(..., 'Venus::Float'),
# )

move

move(string @pairs) (Venus::Unpack)

The move method moves values from the arugment list, reducing the arugment list, as properties of the underlying object and returns the invocant.

Since 2.01

move example 1
# given: synopsis

package main;

$unpack = $unpack->move(0 => 'arg1');

# bless({..., arg1 => 'hello'}, 'Venus::Unpack')
move example 2
# given: synopsis

package main;

$unpack = $unpack->move(0 => 'arg1', 2 => 'arg3');

# bless({..., arg1 => 'hello', arg3 => 1.23}, 'Venus::Unpack')
move example 3
# given: synopsis

package main;

$unpack = $unpack->move(0 => 'arg1', 1 => 'arg2', 2 => 'arg3');

# bless({..., arg1 => 'hello', arg2 => 123, arg3 => 1.23}, 'Venus::Unpack')

name

name(string $data) (Venus::Unpack)

The name method names the unpacking operation and is used in exception messages whenever the "signature" in Venus::Unpack operation fails. This method returns the invocant.

Since 2.23

name example 1
# given: synopsis

package main;

$unpack = $unpack->name;

# bless(..., 'Venus::Unpack')
name example 2
# given: synopsis

package main;

$unpack = $unpack->name('example');

# bless(..., 'Venus::Unpack')

one

one(string | coderef $code, any @args) (any)

The one method returns the first result of the dispatched method call.

Since 2.01

one example 1
# given: synopsis

package main;

my $one = $unpack->all->one('cast');

# (
#   bless(..., 'Venus::String'),
# )
one example 2
# given: synopsis

package main;

my $one = $unpack->all->one('cast', 'string');

# (
#   bless(..., 'Venus::String'),
# )

reset

reset(any @args) (Venus::Unpack)

The reset method resets the arugments list (if provided) and deselects all arguments (selected for processing) and returns the invocant.

Since 2.01

reset example 1
# given: synopsis

package main;

$unpack = $unpack->all->reset;

# bless(..., 'Venus::Unpack')
reset example 2
# given: synopsis

package main;

$unpack = $unpack->all->reset(1.23, 123, "hello");

# bless(..., 'Venus::Unpack')

set

set(string $index, any $value) (any)

The set method assigns the value provided at the index specified and returns the value.

Since 2.01

set example 1
# given: synopsis

package main;

my $set = $unpack->set;

# ["hello", 123, 1.23]
set example 2
# given: synopsis

package main;

my $set = $unpack->set(0, 'howdy');

# "howdy"
set example 3
# given: synopsis

package main;

my $set = $unpack->set(1, 987);

# 987
set example 4
# given: synopsis

package main;

my $set = $unpack->set(2, 12.3);

# 12.3
set example 5
# given: synopsis

package main;

my $set = $unpack->set(3, 'goodbye');

# "goodbye"

signature

signature(string $name, string @types) (arrayref)

The signature method processes the selected arguments, passing each value to the "validate" in Venus::Assert method with the type expression provided and throws an exception on failure and otherise returns the results as an arrayref, or as a list in list context.

Since 2.01

signature example 1
# given: synopsis

package main;

my ($string, $number, $float) = $unpack->all->name('example-1')->signature(
  'string | number | float',
);

# ("hello", 123, 1.23)
signature example 2
 # given: synopsis

 package main;

 my ($string, $number, $float) = $unpack->all->name('example-2')->signature(
   'string', 'number', 'float',
);

 # ("hello", 123, 1.23)
signature example 3
# given: synopsis

package main;

my $results = $unpack->all->name('example-3')->signature(
  'string', 'number',
);

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

package main;

my $results = $unpack->all->name('example-4')->signature(
  'string',
);

# Exception! (isa Venus::Check::Error)
signature example 5
# given: synopsis

package main;

my $results = $unpack->all->name('example-5')->from('t/Venus_Unpack.t')->signature(
  'object',
);

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

types

types(string @types) (Venus::Unpack)

The types method processes the selected arguments, passing each value to the "validate" in Venus::Assert method with the type expression provided, and unlike the "validate" method returns the invocant.

Since 2.01

types example 1
# given: synopsis

package main;

$unpack = $unpack->all->types('string | number | float');

# bless({...}, 'Venus::Unpack')
types example 2
# given: synopsis

package main;

$unpack = $unpack->all->types('string', 'number', 'float');

# bless({...}, 'Venus::Unpack')
types example 3
# given: synopsis

package main;

$unpack = $unpack->all->types('string', 'number');

# Exception! (isa Venus::Error)

# argument #3 error
types example 4
# given: synopsis

package main;

$unpack = $unpack->all->types('string');

# Exception! (isa Venus::Error)

# argument #2 error

use

use(number @args) (Venus::Unpack)

The use method selects the arguments specified (by index) for processing returns the invocant.

Since 2.01

use example 1
# given: synopsis

package main;

$unpack = $unpack->use(1,2);

# bless(..., 'Venus::Unpack')
use example 2
# given: synopsis

package main;

$unpack = $unpack->use(1,0);

# bless(..., 'Venus::Unpack')
use example 3
# given: synopsis

package main;

$unpack = $unpack->use(2,1,0);

# bless(..., 'Venus::Unpack')

validate

validate(string @types) (Venus::Unpack)

The validate method processes the selected arguments, passing each value to the "validate" in Venus::Assert method with the type expression provided and throws an exception on failure and otherise returns the resuts.

Since 2.01

validate example 1
# given: synopsis

package main;

my $results = $unpack->all->validate('string | number | float');

# ["hello", 123, 1.23]
validate example 2
# given: synopsis

package main;

my $results = $unpack->all->validate('string', 'number', 'float');

# ["hello", 123, 1.23]
validate example 3
# given: synopsis

package main;

my $results = $unpack->all->validate('string', 'number');

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

package main;

my $results = $unpack->all->validate('string');

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

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.