blib/lib/Venus/Mixin.pm

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