 |
|
| |
Venus::Core(3) |
User Contributed Perl Documentation |
Venus::Core(3) |
Venus::Core - Core Base Class
Core Base Class for Perl 5
package User;
use base 'Venus::Core';
package main;
my $user = User->BLESS(
fname => 'Elliot',
lname => 'Alderson',
);
# bless({fname => 'Elliot', lname => 'Alderson'}, 'User')
# i.e. BLESS is somewhat equivalent to writing
# User->BUILD(bless(User->ARGS(User->BUILDARGS(@args) || User->DATA), 'User'))
This package provides a base class for "class" and
"role" (kind) derived packages and provides class building, object
construction, and object deconstruction lifecycle hooks. The Venus::Class
and Venus::Role packages provide a simple DSL for automating Venus::Core
derived base classes.
This package provides the following methods:
ARGS(any @args) (hashref)
The ARGS method is a object construction lifecycle hook which
accepts a list of arguments and returns a blessable data structure.
Since 1.00
- args example 1
-
# given: synopsis
package main;
my $args = User->ARGS;
# {}
- args example 2
-
# given: synopsis
package main;
my $args = User->ARGS(name => 'Elliot');
# {name => 'Elliot'}
- args example 3
-
# given: synopsis
package main;
my $args = User->ARGS({name => 'Elliot'});
# {name => 'Elliot'}
ATTR(string $name, any @args) (string | object)
The ATTR method is a class building lifecycle hook which installs
an attribute accessors in the calling package.
Since 1.00
- attr example 1
-
package User;
use base 'Venus::Core';
User->ATTR('name');
package main;
my $user = User->BLESS;
# bless({}, 'User')
# $user->name;
# ""
# $user->name('Elliot');
# "Elliot"
- attr example 2
-
package User;
use base 'Venus::Core';
User->ATTR('role');
package main;
my $user = User->BLESS(role => 'Engineer');
# bless({role => 'Engineer'}, 'User')
# $user->role;
# "Engineer"
# $user->role('Hacker');
# "Hacker"
AUDIT(string $role) (string | object)
The AUDIT method is a class building lifecycle hook which exist in
roles and is executed as a callback when the consuming class invokes the
"TEST" hook.
Since 1.00
- audit example 1
-
package HasType;
use base 'Venus::Core';
sub AUDIT {
die 'Consumer missing "type" attribute' if !$_[1]->can('type');
}
package User;
use base 'Venus::Core';
User->TEST('HasType');
package main;
my $user = User->BLESS;
# Exception! Consumer missing "type" attribute
- audit example 2
-
package HasType;
sub AUDIT {
die 'Consumer missing "type" attribute' if !$_[1]->can('type');
}
package User;
use base 'Venus::Core';
User->ATTR('type');
User->TEST('HasType');
package main;
my $user = User->BLESS;
# bless({}, 'User')
BASE(string $name) (string | object)
The BASE method is a class building lifecycle hook which registers
a base class for the calling package. Note: Unlike the
"FROM" hook, this hook doesn't invoke the "AUDIT"
hook.
Since 1.00
- base example 1
-
package Entity;
sub work {
return;
}
package User;
use base 'Venus::Core';
User->BASE('Entity');
package main;
my $user = User->BLESS;
# bless({}, 'User')
- base example 2
-
package Engineer;
sub debug {
return;
}
package Entity;
sub work {
return;
}
package User;
use base 'Venus::Core';
User->BASE('Entity');
User->BASE('Engineer');
package main;
my $user = User->BLESS;
# bless({}, 'User')
- base example 3
-
package User;
use base 'Venus::Core';
User->BASE('Manager');
# Exception! "Can't locate Manager.pm in @INC"
BLESS(any @args) (object)
The BLESS method is an object construction lifecycle hook which
returns an instance of the calling package.
Since 1.00
- bless example 1
-
package User;
use base 'Venus::Core';
package main;
my $example = User->BLESS;
# bless({}, 'User')
- bless example 2
-
package User;
use base 'Venus::Core';
package main;
my $example = User->BLESS(name => 'Elliot');
# bless({name => 'Elliot'}, 'User')
- bless example 3
-
package User;
use base 'Venus::Core';
package main;
my $example = User->BLESS({name => 'Elliot'});
# bless({name => 'Elliot'}, 'User')
- bless example 4
-
package List;
use base 'Venus::Core';
sub ARGS {
my ($self, @args) = @_;
return @args
? ((@args == 1 && ref $args[0] eq 'ARRAY') ? @args : [@args])
: $self->DATA;
}
sub DATA {
my ($self, $data) = @_;
return $data ? [@$data] : [];
}
package main;
my $list = List->BLESS(1..4);
# bless([1..4], 'List')
- bless example 5
-
package List;
use base 'Venus::Core';
sub ARGS {
my ($self, @args) = @_;
return @args
? ((@args == 1 && ref $args[0] eq 'ARRAY') ? @args : [@args])
: $self->DATA;
}
sub DATA {
my ($self, $data) = @_;
return $data ? [@$data] : [];
}
package main;
my $list = List->BLESS([1..4]);
# bless([1..4], 'List')
BUILD(hashref $data) (object)
The BUILD method is an object construction lifecycle hook which
receives an object and the data structure that was blessed, and should
return an object although its return value is ignored by the
"BLESS" hook.
Since 1.00
- build example 1
-
package User;
use base 'Venus::Core';
sub BUILD {
my ($self) = @_;
$self->{name} = 'Mr. Robot';
return $self;
}
package main;
my $example = User->BLESS(name => 'Elliot');
# bless({name => 'Mr. Robot'}, 'User')
- build example 2
-
package User;
use base 'Venus::Core';
sub BUILD {
my ($self) = @_;
$self->{name} = 'Mr. Robot';
return $self;
}
package Elliot;
use base 'User';
sub BUILD {
my ($self, $data) = @_;
$self->SUPER::BUILD($data);
$self->{name} = 'Elliot';
return $self;
}
package main;
my $elliot = Elliot->BLESS;
# bless({name => 'Elliot'}, 'Elliot')
BUILDARGS(any @args) (any @args | hashref $data)
The BUILDARGS method is an object construction lifecycle hook
which receives the arguments provided to the constructor (unaltered) and
should return a list of arguments, a hashref, or key/value pairs.
Since 1.00
- buildargs example 1
-
package User;
use base 'Venus::Core';
sub BUILD {
my ($self) = @_;
return $self;
}
sub BUILDARGS {
my ($self, @args) = @_;
my $data = @args == 1 && !ref $args[0] ? {name => $args[0]} : {};
return $data;
}
package main;
my $user = User->BLESS('Elliot');
# bless({name => 'Elliot'}, 'User')
DATA() (Ref)
The DATA method is an object construction lifecycle hook which
returns the default data structure reference to be blessed when no arguments
are provided to the constructor. The default data structure is an empty
hashref.
Since 1.00
- data example 1
-
package Example;
use base 'Venus::Core';
sub DATA {
return [];
}
package main;
my $example = Example->BLESS;
# bless([], 'Example')
- data example 2
-
package Example;
use base 'Venus::Core';
sub DATA {
return {};
}
package main;
my $example = Example->BLESS;
# bless({}, 'Example')
DESTROY() (any)
The DESTROY method is an object destruction lifecycle hook which
is called when the last reference to the object goes away.
Since 1.00
- destroy example 1
-
package User;
use base 'Venus::Core';
our $USERS = 0;
sub BUILD {
return $USERS++;
}
sub DESTROY {
return $USERS--;
}
package main;
my $user = User->BLESS(name => 'Elliot');
undef $user;
# undef
DOES(string $name) (boolean)
The DOES method returns true or false if the invocant consumed the
role or interface provided.
Since 1.00
- does example 1
-
package Admin;
use base 'Venus::Core';
package User;
use base 'Venus::Core';
User->ROLE('Admin');
sub BUILD {
my ($self) = @_;
return $self;
}
sub BUILDARGS {
my ($self, @args) = @_;
return (@args);
}
package main;
my $admin = User->DOES('Admin');
# 1
- does example 2
-
package Admin;
use base 'Venus::Core';
package User;
use base 'Venus::Core';
User->ROLE('Admin');
sub BUILD {
my ($self) = @_;
return $self;
}
sub BUILDARGS {
my ($self, @args) = @_;
return (@args);
}
package main;
my $is_owner = User->DOES('Owner');
# 0
EXPORT(any @args) (arrayref)
The EXPORT method is a class building lifecycle hook which returns
an arrayref of routine names to be automatically imported by the calling
package whenever the "ROLE" or "TEST" hooks are
used.
Since 1.00
- export example 1
-
package Admin;
use base 'Venus::Core';
sub shutdown {
return;
}
sub EXPORT {
['shutdown']
}
package User;
use base 'Venus::Core';
User->ROLE('Admin');
package main;
my $user = User->BLESS;
# bless({}, 'User')
FROM(string $name) (string | object)
The FROM method is a class building lifecycle hook which registers
a base class for the calling package, automatically invoking the
"AUDIT" and "IMPORT" hooks on the base class.
Since 1.00
- from example 1
-
package Entity;
use base 'Venus::Core';
sub AUDIT {
my ($self, $from) = @_;
die "Missing startup" if !$from->can('startup');
die "Missing shutdown" if !$from->can('shutdown');
}
package User;
use base 'Venus::Core';
User->ATTR('startup');
User->ATTR('shutdown');
User->FROM('Entity');
package main;
my $user = User->BLESS;
# bless({}, 'User')
- from example 2
-
package Entity;
use base 'Venus::Core';
sub AUDIT {
my ($self, $from) = @_;
die "Missing startup" if !$from->can('startup');
die "Missing shutdown" if !$from->can('shutdown');
}
package User;
use base 'Venus::Core';
User->FROM('Entity');
sub startup {
return;
}
sub shutdown {
return;
}
package main;
my $user = User->BLESS;
# bless({}, 'User')
GET(string $name) (any)
The GET method is a class instance lifecycle hook which is
responsible for "getting" instance items (or attribute
values). By default, all class attributes "getters" are
dispatched to this method.
Since 2.91
- get example 1
-
package User;
use base 'Venus::Core';
User->ATTR('name');
package main;
my $user = User->BLESS(title => 'Engineer');
# bless({title => 'Engineer'}, 'User')
my $get = $user->GET('title');
# "Engineer"
IMPORT(string $into, any @args) (string | object)
The IMPORT method is a class building lifecycle hook which
dispatches the "EXPORT" lifecycle hook whenever the
"ROLE" or "TEST" hooks are used.
Since 1.00
- import example 1
-
package Admin;
use base 'Venus::Core';
our $USES = 0;
sub shutdown {
return;
}
sub EXPORT {
['shutdown']
}
sub IMPORT {
my ($self, $into) = @_;
$self->SUPER::IMPORT($into);
$USES++;
return $self;
}
package User;
use base 'Venus::Core';
User->ROLE('Admin');
package main;
my $user = User->BLESS;
# bless({}, 'User')
ITEM(string $name, any @args) (string | object)
The ITEM method is a class instance lifecycle hook which is
responsible for "getting" and "setting"
instance items (or attributes). By default, all class attributes are
dispatched to this method.
Since 1.11
- item example 1
-
package User;
use base 'Venus::Core';
User->ATTR('name');
package main;
my $user = User->BLESS;
# bless({}, 'User')
my $item = $user->ITEM('name', 'unknown');
# "unknown"
- item example 2
-
package User;
use base 'Venus::Core';
User->ATTR('name');
package main;
my $user = User->BLESS;
# bless({}, 'User')
$user->ITEM('name', 'known');
my $item = $user->ITEM('name');
# "known"
META() (Venus::Meta)
The META method return a Venus::Meta object which describes the
invocant's configuration.
Since 1.00
- meta example 1
-
package User;
use base 'Venus::Core';
package main;
my $meta = User->META;
# bless({name => 'User'}, 'Venus::Meta')
MIXIN(string $name) (string | object)
The MIXIN method is a class building lifecycle hook which consumes
the mixin provided, automatically invoking the mixin's "IMPORT"
hook. The role composition semantics are as follows: Routines to be consumed
must be explicitly declared via the "EXPORT" hook. Routines will
be copied to the consumer even if they already exist. If multiple roles are
consumed having routines with the same name (i.e. naming collisions) the
last routine copied wins.
Since 1.02
- mixin example 1
-
package Action;
use base 'Venus::Core';
package User;
use base 'Venus::Core';
User->MIXIN('Action');
package main;
my $admin = User->DOES('Action');
# 0
NAME() (string)
The NAME method is a class building lifecycle hook which returns
the name of the package.
Since 1.00
- name example 1
-
package User;
use base 'Venus::Core';
package main;
my $name = User->NAME;
# "User"
- name example 2
-
package User;
use base 'Venus::Core';
package main;
my $name = User->BLESS->NAME;
# "User"
ROLE(string $name) (string | object)
The ROLE method is a class building lifecycle hook which consumes
the role provided, automatically invoking the role's "IMPORT"
hook. Note: Unlike the "TEST" and "WITH" hooks,
this hook doesn't invoke the "AUDIT" hook. The role composition
semantics are as follows: Routines to be consumed must be explicitly
declared via the "EXPORT" hook. Routines will be copied to the
consumer unless they already exist (excluding routines from base classes,
which will be overridden). If multiple roles are consumed having routines
with the same name (i.e. naming collisions) the first routine copied
wins.
Since 1.00
- role example 1
-
package Admin;
use base 'Venus::Core';
package User;
use base 'Venus::Core';
User->ROLE('Admin');
package main;
my $admin = User->DOES('Admin');
# 1
- role example 2
-
package Create;
use base 'Venus::Core';
package Delete;
use base 'Venus::Core';
package Manage;
use base 'Venus::Core';
Manage->ROLE('Create');
Manage->ROLE('Delete');
package User;
use base 'Venus::Core';
User->ROLE('Manage');
package main;
my $create = User->DOES('Create');
# 1
SET(string $name, any @args) (any)
The SET method is a class instance lifecycle hook which is
responsible for "setting" instance items (or attribute
values). By default, all class attributes "setters" are
dispatched to this method.
- set example 1
-
package User;
use base 'Venus::Core';
User->ATTR('name');
package main;
my $user = User->BLESS(title => 'Engineer');
# bless({title => 'Engineer'}, 'User')
my $set = $user->SET('title', 'Manager');
# "Manager"
SUBS() (arrayref)
The SUBS method returns the routines defined on the package and
consumed from roles, but not inherited by superclasses.
Since 1.00
- subs example 1
-
package Example;
use base 'Venus::Core';
package main;
my $subs = Example->SUBS;
# [...]
TEST(string $name) (string | object)
The TEST method is a class building lifecycle hook which consumes
the role provided, automatically invoking the role's "IMPORT" hook
as well as the "AUDIT" hook if defined.
Since 1.00
- test example 1
-
package Admin;
use base 'Venus::Core';
package IsAdmin;
use base 'Venus::Core';
sub shutdown {
return;
}
sub AUDIT {
my ($self, $from) = @_;
die "${from} is not a super-user" if !$from->DOES('Admin');
}
sub EXPORT {
['shutdown']
}
package User;
use base 'Venus::Core';
User->ROLE('Admin');
User->TEST('IsAdmin');
package main;
my $user = User->BLESS;
# bless({}, 'User')
UNIMPORT(string $into, any @args) (any)
The UNIMPORT method is a class building lifecycle hook which is
invoked whenever the "no" in perlfunc declaration is used.
Since 2.91
- unimport example 1
-
package User;
use base 'Venus::Core';
package main;
User->UNIMPORT;
# 'User'
Awncorp, "awncorp@cpan.org"
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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|