NAME

Venus::Meta - Class Metadata

ABSTRACT

Class Metadata for Perl 5

SYNOPSIS

  package Person;
  use Venus::Class;
  attr 'fname';
  attr 'lname';
  package Identity;
  use Venus::Role;
  attr 'id';
  attr 'login';
  attr 'password';
  sub EXPORT {
    # explicitly declare routines to be consumed
    ['id', 'login', 'password']
  }
  package Authenticable;
  use Venus::Role;
  sub authenticate {
    return true;
  }
  sub AUDIT {
    my ($self, $from) = @_;
    # ensure the caller has a login and password when consumed
    die "${from} missing the login attribute" if !$from->can('login');
    die "${from} missing the password attribute" if !$from->can('password');
  }
  sub EXPORT {
    # explicitly declare routines to be consumed
    ['authenticate']
  }
  package Novice;
  use Venus::Mixin;
  sub points {
    100
  }
  package User;
  use Venus::Class 'attr', 'base', 'mixin', 'test', 'with';
  base 'Person';
  with 'Identity';
  mixin 'Novice';
  attr 'email';
  test 'Authenticable';
  sub valid {
    my ($self) = @_;
    return $self->login && $self->password ? true : false;
  }
  package main;
  my $user = User->new(
    fname => 'Elliot',
    lname => 'Alderson',
  );
  my $meta = $user->meta;
  # bless({name => 'User'}, 'Venus::Meta')

DESCRIPTION

This package provides configuration information for Venus derived classes, roles, and interfaces.

METHODS

This package provides the following methods:

attr

  attr(string $name) (boolean)

The attr method returns true or false if the package referenced has the attribute accessor named.

Since 1.00

attr example 1

  # given: synopsis
  package main;
  my $attr = $meta->attr('email');
  # 1

attr example 2

  # given: synopsis
  package main;
  my $attr = $meta->attr('username');
  # 0

attrs

  attrs() (arrayref)

The attrs method returns all of the attributes composed into the package referenced.

Since 1.00

attrs example 1

  # given: synopsis
  package main;
  my $attrs = $meta->attrs;
  # [
  #   'email',
  #   'fname',
  #   'id',
  #   'lname',
  #   'login',
  #   'password',
  # ]

base

  base(string $name) (boolean)

The base method returns true or false if the package referenced has inherited the package named.

Since 1.00

base example 1

  # given: synopsis
  package main;
  my $base = $meta->base('Person');
  # 1

base example 2

  # given: synopsis
  package main;
  my $base = $meta->base('Student');
  # 0

bases

  bases() (arrayref)

The bases method returns returns all of the packages inherited by the package referenced.

Since 1.00

bases example 1

  # given: synopsis
  package main;
  my $bases = $meta->bases;
  # [
  #   'Person',
  #   'Venus::Core::Class',
  #   'Venus::Core',
  # ]

data

  data() (hashref)

The data method returns a data structure representing the shallow configuration for the package referenced.

Since 1.00

data example 1

  # given: synopsis
  package main;
  my $data = $meta->data;
  # {
  #   'ATTR' => {
  #     'email' => [
  #       'email'
  #     ]
  #   },
  #   'BASE' => {
  #     'Person' => [
  #       'Person'
  #     ]
  #   },
  #   'ROLE' => {
  #     'Authenticable' => [
  #       'Authenticable'
  #     ],
  #     'Identity' => [
  #       'Identity'
  #     ]
  #   }
  # }

emit

  emit(string $name, any @args) (any)

The emit method invokes the lifecycle hook specified on the underlying package and returns the result.

Since 2.91

emit example 1

  # given: synopsis
  package main;
  my $result = $meta->emit('attr', 'mname');
  # "User"

find

  find(string $type, string $name) (tuple[string,tuple[number,arrayref]])

The find method finds and returns the first configuration for the property type specified. This method uses the "search" method to search "roles", "bases", "mixins", and the source package, in the order listed. The "property type" can be any one of "attr", "base", "mixin", or "role".

Since 1.02

find example 1

  # given: synopsis
  package main;
  my $find = $meta->find;
  # ()

find example 2

  # given: synopsis
  package main;
  my $find = $meta->find('attr', 'id');
  # ['Identity', [ 1, ['id']]]

find example 3

  # given: synopsis
  package main;
  my $find = $meta->find('sub', 'valid');
  # ['User', [1, [sub {...}]]]

