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

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