blib/lib/Venus/Class.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/Os.pm ↑ Summary blib/lib/Venus/Mixin.pm »
1 package Venus::Class;
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 2144 ▶sub import {
Subroutine import: called CC=40 SCAR=37.1
11 2144 my ($self, @args) = @_;
12  
13 2144 my $from = caller;
14  
15 2144 require Venus::Core::Class;
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 2144 ▶ @args = grep defined && !ref && /^[A-Za-z]/, @args;
Condition33%2/6
defined $_ && !ref($_) && /^[A-Za-z]/u
!ll&&!rl&&r
003620
defined $_ and not ref $_
!ll&&!rl&&r
003620
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 2144 ▶ my %exports = map +($_,$_), @args ? @args : qw(
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 1872 272 2144
24 attr
25 base
26 false
27 from
28 mask
29 mixin
30 role
31 test
32 true
33 with
34 );
35  
36 2144 @{"${from}::ISA"} = 'Venus::Core::Class';
37  
38 2144 ▶ if ($exports{"attr"} && !*{"${from}::attr"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"attr"} and not *{"${from}::attr";}{"CODE"}) 744 1400 2144
Condition100%3/3
$exports{"attr"} and not *{"${from}::attr";}{"CODE"}
!ll&&!rl&&r
1202198744
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
39 744 ▶ *{"${from}::attr"} = sub {@_ = ($from, @_); goto \&attr};
Subroutine __ANON__: called CC=1 SCAR=0.0
40 }
41 2144 ▶ if ($exports{"after"} && !*{"${from}::after"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"after"} and not *{"${from}::after";}{"CODE"}) 3 2141 2144
Condition66%2/3
$exports{"after"} and not *{"${from}::after";}{"CODE"}
!ll&&!rl&&r
214103
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
42 3 ▶ *{"${from}::after"} = sub ($$) {require Venus; goto \&Venus::after};
Subroutine __ANON__: called CC=1 SCAR=0.0
43 }
44 2144 ▶ if ($exports{"around"} && !*{"${from}::around"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"around"} and not *{"${from}::around";}{"CODE"}) 3 2141 2144
Condition66%2/3
$exports{"around"} and not *{"${from}::around";}{"CODE"}
!ll&&!rl&&r
214103
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
45 3 ▶ *{"${from}::around"} = sub ($$) {require Venus; goto \&Venus::around};
Subroutine __ANON__: called CC=1 SCAR=0.0
46 }
47 2144 ▶ if ($exports{"base"} && !*{"${from}::base"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"base"} and not *{"${from}::base";}{"CODE"}) 1742 402 2144
Condition100%3/3
$exports{"base"} and not *{"${from}::base";}{"CODE"}
!ll&&!rl&&r
2071951742
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 1742 ▶ *{"${from}::base"} = sub {@_ = ($from, @_); goto \&base};
Subroutine __ANON__: called CC=1 SCAR=0.0
49 }
50 2144 ▶ if ($exports{"before"} && !*{"${from}::before"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"before"} and not *{"${from}::before";}{"CODE"}) 3 2141 2144
Condition66%2/3
$exports{"before"} and not *{"${from}::before";}{"CODE"}
!ll&&!rl&&r
214103
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 3 ▶ *{"${from}::before"} = sub ($$) {require Venus; goto \&Venus::before};
Subroutine __ANON__: called CC=1 SCAR=0.0
52 }
53 2144 ▶ if ($exports{"catch"} && !*{"${from}::catch"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"catch"} and not *{"${from}::catch";}{"CODE"}) 1 2143 2144
Condition66%2/3
$exports{"catch"} and not *{"${from}::catch";}{"CODE"}
!ll&&!rl&&r
214301
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 1 ▶ *{"${from}::catch"} = sub (&) {require Venus; goto \&Venus::catch};
Subroutine __ANON__: called CC=1 SCAR=0.0
55 }
56 2144 ▶ if ($exports{"error"} && !*{"${from}::error"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"error"} and not *{"${from}::error";}{"CODE"}) 1 2143 2144
Condition66%2/3
$exports{"error"} and not *{"${from}::error";}{"CODE"}
!ll&&!rl&&r
214301
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 1 ▶ *{"${from}::error"} = sub (;$) {require Venus; goto \&Venus::error};
Subroutine __ANON__: called CC=1 SCAR=0.0
58 }
59 2144 ▶ if (!*{"${from}::false"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (*{"${from}::false";}{"CODE"}) 1814 330 2144
60 1814 ▶ *{"${from}::false"} = sub {require Venus; Venus::false()};
Subroutine __ANON__: called CC=1 SCAR=0.0
61 }
62 0 ▶ if ($exports{"fault"} && !*{"${from}::fault"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"fault"} and not *{"${from}::fault";}{"CODE"}) 0 2144 2144
Condition33%1/3
$exports{"fault"} and not *{"${from}::fault";}{"CODE"}
!ll&&!rl&&r
214400
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
63 0 ▶ *{"${from}::fault"} = sub (;$) {require Venus; goto \&Venus::fault};
Subroutine __ANON__: not called CC=1 SCAR=6.9
64 }
65 2144 ▶ if ($exports{"from"} && !*{"${from}::from"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"from"} and not *{"${from}::from";}{"CODE"}) 114 2030 2144
Condition100%3/3
$exports{"from"} and not *{"${from}::from";}{"CODE"}
!ll&&!rl&&r
1872158114
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 114 ▶ *{"${from}::from"} = sub {@_ = ($from, @_); goto \&from};
Subroutine __ANON__: called CC=1 SCAR=0.0
67 }
68 2144 ▶ if ($exports{"handle"} && !*{"${from}::handle"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"handle"} and not *{"${from}::handle";}{"CODE"}) 3 2141 2144
Condition66%2/3
$exports{"handle"} and not *{"${from}::handle";}{"CODE"}
!ll&&!rl&&r
214103
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 3 ▶ *{"${from}::handle"} = sub ($$) {require Venus; goto \&Venus::handle};
Subroutine __ANON__: called CC=1 SCAR=0.0
70 }
71 2144 ▶ if ($exports{"hook"} && !*{"${from}::hook"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"hook"} and not *{"${from}::hook";}{"CODE"}) 3 2141 2144
Condition66%2/3
$exports{"hook"} and not *{"${from}::hook";}{"CODE"}
!ll&&!rl&&r
214103
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 3 ▶ *{"${from}::hook"} = sub ($$$) {require Venus; goto \&Venus::hook};
Subroutine __ANON__: called CC=1 SCAR=0.0
73 }
74 2144 ▶ if ($exports{"raise"} && !*{"${from}::raise"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"raise"} and not *{"${from}::raise";}{"CODE"}) 2 2142 2144
Condition66%2/3
$exports{"raise"} and not *{"${from}::raise";}{"CODE"}
!ll&&!rl&&r
214202
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 2144 ▶ if ($exports{"mask"} && !*{"${from}::mask"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"mask"} and not *{"${from}::mask";}{"CODE"}) 116 2028 2144
Condition100%3/3
$exports{"mask"} and not *{"${from}::mask";}{"CODE"}
!ll&&!rl&&r
1870158116
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 116 ▶ *{"${from}::mask"} = sub {@_ = ($from, @_); goto \&mask};
Subroutine __ANON__: called CC=1 SCAR=0.0
79 }
80 2144 ▶ if ($exports{"mixin"} && !*{"${from}::mixin"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"mixin"} and not *{"${from}::mixin";}{"CODE"}) 115 2029 2144
Condition100%3/3
$exports{"mixin"} and not *{"${from}::mixin";}{"CODE"}
!ll&&!rl&&r
1837192115
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 115 ▶ *{"${from}::mixin"} = sub {@_ = ($from, @_); goto \&mixin};
Subroutine __ANON__: called CC=1 SCAR=0.0
82 }
83 2144 ▶ if ($exports{"role"} && !*{"${from}::role"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"role"} and not *{"${from}::role";}{"CODE"}) 114 2030 2144
Condition100%3/3
$exports{"role"} and not *{"${from}::role";}{"CODE"}
!ll&&!rl&&r
1872158114
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 114 ▶ *{"${from}::role"} = sub {@_ = ($from, @_); goto \&role};
Subroutine __ANON__: called CC=1 SCAR=0.0
85 }
86 2144 ▶ if ($exports{"test"} && !*{"${from}::test"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"test"} and not *{"${from}::test";}{"CODE"}) 115 2029 2144
Condition100%3/3
$exports{"test"} and not *{"${from}::test";}{"CODE"}
!ll&&!rl&&r
1837192115
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 115 ▶ *{"${from}::test"} = sub {@_ = ($from, @_); goto \&test};
Subroutine __ANON__: called CC=1 SCAR=0.0
88 }
89 2144 ▶ if (!*{"${from}::true"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (*{"${from}::true";}{"CODE"}) 1814 330 2144
90 1814 ▶ *{"${from}::true"} = sub {require Venus; Venus::true()};
Subroutine __ANON__: called CC=1 SCAR=0.0
91 }
92 2144 ▶ if ($exports{"with"} && !*{"${from}::with"}{"CODE"}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exports{"with"} and not *{"${from}::with";}{"CODE"}) 1262 882 2144
Condition100%3/3
$exports{"with"} and not *{"${from}::with";}{"CODE"}
!ll&&!rl&&r
6782041262
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 1262 ▶ *{"${from}::with"} = sub {@_ = ($from, @_); goto \&test};
Subroutine __ANON__: called CC=1 SCAR=0.0
94 }
95  
96 2144 ${"${from}::META"} = {};
97  
98 2144 ${"${from}::@{[$from->METACACHE]}"} = undef;
99  
100 2144 return $self;
101 }
102  
103 # ROUTINES
104  
105 2243 ▶sub attr {
Subroutine attr: called CC=1 SCAR=0.0
Pod documented
106 2243 my ($from, @args) = @_;
107  
108 2243 $from->ATTR(@args);
109  
110 2243 return $from;
111 }
112  
113 1710 ▶sub base {
Subroutine base: called CC=1 SCAR=0.0
Pod documented
114 1710 my ($from, @args) = @_;
115  
116 1710 $from->BASE(@args);
117  
118 1710 return $from;
119 }
120  
121 2 ▶sub from {
Subroutine from: called CC=1 SCAR=0.0
Pod documented
122 2 my ($from, @args) = @_;
123  
124 2 $from->FROM(@args);
125  
126 2 return $from;
127 }
128  
129 10 ▶sub mask {
Subroutine mask: called CC=1 SCAR=0.0
Pod documented
130 10 my ($from, @args) = @_;
131  
132 10 $from->MASK(@args);
133  
134 10 return $from;
135 }
136  
137 44 ▶sub mixin {
Subroutine mixin: called CC=1 SCAR=0.0
Pod documented
138 44 my ($from, @args) = @_;
139  
140 44 $from->MIXIN(@args);
141  
142 44 return $from;
143 }
144  
145 4 ▶sub role {
Subroutine role: called CC=1 SCAR=0.0
Pod documented
146 4 my ($from, @args) = @_;
147  
148 4 $from->ROLE(@args);
149  
150 4 return $from;
151 }
152  
153 4476 ▶sub test {
Subroutine test: called CC=1 SCAR=0.0
Pod documented
154 4476 my ($from, @args) = @_;
155  
156 4476 $from->TEST(@args);
157  
158 4474 return $from;
159 }
160  
161 119 1;
162  
163  
164  
165 =head1 NAME
166  
167 Venus::Class - Class Builder
168  
169 =cut
170  
171 =head1 ABSTRACT
172  
173 Class 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 class builder which when used causes the consumer to
256 inherit from L<Venus::Core::Class> which provides object construction and
257 lifecycle L<hooks|Venus::Core>.
258  
259 =cut
260  
261 =head1 FUNCTIONS
262  
263 This package provides the following functions:
264  
265 =cut
266  
267 =head2 after
268  
269 after(string $name, coderef $code) (coderef)
270  
271 The after function installs a method modifier that executes after the original
272 method, allowing you to perform actions after a method call. B<Note:> The
273 return value of the modifier routine is ignored; the wrapped method always
274 returns the value from the original method. Modifiers are executed in the order
275 they are stacked. This function is only exported when requested.
276  
277 I<Since C<4.15>>
278  
279 =over 4
280  
281 =item after example 1
282  
283 package Example1;
284  
285 use Venus::Class 'after', 'attr';
286  
287 attr 'calls';
288  
289 sub BUILD {
290 my ($self) = @_;
291 $self->calls([]);
292 }
293  
294 sub test {
295 my ($self) = @_;
296 push @{$self->calls}, 'original';
297 return 'original';
298 }
299  
300 after 'test', sub {
301 my ($self) = @_;
302 push @{$self->calls}, 'after';
303 return 'ignored';
304 };
305  
306 package main;
307  
308 my $example = Example1->new;
309 my $result = $example->test;
310  
311 # "original"
312  
313 =back
314  
315 =cut
316  
317 =head2 around
318  
319 around(string $name, coderef $code) (coderef)
320  
321 The around function installs a method modifier that wraps around the original
322 method. The callback provided will recieve the original routine as its first
323 argument. This function is only exported when requested.
324  
325 I<Since C<4.15>>
326  
327 =over 4
328  
329 =item around example 1
330  
331 package Example2;
332  
333 use Venus::Class 'around', 'attr';
334  
335 sub test {
336 my ($self, $value) = @_;
337 return $value;
338 }
339  
340 around 'test', sub {
341 my ($orig, $self, $value) = @_;
342 return $self->$orig($value) * 2;
343 };
344  
345 package main;
346  
347 my $result = Example2->new->test(5);
348  
349 # 10
350  
351 =back
352  
353 =cut
354  
355 =head2 attr
356  
357 attr(string $name) (string)
358  
359 The attr function creates attribute accessors for the calling package. This
360 function is always exported unless a routine of the same name already exists.
361  
362 I<Since C<1.00>>
363  
364 =over 4
365  
366 =item attr example 1
367  
368 package Example;
369  
370 use Venus::Class;
371  
372 attr 'name';
373  
374 # "Example"
375  
376 =back
377  
378 =cut
379  
380 =head2 base
381  
382 base(string $name) (string)
383  
384 The base function registers one or more base classes for the calling package.
385 This function is always exported unless a routine of the same name already
386 exists.
387  
388 I<Since C<1.00>>
389  
390 =over 4
391  
392 =item base example 1
393  
394 package Entity;
395  
396 use Venus::Class;
397  
398 sub output {
399 return;
400 }
401  
402 package Example;
403  
404 use Venus::Class;
405  
406 base 'Entity';
407  
408 # "Example"
409  
410 =back
411  
412 =cut
413  
414 =head2 before
415  
416 before(string $name, coderef $code) (coderef)
417  
418 The before function installs a method modifier that executes before the
419 original method, allowing you to perform actions before a method call. B<Note:>
420 The return value of the modifier routine is ignored; the wrapped method always
421 returns the value from the original method. Modifiers are executed in the order
422 they are stacked. This function is only exported when requested.
423  
424 I<Since C<4.15>>
425  
426 =over 4
427  
428 =item before example 1
429  
430 package Example3;
431  
432 use Venus::Class 'attr', 'before';
433  
434 attr 'calls';
435  
436 sub BUILD {
437 my ($self) = @_;
438 $self->calls([]);
439 }
440  
441 sub test {
442 my ($self) = @_;
443 push @{$self->calls}, 'original';
444 return $self;
445 }
446  
447 before 'test', sub {
448 my ($self) = @_;
449 push @{$self->calls}, 'before';
450 return $self;
451 };
452  
453 package main;
454  
455 my $example = Example3->new;
456 $example->test;
457 my $calls = $example->calls;
458  
459 # ['before', 'original']
460  
461 =back
462  
463 =cut
464  
465 =head2 catch
466  
467 catch(coderef $block) (Venus::Error, any)
468  
469 The catch function executes the code block trapping errors and returning the
470 caught exception in scalar context, and also returning the result as a second
471 argument in list context. This function isn't export unless requested.
472  
473 I<Since C<1.01>>
474  
475 =over 4
476  
477 =item catch example 1
478  
479 package Example;
480  
481 use Venus::Class 'catch';
482  
483 sub attempt {
484 catch {die};
485 }
486  
487 package main;
488  
489 my $example = Example->new;
490  
491 my $error = $example->attempt;
492  
493 $error;
494  
495 # "Died at ..."
496  
497 =back
498  
499 =cut
500  
501 =head2 error
502  
503 error(maybe[hashref] $args) (Venus::Error)
504  
505 The error function throws a L<Venus::Error> exception object using the
506 exception object arguments provided. This function isn't export unless requested.
507  
508 I<Since C<1.01>>
509  
510 =over 4
511  
512 =item error example 1
513  
514 package Example;
515  
516 use Venus::Class 'error';
517  
518 sub attempt {
519 error;
520 }
521  
522 package main;
523  
524 my $example = Example->new;
525  
526 my $error = $example->attempt;
527  
528 # bless({...}, 'Venus::Error')
529  
530 =back
531  
532 =cut
533  
534 =head2 false
535  
536 false() (boolean)
537  
538 The false function returns a falsy boolean value which is designed to be
539 practically indistinguishable from the conventional numerical C<0> value. This
540 function is always exported unless a routine of the same name already exists.
541  
542 I<Since C<1.00>>
543  
544 =over 4
545  
546 =item false example 1
547  
548 package Example;
549  
550 use Venus::Class;
551  
552 my $false = false;
553  
554 # 0
555  
556 =back
557  
558 =cut
559  
560 =head2 from
561  
562 from(string $name) (string)
563  
564 The from function registers one or more base classes for the calling package
565 and performs an L<"audit"|Venus::Core/AUDIT>. This function is always exported
566 unless a routine of the same name already exists.
567  
568 I<Since C<1.00>>
569  
570 =over 4
571  
572 =item from example 1
573  
574 package Entity;
575  
576 use Venus::Class;
577  
578 sub AUDIT {
579 my ($self, $from) = @_;
580 die "Missing startup" if !$from->can('startup');
581 die "Missing shutdown" if !$from->can('shutdown');
582 }
583  
584 package Example;
585  
586 use Venus::Class;
587  
588 attr 'startup';
589 attr 'shutdown';
590  
591 from 'Entity';
592  
593 # "Example"
594  
595 =back
596  
597 =cut
598  
599 =head2 handle
600  
601 handle(string $name, coderef $code) (coderef)
602  
603 The handle function installs a method modifier that wraps a method, providing
604 low-level control. The callback provided will recieve the original routine as
605 its first argument (or C<undef> if the source routine doesn't exist). This
606 function is only exported when requested.
607  
608 I<Since C<4.15>>
609  
610 =over 4
611  
612 =item handle example 1
613  
614 package Example4;
615  
616 use Venus::Class 'attr', 'handle';
617  
618 sub test {
619 my ($self, $value) = @_;
620 return $value;
621 }
622  
623 handle 'test', sub {
624 my ($orig, $self, $value) = @_;
625 return $orig ? $self->$orig($value * 2) : 0;
626 };
627  
628 package main;
629  
630 my $result = Example4->new->test(5);
631  
632 # 10
633  
634 =back
635  
636 =cut
637  
638 =head2 hook
639  
640 hook(string $type, string $name, coderef $code) (coderef)
641  
642 The hook function installs a method modifier on a lifecycle hook method. The
643 first argument is the type of modifier desired, e.g., L</before>, L</after>,
644 L</around>, and the callback provided will recieve the original routine as its
645 first argument. This function is only exported when requested.
646  
647 I<Since C<4.15>>
648  
649 =over 4
650  
651 =item hook example 1
652  
653 package Example5;
654  
655 use Venus::Class 'attr', 'hook';
656  
657 attr 'startup';
658  
659 sub BUILD {
660 my ($self, $args) = @_;
661 $self->startup('original');
662 }
663  
664 hook 'after', 'build', sub {
665 my ($self) = @_;
666 $self->startup('modified');
667 };
668  
669 package main;
670  
671 my $result = Example5->new->startup;
672  
673 # "modified"
674  
675 =back
676  
677 =cut
678  
679 =head2 mask
680  
681 mask(string $name) (string)
682  
683 The mask function creates private attribute accessors that can only be accessed
684 from within the class or its subclasses. This function is exported on-demand
685 unless a routine of the same name already exists.
686  
687 I<Since C<4.15>>
688  
689 =over 4
690  
691 =item mask example 1
692  
693 package Example;
694  
695 use Venus::Class;
696  
697 mask 'secret';
698  
699 sub set_secret {
700 my ($self, $value) = @_;
701 $self->secret($value);
702 }
703  
704 sub get_secret {
705 my ($self) = @_;
706 return $self->secret;
707 }
708  
709 package main;
710  
711 my $example = Example->new;
712  
713 # $example->set_secret('...')
714  
715 # $example->get_secret
716  
717 # Exception! (if accessed externally)
718 # $example->secret
719  
720 =back
721  
722 =cut
723  
724 =head2 mixin
725  
726 mixin(string $name) (string)
727  
728 The mixin function registers and consumes mixins for the calling package. This
729 function is always exported unless a routine of the same name already exists.
730  
731 I<Since C<1.02>>
732  
733 =over 4
734  
735 =item mixin example 1
736  
737 package YesNo;
738  
739 use Venus::Mixin;
740  
741 sub no {
742 return 0;
743 }
744  
745 sub yes {
746 return 1;
747 }
748  
749 sub EXPORT {
750 ['no', 'yes']
751 }
752  
753 package Answer;
754  
755 use Venus::Class;
756  
757 mixin 'YesNo';
758  
759 # "Answer"
760  
761 =back
762  
763 =over 4
764  
765 =item mixin example 2
766  
767 package YesNo;
768  
769 use Venus::Mixin;
770  
771 sub no {
772 return 0;
773 }
774  
775 sub yes {
776 return 1;
777 }
778  
779 sub EXPORT {
780 ['no', 'yes']
781 }
782  
783 package Answer;
784  
785 use Venus::Class;
786  
787 mixin 'YesNo';
788  
789 sub no {
790 return [0];
791 }
792  
793 sub yes {
794 return [1];
795 }
796  
797 my $package = "Answer";
798  
799 # "Answer"
800  
801 =back
802  
803 =cut
804  
805 =head2 raise
806  
807 raise(string $class | tuple[string, string] $class, maybe[hashref] $args) (Venus::Error)
808  
809 The raise function generates and throws a named exception object derived from
810 L<Venus::Error>, or provided base class, using the exception object arguments
811 provided. This function isn't export unless requested.
812  
813 I<Since C<1.01>>
814  
815 =over 4
816  
817 =item raise example 1
818  
819 package Example;
820  
821 use Venus::Class 'raise';
822  
823 sub attempt {
824 raise 'Example::Error';
825 }
826  
827 package main;
828  
829 my $example = Example->new;
830  
831 my $error = $example->attempt;
832  
833 # bless({...}, 'Example::Error')
834  
835 =back
836  
837 =cut
838  
839 =head2 role
840  
841 role(string $name) (string)
842  
843 The role function registers and consumes roles for the calling package. This
844 function is always exported unless a routine of the same name already exists.
845  
846 I<Since C<1.00>>
847  
848 =over 4
849  
850 =item role example 1
851  
852 package Ability;
853  
854 use Venus::Role;
855  
856 sub action {
857 return;
858 }
859  
860 package Example;
861  
862 use Venus::Class;
863  
864 role 'Ability';
865  
866 # "Example"
867  
868 =back
869  
870 =over 4
871  
872 =item role example 2
873  
874 package Ability;
875  
876 use Venus::Role;
877  
878 sub action {
879 return;
880 }
881  
882 sub EXPORT {
883 return ['action'];
884 }
885  
886 package Example;
887  
888 use Venus::Class;
889  
890 role 'Ability';
891  
892 # "Example"
893  
894 =back
895  
896 =cut
897  
898 =head2 test
899  
900 test(string $name) (string)
901  
902 The test function registers and consumes roles for the calling package and
903 performs an L<"audit"|Venus::Core/AUDIT>, effectively allowing a role to act as
904 an interface. This function is always exported unless a routine of the same
905 name already exists.
906  
907 I<Since C<1.00>>
908  
909 =over 4
910  
911 =item test example 1
912  
913 package Actual;
914  
915 use Venus::Role;
916  
917 package Example;
918  
919 use Venus::Class;
920  
921 test 'Actual';
922  
923 # "Example"
924  
925 =back
926  
927 =over 4
928  
929 =item test example 2
930  
931 package Actual;
932  
933 use Venus::Role;
934  
935 sub AUDIT {
936 die "Example is not an 'actual' thing" if $_[1]->isa('Example');
937 }
938  
939 package Example;
940  
941 use Venus::Class;
942  
943 test 'Actual';
944  
945 # "Example"
946  
947 =back
948  
949 =cut
950  
951 =head2 true
952  
953 true() (boolean)
954  
955 The true function returns a truthy boolean value which is designed to be
956 practically indistinguishable from the conventional numerical C<1> value. 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 true example 1
964  
965 package Example;
966  
967 use Venus::Class;
968  
969 my $true = true;
970  
971 # 1
972  
973 =back
974  
975 =over 4
976  
977 =item true example 2
978  
979 package Example;
980  
981 use Venus::Class;
982  
983 my $false = !true;
984  
985 # 0
986  
987 =back
988  
989 =cut
990  
991 =head2 with
992  
993 with(string $name) (string)
994  
995 The with function registers and consumes roles for the calling package. This
996 function is an alias of the L</test> function and will perform an
997 L<"audit"|Venus::Core/AUDIT> if present. This function is always exported
998 unless a routine of the same name already exists.
999  
1000 I<Since C<1.00>>
1001  
1002 =over 4
1003  
1004 =item with example 1
1005  
1006 package Understanding;
1007  
1008 use Venus::Role;
1009  
1010 sub knowledge {
1011 return;
1012 }
1013  
1014 package Example;
1015  
1016 use Venus::Class;
1017  
1018 with 'Understanding';
1019  
1020 # "Example"
1021  
1022 =back
1023  
1024 =over 4
1025  
1026 =item with example 2
1027  
1028 package Understanding;
1029  
1030 use Venus::Role;
1031  
1032 sub knowledge {
1033 return;
1034 }
1035  
1036 sub EXPORT {
1037 return ['knowledge'];
1038 }
1039  
1040 package Example;
1041  
1042 use Venus::Class;
1043  
1044 with 'Understanding';
1045  
1046 # "Example"
1047  
1048 =back
1049  
1050 =cut
1051  
1052 =head1 AUTHORS
1053  
1054 Awncorp, C<awncorp@cpan.org>
1055  
1056 =cut
1057  
1058 =head1 LICENSE
1059  
1060 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
1061  
1062 This program is free software, you can redistribute it and/or modify it under
1063 the terms of the Apache license version 2.0.
1064  
1065 =cut
« blib/lib/Venus/Os.pm ↑ Summary blib/lib/Venus/Mixin.pm »