find example 4

  # given: synopsis
  package main;
  my $find = $meta->find('sub', 'authenticate');
  # ['Authenticable', [1, [sub {...}]]]

local

  local(string $type) (arrayref)

The local method returns the names of properties defined in the package directly (not inherited) for the property type specified. The $type provided can be either "attrs", "bases", "roles", or "subs".

Since 1.02

local example 1

  # given: synopsis
  package main;
  my $attrs = $meta->local('attrs');
  # ['email']

local example 2

  # given: synopsis
  package main;
  my $bases = $meta->local('bases');
  # ['Person', 'Venus::Core::Class']

local example 3

  # given: synopsis
  package main;
  my $roles = $meta->local('roles');
  # ['Identity', 'Authenticable']

local example 4

  # given: synopsis
  package main;
  my $subs = $meta->local('subs');
  # [
  #   'attr',
  #   'authenticate',
  #   'base',
  #   'email',
  #   'false',
  #   'id',
  #   'login',
  #   'password',
  #   'test',
  #   'true',
  #   'valid',
  #   'with',
  # ]

mixin

  mixin(string $name) (boolean)

The mixin method returns true or false if the package referenced has consumed the mixin named.

Since 1.02

mixin example 1

  # given: synopsis
  package main;
  my $mixin = $meta->mixin('Novice');
  # 1

mixin example 2

  # given: synopsis
  package main;
  my $mixin = $meta->mixin('Intermediate');
  # 0

mixins

  mixins() (arrayref)

The mixins method returns all of the mixins composed into the package referenced.

Since 1.02

mixins example 1

  # given: synopsis
  package main;
  my $mixins = $meta->mixins;
  # [
  #   'Novice',
  # ]

new

  new(any %args | hashref $args) (object)

The new method returns a new instance of this package.

Since 1.00

new example 1

  # given: synopsis
  package main;
  $meta = Venus::Meta->new(name => 'User');
  # bless({name => 'User'}, 'Venus::Meta')

new example 2

  # given: synopsis
  package main;
  $meta = Venus::Meta->new({name => 'User'});
  # bless({name => 'User'}, 'Venus::Meta')

role

  role(string $name) (boolean)

The role method returns true or false if the package referenced has consumed the role named.

Since 1.00

role example 1

  # given: synopsis
  package main;
  my $role = $meta->role('Identity');
  # 1

role example 2

  # given: synopsis
  package main;
  my $role = $meta->role('Builder');
  # 0

roles

  roles() (arrayref)

The roles method returns all of the roles composed into the package referenced.

Since 1.00

roles example 1

  # given: synopsis
  package main;
  my $roles = $meta->roles;
  # [
  #   'Identity',
  #   'Authenticable'
  # ]

search

  search(string $from, string $type, string $name) (within[arrayref, tuple[string,tuple[number,arrayref]]])

The search method searches the source specified and returns the configurations for the property type specified. The source can be any one of "bases", "roles", "mixins", or "self" for the source package. The "property type" can be any one of "attr", "base", "mixin", or "role".

Since 1.02

search example 1

  # given: synopsis
  package main;
  my $search = $meta->search;
  # ()

search example 2

  # given: synopsis
  package main;
  my $search = $meta->search('roles', 'attr', 'id');
  # [['Identity', [ 1, ['id']]]]

search example 3

  # given: synopsis
  package main;
  my $search = $meta->search('self', 'sub', 'valid');
  # [['User', [1, [sub {...}]]]]

search example 4

  # given: synopsis
  package main;
  my $search = $meta->search('self', 'sub', 'authenticate');
  # [['User', [1, [sub {...}]]]]

sub

  sub(string $name) (boolean)

The sub method returns true or false if the package referenced has the subroutine named on the package directly, or any of its superclasses.

Since 1.00

sub example 1

  # given: synopsis
  package main;
  my $sub = $meta->sub('authenticate');
  # 1

sub example 2

  # given: synopsis
  package main;
  my $sub = $meta->sub('authorize');
  # 0

subs

  subs() (arrayref)

The subs method returns all of the subroutines composed into the package referenced.

Since 1.00

subs example 1

  # given: synopsis
  package main;
  my $subs = $meta->subs;
  # [
  #   'attr', ...,
  #   'base',
  #   'email',
  #   'false',
  #   'fname', ...,
  #   'id',
  #   'lname',
  #   'login',
  #   'new', ...,
  #   'role',
  #   'test',
  #   'true',
  #   'with', ...,
  # ]

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.