NAME

Venus::Role::Makeable - Makeable Role

ABSTRACT

Makeable Role for Perl 5

SYNOPSIS

  package Person;
  use Venus::Class 'attr', 'error', 'with';
  with 'Venus::Role::Makeable';
  attr 'name';
  attr 'father';
  attr 'mother';
  attr 'siblings';
  sub make {
    my ($self, $value) = @_;
    error if !ref $value;
    return $self->new($value);
  }
  sub makers {
    {
      father => 'Person',
      mother => 'Person',
      name => 'Venus/String',
      siblings => 'Person',
    }
  }
  sub make_name {
    my ($self, $code, @args) = @_;
    return $self->$code(@args);
  }
  sub make_siblings {
    my ($self, $code, $class, $value) = @_;
    return [map $self->$code($class, $_), @$value];
  }
  package main;
  my $person = Person->make({
    name => 'me',
    father => {name => 'father'},
    mother => {name => 'mother'},
    siblings => [{name => 'brother'}, {name => 'sister'}],
  });
  # $person
  # bless({...}, 'Person')
  # $person->name
  # bless({...}, 'Venus::String')
  # $person->father
  # bless({...}, 'Person')
  # $person->mother
  # bless({...}, 'Person')
  # $person->siblings
  # [bless({...}, 'Person'), bless({...}, 'Person'), ...]

DESCRIPTION

This package modifies the consuming package and provides methods for hooking into object construction and coercing arguments into objects and values using the "make" protocol, i.e. using the "make" method (which performs fatal type checking and coercions) instead of the typical "new" method.

METHODS

This package provides the following methods:

make_args

  make_args(hashref $data, hashref $spec) (hashref)

The make_args method replaces values in the data provided with objects corresponding to the specification provided. The specification should contains key/value pairs where the keys map to class attributes (or input parameters) and the values are Venus::Space compatible package names.

Since 1.30

make_args example 1

  package main;
  my $person = Person->new;
  my $data = $person->make_args(
    {
      father => { name => 'father' }
    },
    {
      father => 'Person',
    },
  );
  # {
  #   father   => bless({...}, 'Person'),
  # }

make_attr

  make_attr(string $name, any $value) (any)

The make_attr method is a surrogate accessor and gets and/or sets an instance attribute based on the "makers" rules, returning the made value.

Since 1.30

make_attr example 1

  # given: synopsis
  package main;
  $person = Person->new(
    name => 'me',
  );
  my $make_name = $person->make_attr('name');
  # bless({value => "me"}, "Venus::String")

make_attr example 2

  # given: synopsis
  package main;
  $person = Person->new(
    name => 'me',
  );
  my $make_name = $person->make_attr('name', 'myself');
  # bless({value => "myself"}, "Venus::String")

make_into

  make_into(string $class, any $value) (object)

The make_into method attempts to build and return an object based on the class name and value provided, unless the value provided is already an object derived from the specified class.

Since 1.30

make_into example 1

  package main;
  my $person = Person->new;
  my $friend = $person->make_into('Person', {
    name => 'friend',
  });
  # bless({...}, 'Person')

make_onto

  make_onto(hashref $data, string $name, string $class, any $value) (object)

The make_onto method attempts to build and assign an object based on the class name and value provided, as the value corresponding to the name specified, in the data provided. If the $value is omitted, the value corresponding to the name in the $data will be used.

Since 1.30

make_onto example 1

  package main;
  my $person = Person->new;
  my $data = { friend => { name => 'friend' } };
  my $friend = $person->make_onto($data, 'friend', 'Person');
  # bless({...}, 'Person'),
  # $data was updated
  #
  # {
  #   friend => bless({...}, 'Person'),
  # }

make_onto example 2

  package Player;
  use Venus::Class;
  with 'Venus::Role::Makeable';
  attr 'name';
  attr 'teammates';
  sub makers {
    {
      teammates => 'Person',
    }
  }
  sub make_into_person {
    my ($self, $class, $value) = @_;
    return $class->make($value);
  }
  sub make_into_venus_string {
    my ($self, $class, $value) = @_;
    return $class->make($value);
  }
  sub make_teammates {
    my ($self, $code, $class, $value) = @_;
    return [map $self->$code($class, $_), @$value];
  }
  package main;
  my $player = Player->new;
  my $data = { teammates => [{ name => 'player2' }, { name => 'player3' }] };
  my $teammates = $player->make_onto($data, 'teammates', 'Person');
  # [bless({...}, 'Person'), bless({...}, 'Person')]
  # $data was updated
  #
  # {
  #   teammates => [bless({...}, 'Person'), bless({...}, 'Person')],
  # }

makers

  makers() (hashref)

The makers method, if defined, is called during object construction, or by the "making" method, and returns key/value pairs where the keys map to class attributes (or input parameters) and the values are Venus::Space compatible package names.

Since 1.30

makers example 1

  package main;
  my $person = Person->new(
    name => 'me',
  );
  my $makers = $person->makers;
  # {
  #   father   => "Person",
  #   mother   => "Person",
  #   name     => "Venus/String",
  #   siblings => "Person",
  # }

making

  making(hashref $data) (hashref)

The making method is called automatically during object construction but can be called manually as well, and is passed a hashref to make and return.

Since 1.30

making example 1

  package main;
  my $person = Person->new;
  my $making = $person->making({
    name => 'me',
  });
  # $making
  # {...}
  # $making->{name}
  # bless({...}, 'Venus::String')
  # $making->{father}
  # undef
  # $making->{mother}
  # undef
  # $making->{siblings}
  # undef

making example 2

  package main;
  my $person = Person->new;
  my $making = $person->making({
    name => 'me',
    mother => {name => 'mother'},
    siblings => [{name => 'brother'}, {name => 'sister'}],
  });
  # $making
  # {...}
  # $making->{name}
  # bless({...}, 'Venus::String')
  # $making->{father}
  # undef
  # $making->{mother}
  # bless({...}, 'Person')
  # $making->{siblings}
  # [bless({...}, 'Person'), bless({...}, 'Person'), ...]

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.