blib/lib/Venus/Role.pm

filter: Statementstmt 86.7% 144 / 166 Branchbran 100% 40 / 40 Conditioncond 77.1% 44 / 57 MC/DCmcdc 67.5% 25 / 37 Subroutinesub 72.7% 24 / 33 Podpod 100% 7 / 7 totaltotal 83.5% 284 / 340 CC 40 SCAR 31.6
CC
40
Cov
87%
import
41.5
base
2.0
from
2.0
CRAP 23.6
« blib/lib/Venus/Assert.pm ↑ Summary blib/lib/Venus/Os.pm »
1 package Venus::Role;
2  
3 119 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 119 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 119 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 2782 ▶sub import {
Subroutine import: called CC=40 SCAR=37.3
11 2782 my ($self, @args) = @_;
12  
13 2782 my $from = caller;
14  
15 2782 require Venus::Core::Role;
16  
17 119 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
18 119 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
19 119 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 2782 ▶ @args = grep defined && !ref && /^[A-Za-z]/, @args;
Condition33%2/6
defined $_ && !ref($_) && /^[A-Za-z]/u
!ll&&!rl&&r
002811
defined $_ and not ref $_
!ll&&!rl&&r
002811
MC/DC0%0/3
defined $_ && !ref($_) && /^[A-Za-z]/u
defined $_ not ref $_ /^[A-Za-z]/u
Truth table25%1/4
A and not(B) && C
A= defined $_B= not ref $_C= /^[A-Za-z]/u
ABCresult
0XX0
10X0
1100
1111
22  
23 2782 ▶ my %exports = map +($_,$_), @args ? @args : qw(
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 2680 102 2782
24 attr
25 base
26 false
27 from
28 mask
29 mixin
30 role
31 test
32 true
33 with
34 );
35  
36 2782 @{"${from}::ISA"} = 'Venus::Core::Role';
37  
38 2782 ▶ if ($exports{"after"} && !*{"${from}::after"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"after"} and not *{"${from}::after";}{"CODE"}) 1 2781 2782
Condition66%2/3
$exports{"after"} and not *{"${from}::after";}{"CODE"}
!ll&&!rl&&r
278101
MC/DC50%1/2
$exports{"after"} and not *{"${from}::after";}{"CODE"}
$exports{"after"} not *{"${from}::after";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"after"}B= not *{"${from}::after";}{"CODE"}
ABresult
0X0
100
111
39 1 ▶ *{"${from}::after"} = sub ($$) {require Venus; goto \&Venus::after};
Subroutine __ANON__: called CC=1 SCAR=0.0
40 }
41 2782 ▶ if ($exports{"around"} && !*{"${from}::around"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"around"} and not *{"${from}::around";}{"CODE"}) 1 2781 2782
Condition66%2/3
$exports{"around"} and not *{"${from}::around";}{"CODE"}
!ll&&!rl&&r
278101
MC/DC50%1/2
$exports{"around"} and not *{"${from}::around";}{"CODE"}
$exports{"around"} not *{"${from}::around";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"around"}B= not *{"${from}::around";}{"CODE"}
ABresult
0X0
100
111
42 1 ▶ *{"${from}::around"} = sub ($$) {require Venus; goto \&Venus::around};
Subroutine __ANON__: called CC=1 SCAR=0.0
43 }
44 2782 ▶ if ($exports{"attr"} && !*{"${from}::attr"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"attr"} and not *{"${from}::attr";}{"CODE"}) 144 2638 2782
Condition100%3/3
$exports{"attr"} and not *{"${from}::attr";}{"CODE"}
!ll&&!rl&&r
255583144
MC/DC100%2/2
$exports{"attr"} and not *{"${from}::attr";}{"CODE"}
$exports{"attr"} not *{"${from}::attr";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"attr"}B= not *{"${from}::attr";}{"CODE"}
ABresult
0X0
100
111
45 144 ▶ *{"${from}::attr"} = sub {@_ = ($from, @_); goto \&attr};
Subroutine __ANON__: called CC=1 SCAR=0.0
46 }
47 2782 ▶ if ($exports{"base"} && !*{"${from}::base"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"base"} and not *{"${from}::base";}{"CODE"}) 19 2763 2782
Condition100%3/3
$exports{"base"} and not *{"${from}::base";}{"CODE"}
!ll&&!rl&&r
26808319
MC/DC100%2/2
$exports{"base"} and not *{"${from}::base";}{"CODE"}
$exports{"base"} not *{"${from}::base";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"base"}B= not *{"${from}::base";}{"CODE"}
ABresult
0X0
100
111
48 0 ▶ *{"${from}::base"} = sub {@_ = ($from, @_); goto \&base};
Subroutine __ANON__: not called CC=1 SCAR=1.2
49 }
50 2782 ▶ if ($exports{"before"} && !*{"${from}::before"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"before"} and not *{"${from}::before";}{"CODE"}) 1 2781 2782
Condition66%2/3
$exports{"before"} and not *{"${from}::before";}{"CODE"}
!ll&&!rl&&r
278101
MC/DC50%1/2
$exports{"before"} and not *{"${from}::before";}{"CODE"}
$exports{"before"} not *{"${from}::before";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"before"}B= not *{"${from}::before";}{"CODE"}
ABresult
0X0
100
111
51 1 ▶ *{"${from}::before"} = sub ($$) {require Venus; goto \&Venus::before};
Subroutine __ANON__: called CC=1 SCAR=0.0
52 }
53 2782 ▶ if ($exports{"catch"} && !*{"${from}::catch"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"catch"} and not *{"${from}::catch";}{"CODE"}) 5 2777 2782
Condition66%2/3
$exports{"catch"} and not *{"${from}::catch";}{"CODE"}
!ll&&!rl&&r
277705
MC/DC50%1/2
$exports{"catch"} and not *{"${from}::catch";}{"CODE"}
$exports{"catch"} not *{"${from}::catch";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"catch"}B= not *{"${from}::catch";}{"CODE"}
ABresult
0X0
100
111
54 5 ▶ *{"${from}::catch"} = sub (&) {require Venus; goto \&Venus::catch};
Subroutine __ANON__: called CC=1 SCAR=0.0
55 }
56 2782 ▶ if ($exports{"error"} && !*{"${from}::error"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"error"} and not *{"${from}::error";}{"CODE"}) 5 2777 2782
Condition66%2/3
$exports{"error"} and not *{"${from}::error";}{"CODE"}
!ll&&!rl&&r
277705
MC/DC50%1/2
$exports{"error"} and not *{"${from}::error";}{"CODE"}
$exports{"error"} not *{"${from}::error";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"error"}B= not *{"${from}::error";}{"CODE"}
ABresult
0X0
100
111
57 5 ▶ *{"${from}::error"} = sub (;$) {require Venus; goto \&Venus::error};
Subroutine __ANON__: called CC=1 SCAR=0.0
58 }
59 2782 ▶ if (!*{"${from}::false"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (*{"${from}::false";}{"CODE"}) 2695 87 2782
60 2695 ▶ *{"${from}::false"} = sub {require Venus; Venus::false()};
Subroutine __ANON__: called CC=1 SCAR=0.0
61 }
62 2782 ▶ if ($exports{"fault"} && !*{"${from}::fault"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"fault"} and not *{"${from}::fault";}{"CODE"}) 926 1856 2782
Condition66%2/3
$exports{"fault"} and not *{"${from}::fault";}{"CODE"}
!ll&&!rl&&r
18560926
MC/DC50%1/2
$exports{"fault"} and not *{"${from}::fault";}{"CODE"}
$exports{"fault"} not *{"${from}::fault";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"fault"}B= not *{"${from}::fault";}{"CODE"}
ABresult
0X0
100
111
63 926 ▶ *{"${from}::fault"} = sub (;$) {require Venus; goto \&Venus::fault};
Subroutine __ANON__: called CC=1 SCAR=0.0
64 }
65 2782 ▶ if ($exports{"from"} && !*{"${from}::from"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"from"} and not *{"${from}::from";}{"CODE"}) 19 2763 2782
Condition100%3/3
$exports{"from"} and not *{"${from}::from";}{"CODE"}
!ll&&!rl&&r
26808319
MC/DC100%2/2
$exports{"from"} and not *{"${from}::from";}{"CODE"}
$exports{"from"} not *{"${from}::from";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"from"}B= not *{"${from}::from";}{"CODE"}
ABresult
0X0
100
111
66 0 ▶ *{"${from}::from"} = sub {@_ = ($from, @_); goto \&from};
Subroutine __ANON__: not called CC=1 SCAR=1.2
67 }
68 2782 ▶ if ($exports{"handle"} && !*{"${from}::handle"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"handle"} and not *{"${from}::handle";}{"CODE"}) 1 2781 2782
Condition66%2/3
$exports{"handle"} and not *{"${from}::handle";}{"CODE"}
!ll&&!rl&&r
278101
MC/DC50%1/2
$exports{"handle"} and not *{"${from}::handle";}{"CODE"}
$exports{"handle"} not *{"${from}::handle";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"handle"}B= not *{"${from}::handle";}{"CODE"}
ABresult
0X0
100
111
69 1 ▶ *{"${from}::handle"} = sub ($$) {require Venus; goto \&Venus::handle};
Subroutine __ANON__: called CC=1 SCAR=0.0
70 }
71 2782 ▶ if ($exports{"hook"} && !*{"${from}::hook"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"hook"} and not *{"${from}::hook";}{"CODE"}) 1 2781 2782
Condition66%2/3
$exports{"hook"} and not *{"${from}::hook";}{"CODE"}
!ll&&!rl&&r
278101
MC/DC50%1/2
$exports{"hook"} and not *{"${from}::hook";}{"CODE"}
$exports{"hook"} not *{"${from}::hook";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"hook"}B= not *{"${from}::hook";}{"CODE"}
ABresult
0X0
100
111
72 1 ▶ *{"${from}::hook"} = sub ($$$) {require Venus; goto \&Venus::hook};
Subroutine __ANON__: called CC=1 SCAR=0.0
73 }
74 2782 ▶ if ($exports{"raise"} && !*{"${from}::raise"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"raise"} and not *{"${from}::raise";}{"CODE"}) 2 2780 2782
Condition66%2/3
$exports{"raise"} and not *{"${from}::raise";}{"CODE"}
!ll&&!rl&&r
278002
MC/DC50%1/2
$exports{"raise"} and not *{"${from}::raise";}{"CODE"}
$exports{"raise"} not *{"${from}::raise";}{"CODE"}
Truth table66%2/3
A and not(B)
A= $exports{"raise"}B= not *{"${from}::raise";}{"CODE"}
ABresult
0X0
100
111
75 2 ▶ *{"${from}::raise"} = sub ($;$) {require Venus; goto \&Venus::raise};
Subroutine __ANON__: called CC=1 SCAR=0.0
76 }
77 2782 ▶ if ($exports{"mask"} && !*{"${from}::mask"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"mask"} and not *{"${from}::mask";}{"CODE"}) 139 2643 2782
Condition100%3/3
$exports{"mask"} and not *{"${from}::mask";}{"CODE"}
!ll&&!rl&&r
256083139
MC/DC100%2/2
$exports{"mask"} and not *{"${from}::mask";}{"CODE"}
$exports{"mask"} not *{"${from}::mask";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"mask"}B= not *{"${from}::mask";}{"CODE"}
ABresult
0X0
100
111
78 139 ▶ *{"${from}::mask"} = sub {@_ = ($from, @_); goto \&mask};
Subroutine __ANON__: called CC=1 SCAR=0.0
79 }
80 2782 ▶ if ($exports{"mixin"} && !*{"${from}::mixin"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"mixin"} and not *{"${from}::mixin";}{"CODE"}) 19 2763 2782
Condition100%3/3
$exports{"mixin"} and not *{"${from}::mixin";}{"CODE"}
!ll&&!rl&&r
26808319
MC/DC100%2/2
$exports{"mixin"} and not *{"${from}::mixin";}{"CODE"}
$exports{"mixin"} not *{"${from}::mixin";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"mixin"}B= not *{"${from}::mixin";}{"CODE"}
ABresult
0X0
100
111
81 19 ▶ *{"${from}::mixin"} = sub {@_ = ($from, @_); goto \&mixin};
Subroutine __ANON__: called CC=1 SCAR=0.0
82 }
83 2782 ▶ if ($exports{"role"} && !*{"${from}::role"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"role"} and not *{"${from}::role";}{"CODE"}) 19 2763 2782
Condition100%3/3
$exports{"role"} and not *{"${from}::role";}{"CODE"}
!ll&&!rl&&r
26808319
MC/DC100%2/2
$exports{"role"} and not *{"${from}::role";}{"CODE"}
$exports{"role"} not *{"${from}::role";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"role"}B= not *{"${from}::role";}{"CODE"}
ABresult
0X0
100
111
84 0 ▶ *{"${from}::role"} = sub {@_ = ($from, @_); goto \&role};
Subroutine __ANON__: not called CC=1 SCAR=1.2
85 }
86 2782 ▶ if ($exports{"test"} && !*{"${from}::test"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"test"} and not *{"${from}::test";}{"CODE"}) 19 2763 2782
Condition100%3/3
$exports{"test"} and not *{"${from}::test";}{"CODE"}
!ll&&!rl&&r
26808319
MC/DC100%2/2
$exports{"test"} and not *{"${from}::test";}{"CODE"}
$exports{"test"} not *{"${from}::test";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"test"}B= not *{"${from}::test";}{"CODE"}
ABresult
0X0
100
111
87 0 ▶ *{"${from}::test"} = sub {@_ = ($from, @_); goto \&test};
Subroutine __ANON__: not called CC=1 SCAR=1.2
88 }
89 2782 ▶ if (!*{"${from}::true"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (*{"${from}::true";}{"CODE"}) 2695 87 2782
90 2695 ▶ *{"${from}::true"} = sub {require Venus; Venus::true()};
Subroutine __ANON__: called CC=1 SCAR=0.0
91 }
92 2782 ▶ if ($exports{"with"} && !*{"${from}::with"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"with"} and not *{"${from}::with";}{"CODE"}) 1642 1140 2782
Condition100%3/3
$exports{"with"} and not *{"${from}::with";}{"CODE"}
!ll&&!rl&&r
1057831642
MC/DC100%2/2
$exports{"with"} and not *{"${from}::with";}{"CODE"}
$exports{"with"} not *{"${from}::with";}{"CODE"}
Truth table100%3/3
A and not(B)
A= $exports{"with"}B= not *{"${from}::with";}{"CODE"}
ABresult
0X0
100
111
93 0 ▶ *{"${from}::with"} = sub {@_ = ($from, @_); goto \&test};
Subroutine __ANON__: not called CC=1 SCAR=1.2
94 }
95  
96 2782 ${"${from}::META"} = {};
97  
98 2782 ${"${from}::@{[$from->METACACHE]}"} = undef;
99  
100 2782 return $self;
101 }
102  
103 # ROUTINES
104  
105 233 ▶sub attr {
Subroutine attr: called CC=1 SCAR=0.0
Pod documented
106 233 my ($from, @args) = @_;
107  
108 233 $from->ATTR(@args);
109  
110 233 return $from;
111 }
112  
113 0 ▶sub base {
Subroutine base: not called CC=1 SCAR=6.9
Pod documented
114 0 my ($from, @args) = @_;
115  
116 0 $from->BASE(@args);
117  
118 0 return $from;
119 }
120  
121 0 ▶sub from {
Subroutine from: not called CC=1 SCAR=6.9
Pod documented
122 0 my ($from, @args) = @_;
123  
124 0 $from->FROM(@args);
125  
126 0 return $from;
127 }
128  
129 155 ▶sub mask {
Subroutine mask: called CC=1 SCAR=0.0
Pod documented
130 155 my ($from, @args) = @_;
131  
132 155 $from->MASK(@args);
133  
134 155 return $from;
135 }
136  
137 2 ▶sub mixin {
Subroutine mixin: called CC=1 SCAR=0.0
Pod documented
138 2 my ($from, @args) = @_;
139  
140 2 $from->MIXIN(@args);
141  
142 2 return $from;
143 }
144  
145 0 ▶sub role {
Subroutine role: not called CC=1 SCAR=6.9
Pod documented
146 0 my ($from, @args) = @_;
147  
148 0 $from->ROLE(@args);
149  
150 0 return $from;
151 }
152  
153 0 ▶sub test {
Subroutine test: not called CC=1 SCAR=6.9
Pod documented
154 0 my ($from, @args) = @_;
155  
156 0 $from->TEST(@args);
157  
158 0 return $from;
159 }
160  
161 119 1;
162  
163  
164  
165 =head1 NAME
166  
167 Venus::Role - Role Builder
168  
169 =cut
170  
171 =head1 ABSTRACT
172  
173 Role Builder for Perl 5
174  
175 =cut
176  
177 =head1 SYNOPSIS
178  
179 package Person;
180  
181 use Venus::Class 'attr';
182  
183 attr 'fname';
184 attr 'lname';
185  
186 package Identity;
187  
188 use Venus::Role 'attr';
189  
190 attr 'id';
191 attr 'login';
192 attr 'password';
193  
194 sub EXPORT {
195 # explicitly declare routines to be consumed
196 ['id', 'login', 'password']
197 }
198  
199 package Authenticable;
200  
201 use Venus::Role;
202  
203 sub authenticate {
204 return true;
205 }
206  
207 sub AUDIT {
208 my ($self, $from) = @_;
209 # ensure the caller has a login and password when consumed
210 die "${from} missing the login attribute" if !$from->can('login');
211 die "${from} missing the password attribute" if !$from->can('password');
212 }
213  
214 sub BUILD {
215 my ($self, $data) = @_;
216 $self->{auth} = undef;
217 return $self;
218 }
219  
220 sub EXPORT {
221 # explicitly declare routines to be consumed
222 ['authenticate']
223 }
224  
225 package User;
226  
227 use Venus::Class;
228  
229 base 'Person';
230  
231 with 'Identity';
232  
233 attr 'email';
234  
235 test 'Authenticable';
236  
237 sub valid {
238 my ($self) = @_;
239 return $self->login && $self->password ? true : false;
240 }
241  
242 package main;
243  
244 my $user = User->new(
245 fname => 'Elliot',
246 lname => 'Alderson',
247 );
248  
249 # bless({fname => 'Elliot', lname => 'Alderson'}, 'User')
250  
251 =cut
252  
253 =head1 DESCRIPTION
254  
255 This package provides a role builder which when used causes the consumer to
256 inherit from L<Venus::Core::Role> which provides role construction and
257 lifecycle L<hooks|Venus::Core>. A role differs from a L<"class"|Venus::Class>
258 in that it can't be instantiated using the C<new> method. A role can act as an
259 interface by defining an L<"audit"|Venus::Core/AUDIT> hook which is invoked
260 automatically by the L<"test"|Venus::Class/test> function.
261  
262 =cut
263  
264 =head1 FUNCTIONS
265  
266 This package provides the following functions:
267  
268 =cut
269  
270 =head2 after
271  
272 after(string $name, coderef $code) (coderef)
273  
274 The after function installs a method modifier that executes after the original
275 method, allowing you to perform actions after a method call. B<Note:> The
276 return value of the modifier routine is ignored; the wrapped method always
277 returns the value from the original method. Modifiers are executed in the order
278 they are stacked. This function is only exported when requested.
279  
280 I<Since C<4.15>>
281  
282 =over 4
283  
284 =item after example 1
285  
286 package Example1;
287  
288 use Venus::Role 'after', 'attr';
289  
290 attr 'calls';
291  
292 sub BUILD {
293 my ($self) = @_;
294 $self->calls([]);
295 }
296  
297 sub execute {
298 my ($self) = @_;
299 push @{$self->calls}, 'original';
300 return 'original';
301 }
302  
303 after 'execute', sub {
304 my ($self) = @_;
305 push @{$self->calls}, 'after';
306 return 'ignored';
307 };
308  
309 sub EXPORT {
310 ['execute', 'calls', 'BUILD']
311 }
312  
313 package Consumer;
314  
315 use Venus::Class;
316  
317 with 'Example1';
318  
319 package main;
320  
321 my $example = Consumer->new;
322 my $result = $example->execute;
323  
324 # "original"
325  
326 =back
327  
328 =cut
329  
330 =head2 around
331  
332 around(string $name, coderef $code) (coderef)
333  
334 The around function installs a method modifier that wraps around the original
335 method. The callback provided will recieve the original routine as its first
336 argument. This function is only exported when requested.
337  
338 I<Since C<4.15>>
339  
340 =over 4
341  
342 =item around example 1
343  
344 package Example2;
345  
346 use Venus::Role 'around', 'attr';
347  
348 sub process {
349 my ($self, $value) = @_;
350 return $value;
351 }
352  
353 around 'process', sub {
354 my ($orig, $self, $value) = @_;
355 return $self->$orig($value) * 2;
356 };
357  
358 sub EXPORT {
359 ['process']
360 }
361  
362 package Consumer2;
363  
364 use Venus::Class;
365  
366 with 'Example2';
367  
368 package main;
369  
370 my $result = Consumer2->new->process(5);
371  
372 # 10
373  
374 =back
375  
376 =cut
377  
378 =head2 attr
379  
380 attr(string $name) (string)
381  
382 The attr function creates attribute accessors for the calling package. This
383 function is always exported unless a routine of the same name already exists.
384  
385 I<Since C<1.00>>
386  
387 =over 4
388  
389 =item attr example 1
390  
391 package Example;
392  
393 use Venus::Class;
394  
395 attr 'name';
396  
397 # "Example"
398  
399 =back
400  
401 =cut
402  
403 =head2 base
404  
405 base(string $name) (string)
406  
407 The base function registers one or more base classes for the calling package.
408 This function is always exported unless a routine of the same name already
409 exists.
410  
411 I<Since C<1.00>>
412  
413 =over 4
414  
415 =item base example 1
416  
417 package Entity;
418  
419 use Venus::Class;
420  
421 sub output {
422 return;
423 }
424  
425 package Example;
426  
427 use Venus::Class;
428  
429 base 'Entity';
430  
431 # "Example"
432  
433 =back
434  
435 =cut
436  
437 =head2 before
438  
439 before(string $name, coderef $code) (coderef)
440  
441 The before function installs a method modifier that executes before the
442 original method, allowing you to perform actions before a method call. B<Note:>
443 The return value of the modifier routine is ignored; the wrapped method always
444 returns the value from the original method. Modifiers are executed in the order
445 they are stacked. This function is only exported when requested.
446  
447 I<Since C<4.15>>
448  
449 =over 4
450  
451 =item before example 1
452  
453 package Example3;
454  
455 use Venus::Role 'attr', 'before';
456  
457 attr 'calls';
458  
459 sub perform {
460 my ($self) = @_;
461 push @{$self->calls}, 'original';
462 return $self;
463 }
464  
465 before 'perform', sub {
466 my ($self) = @_;
467 push @{$self->calls}, 'before';
468 return $self;
469 };
470  
471 sub EXPORT {
472 ['perform']
473 }
474  
475 package Consumer3;
476  
477 use Venus::Class;
478  
479 attr 'calls';
480  
481 sub BUILD {
482 my ($self) = @_;
483 $self->calls([]);
484 }
485  
486 with 'Example3';
487  
488 package main;
489  
490 my $example = Consumer3->new;
491 $example->perform;
492 my $calls = $example->calls;
493  
494 # ['before', 'original']
495  
496 =back
497  
498 =cut
499  
500 =head2 catch
501  
502 catch(coderef $block) (Venus::Error, any)
503  
504 The catch function executes the code block trapping errors and returning the
505 caught exception in scalar context, and also returning the result as a second
506 argument in list context. This function isn't export unless requested.
507  
508 I<Since C<1.01>>
509  
510 =over 4
511  
512 =item catch example 1
513  
514 package Ability;
515  
516 use Venus::Role 'catch';
517  
518 sub attempt_catch {
519 catch {die};
520 }
521  
522 sub EXPORT {
523 ['attempt_catch']
524 }
525  
526 package Example;
527  
528 use Venus::Class 'with';
529  
530 with 'Ability';
531  
532 package main;
533  
534 my $example = Example->new;
535  
536 my $error = $example->attempt_catch;
537  
538 $error;
539  
540 # "Died at ..."
541  
542 =back
543  
544 =cut
545  
546 =head2 error
547  
548 error(maybe[hashref] $args) (Venus::Error)
549  
550 The error function throws a L<Venus::Error> exception object using the
551 exception object arguments provided. This function isn't export unless requested.
552  
553 I<Since C<1.01>>
554  
555 =over 4
556  
557 =item error example 1
558  
559 package Ability;
560  
561 use Venus::Role 'error';
562  
563 sub attempt_error {
564 error;
565 }
566  
567 sub EXPORT {
568 ['attempt_error']
569 }
570  
571 package Example;
572  
573 use Venus::Class 'with';
574  
575 with 'Ability';
576  
577 package main;
578  
579 my $example = Example->new;
580  
581 my $error = $example->attempt_error;
582  
583 # bless({...}, 'Venus::Error')
584  
585 =back
586  
587 =cut
588  
589 =head2 false
590  
591 false() (boolean)
592  
593 The false function returns a falsy boolean value which is designed to be
594 practically indistinguishable from the conventional numerical C<0> value. This
595 function is always exported unless a routine of the same name already exists.
596  
597 I<Since C<1.00>>
598  
599 =over 4
600  
601 =item false example 1
602  
603 package Example;
604  
605 use Venus::Class;
606  
607 my $false = false;
608  
609 # 0
610  
611 =back
612  
613 =over 4
614  
615 =item false example 2
616  
617 package Example;
618  
619 use Venus::Class;
620  
621 my $true = !false;
622  
623 # 1
624  
625 =back
626  
627 =cut
628  
629 =head2 from
630  
631 from(string $name) (string)
632  
633 The from function registers one or more base classes for the calling package
634 and performs an L<"audit"|Venus::Core/AUDIT>. This function is always exported
635 unless a routine of the same name already exists.
636  
637 I<Since C<1.00>>
638  
639 =over 4
640  
641 =item from example 1
642  
643 package Entity;
644  
645 use Venus::Role;
646  
647 attr 'startup';
648 attr 'shutdown';
649  
650 sub EXPORT {
651 ['startup', 'shutdown']
652 }
653  
654 package Record;
655  
656 use Venus::Class;
657  
658 sub AUDIT {
659 my ($self, $from) = @_;
660 die "Missing startup" if !$from->can('startup');
661 die "Missing shutdown" if !$from->can('shutdown');
662 }
663  
664 package Example;
665  
666 use Venus::Class;
667  
668 with 'Entity';
669  
670 from 'Record';
671  
672 # "Example"
673  
674 =back
675  
676 =cut
677  
678 =head2 handle
679  
680 handle(string $name, coderef $code) (coderef)
681  
682 The handle function installs a method modifier that wraps a method, providing
683 low-level control. The callback provided will recieve the original routine as
684 its first argument (or C<undef> if the source routine doesn't exist). This
685 function is only exported when requested.
686  
687 I<Since C<4.15>>
688  
689 =over 4
690  
691 =item handle example 1
692  
693 package Example4;
694  
695 use Venus::Role 'handle';
696  
697 sub compute {
698 my ($self, $value) = @_;
699 return $value;
700 }
701  
702 handle 'compute', sub {
703 my ($orig, $self, $value) = @_;
704 return $orig ? $self->$orig($value * 2) : 0;
705 };
706  
707 sub EXPORT {
708 ['compute']
709 }
710  
711 package Consumer4;
712  
713 use Venus::Class;
714  
715 with 'Example4';
716  
717 package main;
718  
719 my $result = Consumer4->new->compute(5);
720  
721 # 10
722  
723 =back
724  
725 =cut
726  
727 =head2 hook
728  
729 hook(string $type, string $name, coderef $code) (coderef)
730  
731 The hook function installs a method modifier on a lifecycle hook method. The
732 first argument is the type of modifier desired, e.g., L</before>, L</after>,
733 L</around>, and the callback provided will recieve the original routine as its
734 first argument. This function is only exported when requested.
735  
736 I<Since C<4.15>>
737  
738 =over 4
739  
740 =item hook example 1
741  
742 package Example5;
743  
744 use Venus::Role 'attr', 'hook';
745  
746 attr 'startup';
747  
748 sub BUILD {
749 my ($self, $args) = @_;
750 $self->startup('original');
751 }
752  
753 hook 'after', 'build', sub {
754 my ($self) = @_;
755 $self->startup('modified');
756 };
757  
758 sub EXPORT {
759 ['startup', 'BUILD']
760 }
761  
762 package Consumer5;
763  
764 use Venus::Class;
765  
766 with 'Example5';
767  
768 package main;
769  
770 my $result = Consumer5->new->startup;
771  
772 # "modified"
773  
774 =back
775  
776 =cut
777  
778 =head2 mask
779  
780 mask(string $name) (string)
781  
782 The mask function creates private attribute accessors that can only be accessed
783 from within the class or its subclasses. This function is exported on-demand
784 unless a routine of the same name already exists.
785  
786 I<Since C<4.15>>
787  
788 =over 4
789  
790 =item mask example 1
791  
792 package Example;
793  
794 use Venus::Class;
795  
796 mask 'secret';
797  
798 # "Example"
799  
800 =back
801  
802 =cut
803  
804 =head2 mixin
805  
806 mixin(string $name) (string)
807  
808 The mixin function registers and consumes mixins for the calling package. This
809 function is always exported unless a routine of the same name already exists.
810  
811 I<Since C<1.02>>
812  
813 =over 4
814  
815 =item mixin example 1
816  
817 package YesNo;
818  
819 use Venus::Mixin;
820  
821 sub no {
822 return 0;
823 }
824  
825 sub yes {
826 return 1;
827 }
828  
829 sub EXPORT {
830 ['no', 'yes']
831 }
832  
833 package Answer;
834  
835 use Venus::Role;
836  
837 mixin 'YesNo';
838  
839 # "Answer"
840  
841 =back
842  
843 =over 4
844  
845 =item mixin example 2
846  
847 package YesNo;
848  
849 use Venus::Mixin;
850  
851 sub no {
852 return 0;
853 }
854  
855 sub yes {
856 return 1;
857 }
858  
859 sub EXPORT {
860 ['no', 'yes']
861 }
862  
863 package Answer;
864  
865 use Venus::Role;
866  
867 mixin 'YesNo';
868  
869 sub no {
870 return [0];
871 }
872  
873 sub yes {
874 return [1];
875 }
876  
877 my $package = "Answer";
878  
879 # "Answer"
880  
881 =back
882  
883 =cut
884  
885 =head2 raise
886  
887 raise(string $class | tuple[string, string] $class, maybe[hashref] $args) (Venus::Error)
888  
889 The raise function generates and throws a named exception object derived from
890 L<Venus::Error>, or provided base class, using the exception object arguments
891 provided. This function isn't export unless requested.
892  
893 I<Since C<1.01>>
894  
895 =over 4
896  
897 =item raise example 1
898  
899 package Ability;
900  
901 use Venus::Role 'raise';
902  
903 sub attempt_raise {
904 raise 'Example::Error';
905 }
906  
907 sub EXPORT {
908 ['attempt_raise']
909 }
910  
911 package Example;
912  
913 use Venus::Class 'with';
914  
915 with 'Ability';
916  
917 package main;
918  
919 my $example = Example->new;
920  
921 my $error = $example->attempt_raise;
922  
923 # bless({...}, 'Example::Error')
924  
925 =back
926  
927 =cut
928  
929 =head2 role
930  
931 role(string $name) (string)
932  
933 The role function registers and consumes roles for the calling package. This
934 function is always exported unless a routine of the same name already exists.
935  
936 I<Since C<1.00>>
937  
938 =over 4
939  
940 =item role example 1
941  
942 package Ability;
943  
944 use Venus::Role;
945  
946 sub action {
947 return;
948 }
949  
950 package Example;
951  
952 use Venus::Class;
953  
954 role 'Ability';
955  
956 # "Example"
957  
958 =back
959  
960 =over 4
961  
962 =item role example 2
963  
964 package Ability;
965  
966 use Venus::Role;
967  
968 sub action {
969 return;
970 }
971  
972 sub EXPORT {
973 return ['action'];
974 }
975  
976 package Example;
977  
978 use Venus::Class;
979  
980 role 'Ability';
981  
982 # "Example"
983  
984 =back
985  
986 =cut
987  
988 =head2 test
989  
990 test(string $name) (string)
991  
992 The test function registers and consumes roles for the calling package and
993 performs an L<"audit"|Venus::Core/AUDIT>, effectively allowing a role to act as
994 an interface. This function is always exported unless a routine of the same
995 name already exists.
996  
997 I<Since C<1.00>>
998  
999 =over 4
1000  
1001 =item test example 1
1002  
1003 package Actual;
1004  
1005 use Venus::Role;
1006  
1007 package Example;
1008  
1009 use Venus::Class;
1010  
1011 test 'Actual';
1012  
1013 # "Example"
1014  
1015 =back
1016  
1017 =over 4
1018  
1019 =item test example 2
1020  
1021 package Actual;
1022  
1023 use Venus::Role;
1024  
1025 sub AUDIT {
1026 die "Example is not an 'actual' thing" if $_[1]->isa('Example');
1027 }
1028  
1029 package Example;
1030  
1031 use Venus::Class;
1032  
1033 test 'Actual';
1034  
1035 # "Example"
1036  
1037 =back
1038  
1039 =cut
1040  
1041 =head2 true
1042  
1043 true() (boolean)
1044  
1045 The true function returns a truthy boolean value which is designed to be
1046 practically indistinguishable from the conventional numerical C<1> value. This
1047 function is always exported unless a routine of the same name already exists.
1048  
1049 I<Since C<1.00>>
1050  
1051 =over 4
1052  
1053 =item true example 1
1054  
1055 package Example;
1056  
1057 use Venus::Class;
1058  
1059 my $true = true;
1060  
1061 # 1
1062  
1063 =back
1064  
1065 =over 4
1066  
1067 =item true example 2
1068  
1069 package Example;
1070  
1071 use Venus::Class;
1072  
1073 my $false = !true;
1074  
1075 # 0
1076  
1077 =back
1078  
1079 =cut
1080  
1081 =head2 with
1082  
1083 with(string $name) (string)
1084  
1085 The with function registers and consumes roles for the calling package. This
1086 function is an alias of the L</test> function and will perform an
1087 L<"audit"|Venus::Core/AUDIT> if present. This function is always exported
1088 unless a routine of the same name already exists.
1089  
1090 I<Since C<1.00>>
1091  
1092 =over 4
1093  
1094 =item with example 1
1095  
1096 package Understanding;
1097  
1098 use Venus::Role;
1099  
1100 sub knowledge {
1101 return;
1102 }
1103  
1104 package Example;
1105  
1106 use Venus::Class;
1107  
1108 with 'Understanding';
1109  
1110 # "Example"
1111  
1112 =back
1113  
1114 =over 4
1115  
1116 =item with example 2
1117  
1118 package Understanding;
1119  
1120 use Venus::Role;
1121  
1122 sub knowledge {
1123 return;
1124 }
1125  
1126 sub EXPORT {
1127 return ['knowledge'];
1128 }
1129  
1130 package Example;
1131  
1132 use Venus::Class;
1133  
1134 with 'Understanding';
1135  
1136 # "Example"
1137  
1138 =back
1139  
1140 =cut
1141  
1142 =head1 AUTHORS
1143  
1144 Awncorp, C<awncorp@cpan.org>
1145  
1146 =cut
1147  
1148 =head1 LICENSE
1149  
1150 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
1151  
1152 This program is free software, you can redistribute it and/or modify it under
1153 the terms of the Apache license version 2.0.
1154  
1155 =cut
« blib/lib/Venus/Assert.pm ↑ Summary blib/lib/Venus/Os.pm »