blib/lib/Venus/Hook.pm

filter: Statementstmt 87.7% 423 / 482 Branchbran 70.3% 45 / 64 Conditioncond 60.6% 20 / 33 MC/DCmcdc 28.5% 6 / 21 Subroutinesub 91.8% 90 / 98 Podpod 60.0% 27 / 45 totaltotal 82.2% 611 / 743 CC 60 SCAR 15.6
CC
60
Cov
84%
STORE
30.6
__ANON__
11.0
DECONSTRUCT_FOR_CLASS
7.6
CRAP 4.7
« blib/lib/Venus/Role/Encaseable.pm ↑ Summary blib/lib/Venus/Hash.pm »
1 package Venus::Hook;
2  
3 120 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 120 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 120 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 120 ▶use Hash::Util::FieldHash;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 120 ▶no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # HOOKS
13  
14 # ARGS hook
15 116848 ▶sub ARGS {
Subroutine ARGS: called CC=6 SCAR=18.0
Pod documented
16 116848 my ($self, @args) = @_;
17  
18 return (!@args)
19 ? ($self->DATA)
20 : ((@args == 1 && ref($args[0]) eq 'HASH')
21 116848 ▶ ? (do{my %args = %{$args[0]}; !CORE::keys(%args) ? $self->DATA : {%args}})
Branch: 4 branches
BranchTrueFalseTotal
!@args ? : 16229 100619 116848
@args == 1 && ref $args[0] eq 'HASH' ? : 33622 66997 100619
!keys(%args) ? : 7 33615 33622
@args % 2 ? : 0 66997 66997
Condition66%2/3
@args == 1 and ref $args[0] eq "HASH"
!ll&&!rl&&r
66997033622
MC/DC50%1/2
@args == 1 and ref $args[0] eq "HASH"
@args == 1 ref $args[0] eq "HASH"
Truth table66%2/3
A and B
A= @args == 1B= ref $args[0] eq "HASH"
ABresult
0X0
100
111
22 : (@args % 2 ? {@args, undef} : {@args}));
23 }
24  
25 # ATTR hook
26 2503 ▶sub ATTR {
Subroutine ATTR: called CC=2 SCAR=6.9
Pod documented
27 2503 my ($self, $attr, @args) = @_;
28  
29 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
30  
31 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
32  
33 2185 ▶ *{"@{[$self->NAME]}::$attr"} = sub {$_[0]->ITEM($attr, @_[1..$#_])}
Subroutine __ANON__: called CC=1 SCAR=0.0
34 2503 ▶ if !$self->can($attr);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->can($attr) 2185 318 2503
35  
36 2503 my $index = int(keys(%{$${"@{[$self->NAME]}::META"}{ATTR}})) + 1;
37  
38 2503 $${"@{[$self->NAME]}::META"}{ATTR}{$attr} = [$index, [$attr, @args]];
39  
40 2503 my $metacache = join '::', $self->NAME, $self->METACACHE;
41  
42 2503 ${$metacache} = undef;
43  
44 2503 return $self;
45 }
46  
47 # AUDIT hook
48 3072 ▶sub AUDIT {
Subroutine AUDIT: called CC=1 SCAR=0.0
Pod documented
49 3072 my ($self) = @_;
50  
51 3072 return $self;
52 }
53  
54 # BASE hook
55 1723 ▶sub BASE {
Subroutine BASE: called CC=3 SCAR=11.0
Pod documented
56 1723 my ($self, $base, @args) = @_;
57  
58 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
59  
60 1723 ▶ if (!grep !/\A[^:]+::\z/, keys(%{"${base}::"})) {
Branch: 1 branch
BranchTrueFalseTotal
unless (grep((!/\A[^:]+::\z/u), keys %{"${base}::";})) 505 1218 1723
61 505 ▶ local $@; eval "require $base"; do{require Venus; Venus::fault($@)} if $@;
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 1 504 505
62 }
63  
64 1722 @{"@{[$self->NAME]}::ISA"} = (
65 1722 $base, (grep +($_ ne $base), @{"@{[$self->NAME]}::ISA"})
66 );
67  
68 1722 my $index = int(keys(%{$${"@{[$self->NAME]}::META"}{BASE}})) + 1;
69  
70 1722 $${"@{[$self->NAME]}::META"}{BASE}{$base} = [$index, [$base, @args]];
71  
72 1722 my $metacache = join '::', $self->NAME, $self->METACACHE;
73  
74 1722 ${$metacache} = undef;
75  
76 1722 return $self;
77 }
78  
79 # BLESS hook
80 116809 ▶sub BLESS {
Subroutine BLESS: called CC=3 SCAR=11.0
Pod documented
81 116809 my ($self, @args) = @_;
82  
83 116809 my $name = $self->NAME;
84 116809 my $data = $self->DATA($self->ARGS($self->BUILDARGS(@args)));
85 116809 my $anew = bless($data, $name);
86  
87 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
88  
89 116809 $anew->BUILD($data);
90  
91 116799 $anew->CONSTRUCT;
92  
93 116799 ▶ return $anew if $name eq 'Venus::Meta';
Branch: 1 branch
BranchTrueFalseTotal
if $name eq "Venus::Meta" 47849 68950 116799
94  
95 68950 require Venus::Meta;
96  
97 68950 my $metacache = join '::', $self->NAME, $self->METACACHE;
98  
99 68950 ▶ ${$metacache} ||= Venus::Meta->new(name => $name);
Condition66%2/3
${$metacache;} ||= "Venus::Meta"->new("name", $name)
l!l&&r!l&&!r
68888620
MC/DC0%0/2
${$metacache;} ||= "Venus::Meta"->new("name", $name)
${$metacache;} "Venus::Meta"->new("name", $name)
Truth table66%2/3
A ||= B
A= ${$metacache;}B= "Venus::Meta"->new("name", $name)
ABresult
1X1
011
000
100  
101 68950 return $anew;
102 }
103  
104 # BUILD hook
105 47903 ▶sub BUILD {
Subroutine BUILD: called CC=1 SCAR=0.0
Pod documented
106 47903 my ($self) = @_;
107  
108 47903 return $self;
109 }
110  
111 # BUILD hook handler for class
112 68858 ▶sub BUILD_FOR_CLASS {
Subroutine BUILD_FOR_CLASS: called CC=2 SCAR=6.9
Pod undocumented
113 68858 my ($self, @data) = @_;
114  
115 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
116  
117 68858 my @roles = @{$self->META->roles};
118  
119 68858 for my $action (grep defined, map *{"${_}::BUILD"}{"CODE"}, @roles) {
120 100105 $self->$action(@data);
121 }
122  
123 68848 return $self;
124 }
125  
126 # BUILD hook handler for role
127 0 ▶sub BUILD_FOR_ROLE {
Subroutine BUILD_FOR_ROLE: not called CC=2 SCAR=12.2
Pod undocumented
128 0 my ($self, @data) = @_;
129  
130 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
131  
132 0 my @roles = @{$self->META->roles};
133  
134 0 for my $action (grep defined, map *{"${_}::BUILD"}{"CODE"}, @roles) {
135 0 $self->$action(@data);
136 }
137  
138 0 return $self;
139 }
140  
141 # BUILD hook handler for mixin
142 0 ▶sub BUILD_FOR_MIXIN {
Subroutine BUILD_FOR_MIXIN: not called CC=1 SCAR=6.9
Pod undocumented
143 0 my ($self) = @_;
144  
145 0 return $self;
146 }
147  
148 # BUILDARGS hook
149 48368 ▶sub BUILDARGS {
Subroutine BUILDARGS: called CC=1 SCAR=0.0
Pod documented
150 48368 my ($self, @args) = @_;
151  
152 48368 return (@args);
153 }
154  
155 # CONSTRUCT hook
156 47914 ▶sub CONSTRUCT {
Subroutine CONSTRUCT: called CC=1 SCAR=0.0
Pod documented
157 47914 my ($self) = @_;
158  
159 47914 return $self;
160 }
161  
162 # CONSTRUCT hook handler for class
163 68865 ▶sub CONSTRUCT_FOR_CLASS {
Subroutine CONSTRUCT_FOR_CLASS: called CC=3 SCAR=11.1
Pod undocumented
164 68865 my ($self, @data) = @_;
165  
166 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
167  
168 68865 my @mixins = @{$self->META->mixins};
169  
170 68865 for my $action (grep defined, map *{"${_}::CONSTRUCT"}{"CODE"}, @mixins) {
171 0 $self->$action(@data);
172 }
173  
174 68865 my @roles = @{$self->META->roles};
175  
176 68865 for my $action (grep defined, map *{"${_}::CONSTRUCT"}{"CODE"}, @roles) {
177 0 $self->$action(@data);
178 }
179  
180 68865 return $self;
181 }
182  
183 # CONSTRUCT hook handler for role
184 0 ▶sub CONSTRUCT_FOR_ROLE {
Subroutine CONSTRUCT_FOR_ROLE: not called CC=1 SCAR=0.0
Pod undocumented
185 }
186  
187 # CONSTRUCT hook handler for mixin
188 0 ▶sub CONSTRUCT_FOR_MIXIN {
Subroutine CONSTRUCT_FOR_MIXIN: not called CC=1 SCAR=0.0
Pod undocumented
189 }
190  
191 # CLONE hook
192 13 ▶sub CLONE {
Subroutine CLONE: called CC=3 SCAR=11.0
193 13 my ($self) = @_;
194  
195 13 require Scalar::Util;
196  
197 13 ▶ if (!Scalar::Util::blessed($self)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 2 11 13
198 2 require Venus;
199  
200 2 Venus::fault("Can't clone without an instance of \"${self}\"");
201 }
202  
203 11 require Storable;
204  
205 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
206  
207 11 local $Storable::Deparse = 1;
208  
209 11 local $Storable::Eval = 1;
210  
211 11 my $clone = Storable::dclone($self);
212  
213 11 my $store = $self->STORE;
214  
215 11 ▶ my $instance = $store->{$clone} = Storable::dclone($store->{$self} ||= {});
Condition100%2/2
$store->{$self} ||= {}
l!l
74
MC/DC100%1/1
$store->{$self} ||= {}
$store->{$self}
Truth table100%2/2
A
A= $store->{$self}
Aresult
11
00
216  
217 11 return $clone;
218 }
219  
220 # DATA hook
221 133032 ▶sub DATA {
Subroutine DATA: called CC=2 SCAR=6.9
Pod documented
222 133032 my ($self, $data) = @_;
223  
224 133032 ▶ return $data || {};
Condition100%2/2
$data || {}
l!l
11679916233
MC/DC100%1/1
$data || {}
$data
Truth table100%2/2
A
A= $data
Aresult
11
00
225 }
226  
227 # DECONSTRUCT hook
228 46552 ▶sub DECONSTRUCT {
Subroutine DECONSTRUCT: called CC=1 SCAR=0.0
Pod documented
229 46552 my ($self) = @_;
230  
231 46552 return $self;
232 }
233  
234 # DECONSTRUCT hook handler for class
235 0 ▶sub DECONSTRUCT_FOR_CLASS {
Subroutine DECONSTRUCT_FOR_CLASS: not called CC=3 SCAR=20.3
Pod undocumented
236 0 my ($self, @data) = @_;
237  
238 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
239  
240 0 my @mixins = @{$self->META->mixins};
241  
242 0 for my $action (grep defined, map *{"${_}::DECONSTRUCT"}{"CODE"}, @mixins) {
243 0 $self->$action(@data);
244 }
245  
246 0 my @roles = @{$self->META->roles};
247  
248 0 for my $action (grep defined, map *{"${_}::DECONSTRUCT"}{"CODE"}, @roles) {
249 0 $self->$action(@data);
250 }
251  
252 0 return $self;
253 }
254  
255 # DECONSTRUCT hook handler for role
256 0 ▶sub DECONSTRUCT_FOR_ROLE {
Subroutine DECONSTRUCT_FOR_ROLE: not called CC=1 SCAR=0.0
Pod undocumented
257 }
258  
259 # DECONSTRUCT hook handler for mixin
260 0 ▶sub DECONSTRUCT_FOR_MIXIN {
Subroutine DECONSTRUCT_FOR_MIXIN: not called CC=1 SCAR=0.0
Pod undocumented
261 }
262  
263 # DESTROY hook
264 46555 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
265 46555 my ($self) = @_;
266  
267 46555 $self->DECONSTRUCT;
268  
269 46555 return $self;
270 }
271  
272 # DESTROY hook handler for class
273 68232 ▶sub DESTROY_FOR_CLASS {
Subroutine DESTROY_FOR_CLASS: called CC=3 SCAR=11.1
Pod undocumented
274 68232 my ($self, @data) = @_;
275  
276 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
277  
278 68232 my @mixins = @{$self->META->mixins};
279  
280 68232 for my $action (grep defined, map *{"${_}::DESTROY"}{"CODE"}, @mixins) {
281 0 $self->$action(@data);
282 }
283  
284 68232 my @roles = @{$self->META->roles};
285  
286 68232 for my $action (grep defined, map *{"${_}::DESTROY"}{"CODE"}, @roles) {
287 0 $self->$action(@data);
288 }
289  
290 68232 return $self;
291 }
292  
293 # DESTROY hook handler for role
294 0 ▶sub DESTROY_FOR_ROLE {
Subroutine DESTROY_FOR_ROLE: not called CC=3 SCAR=20.3
Pod undocumented
295 0 my ($self, @data) = @_;
296  
297 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
298  
299 0 my @mixins = @{$self->META->mixins};
300  
301 0 for my $action (grep defined, map *{"${_}::DESTROY"}{"CODE"}, @mixins) {
302 0 $self->$action(@data);
303 }
304  
305 0 my @roles = @{$self->META->roles};
306  
307 0 for my $action (grep defined, map *{"${_}::DESTROY"}{"CODE"}, @roles) {
308 0 $self->$action(@data);
309 }
310  
311 0 return $self;
312 }
313  
314 # DESTROY hook handler for mixin
315 2 ▶sub DESTROY_FOR_MIXIN {
Subroutine DESTROY_FOR_MIXIN: called CC=1 SCAR=0.0
Pod undocumented
316 2 my ($self) = @_;
317  
318 2 return;
319 }
320  
321 # DOES hook
322 633 ▶sub DOES {
Subroutine DOES: called CC=2 SCAR=7.1
Pod documented
323 633 my ($self, $role) = @_;
324  
325 633 ▶ return if !$role;
Branch: 1 branch
BranchTrueFalseTotal
unless $role 0 633 633
326  
327 633 return $self->META->role($role);
328 }
329  
330 # EXPORT hook
331 18 ▶sub EXPORT {
Subroutine EXPORT: called CC=1 SCAR=0.0
Pod documented
332 18 my ($self, $into) = @_;
333  
334 120 ▶ no strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
335 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
336  
337 18 return [@{"${self}::EXPORT"}];
338 }
339  
340 # EXPORT hook handler for class
341 5562 ▶sub EXPORT_FOR_CLASS {
Subroutine EXPORT_FOR_CLASS: called CC=1 SCAR=0.0
Pod undocumented
342 5562 my ($self, $into) = @_;
343  
344 120 ▶ no strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
345 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
346  
347 5562 return [@{"${self}::EXPORT"}];
348 }
349  
350 # EXPORT hook handler for role
351 370 ▶sub EXPORT_FOR_ROLE {
Subroutine EXPORT_FOR_ROLE: called CC=1 SCAR=0.0
Pod undocumented
352 370 my ($self, $into) = @_;
353  
354 120 ▶ no strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
355 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
356  
357 370 return [@{"${self}::EXPORT"}];
358 }
359  
360 # EXPORT hook handler for mixin
361 38 ▶sub EXPORT_FOR_MIXIN {
Subroutine EXPORT_FOR_MIXIN: called CC=1 SCAR=0.0
Pod undocumented
362 38 my ($self, $into) = @_;
363  
364 120 ▶ no strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
365 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
366  
367 38 return [@{"${self}::EXPORT"}];
368 }
369  
370 # FROM hook
371 7 ▶sub FROM {
Subroutine FROM: called CC=2 SCAR=7.0
Pod documented
372 7 my ($self, $base) = @_;
373  
374 7 $self->BASE($base);
375  
376 7 ▶ $base->AUDIT($self->NAME) if $base->can('AUDIT');
Branch: 1 branch
BranchTrueFalseTotal
if $base->can("AUDIT") 7 0 7
377  
378 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
379  
380 6 $base->IMPORT($self->NAME);
381  
382 6 return $self;
383 }
384  
385 # GET hook
386 492298 ▶sub GET {
Subroutine GET: called CC=1 SCAR=0.0
Pod documented
387 492298 my ($self, $name) = @_;
388  
389 492298 return $self->{$name};
390 }
391  
392 # IMPORT hook
393 38 ▶sub IMPORT {
Subroutine IMPORT: called CC=2 SCAR=6.9
Pod documented
394 38 my ($self, $into) = @_;
395  
396 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
397 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
398  
399 38 for my $name (@{$self->EXPORT($into)}) {
400 22 *{"${into}::${name}"} = \&{"@{[$self->NAME]}::${name}"};
401 }
402  
403 38 return $self;
404 }
405  
406 # IMPORT hook handler for class
407 5562 ▶sub IMPORT_FOR_CLASS {
Subroutine IMPORT_FOR_CLASS: called CC=2 SCAR=6.9
Pod undocumented
408 5562 my ($self, $into) = @_;
409  
410 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
411 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
412  
413 5562 for my $name (@{$self->EXPORT($into)}) {
414 1026 *{"${into}::${name}"} = \&{"@{[$self->NAME]}::${name}"};
415 }
416  
417 5562 return $self;
418 }
419  
420 # IMPORT hook handler for role
421 4503 ▶sub IMPORT_FOR_ROLE {
Subroutine IMPORT_FOR_ROLE: called CC=2 SCAR=6.9
Pod undocumented
422 4503 my ($self, $into) = @_;
423  
424 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
425 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
426  
427 4503 for my $name (grep !*{"${into}::${_}"}{"CODE"}, @{$self->EXPORT($into)}) {
428 10961 *{"${into}::${name}"} = \&{"@{[$self->NAME]}::${name}"};
429 }
430  
431 4503 return $self;
432 }
433  
434 # IMPORT hook handler for mixin
435 59 ▶sub IMPORT_FOR_MIXIN {
Subroutine IMPORT_FOR_MIXIN: called CC=2 SCAR=6.9
Pod undocumented
436 59 my ($self, $into) = @_;
437  
438 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
439 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
440  
441 59 for my $name (@{$self->EXPORT($into)}) {
442 39 *{"${into}::${name}"} = \&{"@{[$self->NAME]}::${name}"};
443 }
444  
445 59 return $self;
446 }
447  
448 # ITEM hook
449 553665 ▶sub ITEM {
Subroutine ITEM: called CC=3 SCAR=11.1
Pod documented
450 553665 my ($self, $name, @args) = @_;
451  
452 553665 ▶ return $name ? (@args ? $self->SET($name, $args[0]) : $self->GET($name)) : undef;
Branch: 2 branches
BranchTrueFalseTotal
$name ? : 553665 0 553665
@args ? : 61370 492295 553665
453 }
454  
455 # META hook
456 344805 ▶sub META {
Subroutine META: called CC=2 SCAR=6.9
Pod documented
457 344805 my ($self) = @_;
458  
459 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
460  
461 344805 require Venus::Meta;
462  
463 344805 my $metacache = join '::', my $name = $self->NAME, $self->METACACHE;
464  
465 344805 ▶ return ${$metacache} ||= Venus::Meta->new(name => $name);
Condition66%2/3
${$metacache;} ||= "Venus::Meta"->new("name", $name)
l!l&&r!l&&!r
34269121140
MC/DC0%0/2
${$metacache;} ||= "Venus::Meta"->new("name", $name)
${$metacache;} "Venus::Meta"->new("name", $name)
Truth table66%2/3
A ||= B
A= ${$metacache;}B= "Venus::Meta"->new("name", $name)
ABresult
1X1
011
000
466 }
467  
468 # METACACHE cache name (for META hook)
469 427753 ▶sub METACACHE {
Subroutine METACACHE: called CC=1 SCAR=0.0
Pod documented
470 427753 my ($self) = @_;
471  
472 427753 return 'METACACHE';
473 }
474  
475 # MIXIN hook
476 57 ▶sub MIXIN {
Subroutine MIXIN: called CC=3 SCAR=11.4
Pod documented
477 57 my ($self, $mixin, @args) = @_;
478  
479 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
480  
481 57 ▶ if (!grep !/\A[^:]+::\z/, keys(%{"${mixin}::"})) {
Branch: 1 branch
BranchTrueFalseTotal
unless (grep((!/\A[^:]+::\z/u), keys %{"${mixin}::";})) 0 57 57
482 0 ▶ local $@; eval "require $mixin"; do{require Venus; Venus::fault($@)} if $@;
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
483 }
484  
485 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
486  
487 57 $mixin->IMPORT($self->NAME);
488  
489 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
490  
491 57 my $index = int(keys(%{$${"@{[$self->NAME]}::META"}{MIXIN}})) + 1;
492  
493 57 $${"@{[$self->NAME]}::META"}{MIXIN}{$mixin} = [$index, [$mixin, @args]];
494  
495 57 my $metacache = join '::', $self->NAME, $self->METACACHE;
496  
497 57 ${$metacache} = undef;
498  
499 57 return $self;
500 }
501  
502 # MASK hook
503 177 ▶sub MASK {
Subroutine MASK: called CC=2 SCAR=6.9
Pod documented
504 177 my ($self, $mask, @args) = @_;
505  
506 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
507  
508 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
509  
510 177 my $store = $self->STORE;
511  
512 140 ▶ *{"@{[$self->NAME]}::$mask"} = sub {
Subroutine __ANON__: called CC=11 SCAR=24.0
513 45890 my ($self, @args) = @_;
514  
515 45890 my $caller = caller;
516  
517 45890 require Scalar::Util;
518  
519 45890 ▶ if (!Scalar::Util::blessed($self)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 2 45888 45890
520 2 require Venus;
521  
522 2 Venus::fault(
523 "Can't get/set private variable \"${mask}\" without an instance of \"${self}\""
524 );
525 }
526  
527 45888 my $class = ref $self;
528  
529 45888 ▶ if ($caller ne $class && !$class->isa($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($caller ne $class and not $class->isa($caller)) 45627 261 45888
Condition66%2/3
$caller ne $class and not $class->isa($caller)
!ll&&!rl&&r
261045627
MC/DC50%1/2
$caller ne $class and not $class->isa($caller)
$caller ne $class not $class->isa($caller)
Truth table66%2/3
A and not(B)
A= $caller ne $classB= not $class->isa($caller)
ABresult
0X0
100
111
530 45627 my $authorized = 0;
531  
532 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
533 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
534  
535 45627 ▶ if (${"${caller}::META"} && $${"${caller}::META"}{MASK}{$mask}) {
Branch: 1 branch
BranchTrueFalseTotal
if (${"${caller}::META";} and ${"${caller}::META";}->{"MASK"}{$mask}) 45617 10 45627
Condition66%2/3
${"${caller}::META";} and ${"${caller}::META";}->{"MASK"}{$mask}
!ll&&!rl&&r
10045617
MC/DC50%1/2
${"${caller}::META";} and ${"${caller}::META";}->{"MASK"}{$mask}
${"${caller}::META";} ${"${caller}::META";}->{"MASK"}{$mask}
Truth table66%2/3
A and B
A= ${"${caller}::META";}B= ${"${caller}::META";}->{"MASK"}{$mask}
ABresult
0X0
100
111
536 45617 require Venus::Meta;
537  
538 45617 my $meta = Venus::Meta->new(name => $class);
539  
540 45617 ▶ if ($meta->role($caller) || $meta->mixin($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($meta->role($caller) or $meta->mixin($caller)) 45617 0 45617
Condition66%2/3
$meta->role($caller) or $meta->mixin($caller)
l!l&&r!l&&!r
4561160
MC/DC0%0/2
$meta->role($caller) or $meta->mixin($caller)
$meta->role($caller) $meta->mixin($caller)
Truth table66%2/3
A or B
A= $meta->role($caller)B= $meta->mixin($caller)
ABresult
1X1
011
000
541 45617 $authorized = 1;
542 }
543 }
544  
545 45627 ▶ if (!$authorized) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($authorized) 10 45617 45627
546 10 require Venus;
547  
548 10 Venus::fault(
549 "Can't get/set private variable \"${mask}\" outside the class or subclass of \"${class}\""
550 );
551 }
552 }
553  
554 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
555  
556 45878 ▶ my $variable = $store->{$self} ||= {};
Condition100%2/2
$store->{$self} ||= {}
l!l
436492229
MC/DC100%1/1
$store->{$self} ||= {}
$store->{$self}
Truth table100%2/2
A
A= $store->{$self}
Aresult
11
00
557  
558 45878 ▶ return @args ? ($variable->{$mask} = $args[0]) : $variable->{$mask};
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 2332 43546 45878
559 }
560 177 ▶ if !$self->can($mask);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->can($mask) 140 37 177
561  
562 177 my $index = int(keys(%{$${"@{[$self->NAME]}::META"}{MASK}})) + 1;
563  
564 177 $${"@{[$self->NAME]}::META"}{MASK}{$mask} = [$index, [$mask, @args]];
565  
566 177 my $metacache = join '::', $self->NAME, $self->METACACHE;
567  
568 177 ${$metacache} = undef;
569  
570 177 return $self;
571 }
572  
573 # NAME hook
574 585406 ▶sub NAME {
Subroutine NAME: called CC=2 SCAR=7.1
Pod documented
575 585406 my ($self) = @_;
576  
577 585406 ▶ return ref $self || $self;
Condition66%2/3
ref $self || $self
l!l&&r!l&&!r
3441012413050
MC/DC0%0/2
ref $self || $self
ref $self $self
Truth table66%2/3
A || B
A= ref $selfB= $self
ABresult
1X1
011
000
578 }
579  
580 # ROLE hook
581 4533 ▶sub ROLE {
Subroutine ROLE: called CC=3 SCAR=11.0
Pod documented
582 4533 my ($self, $role, @args) = @_;
583  
584 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
585  
586 4533 ▶ if (!grep !/\A[^:]+::\z/, keys(%{"${role}::"})) {
Branch: 1 branch
BranchTrueFalseTotal
unless (grep((!/\A[^:]+::\z/u), keys %{"${role}::";})) 2657 1876 4533
587 0 ▶ local $@; eval "require $role"; do{require Venus; Venus::fault($@)} if $@;
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 2657 2657
588 }
589  
590 120 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
591  
592 4533 $role->IMPORT($self->NAME);
593  
594 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
595  
596 4533 my $index = int(keys(%{$${"@{[$self->NAME]}::META"}{ROLE}})) + 1;
597  
598 4533 $${"@{[$self->NAME]}::META"}{ROLE}{$role} = [$index, [$role, @args]];
599  
600 4533 my $metacache = join '::', $self->NAME, $self->METACACHE;
601  
602 4533 ${$metacache} = undef;
603  
604 4533 return $self;
605 }
606  
607 # SET hook
608 61372 ▶sub SET {
Subroutine SET: called CC=1 SCAR=0.0
Pod documented
609 61372 my ($self, $name, $data) = @_;
610  
611 61372 return $self->{$name} = $data;
612 }
613  
614 # STORE for private data (for MASK hook)
615 188 ▶sub STORE {
Subroutine STORE: called CC=11 SCAR=34.2
616 188 my ($self) = @_;
617  
618 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
619  
620 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
621  
622 188 state $cache = {};
623  
624 188 my $caller = caller;
625  
626 188 ▶ if (!$cache->{$self->NAME}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($$cache{$self->NAME}) 137 51 188
627 137 my $name = 'STORE';
628  
629 137 for my $class ($self->NAME, $self->META->bases) {
630 412 ▶ if (ref ${"${class}::${name}"}) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref ${"${class}::$name";}) 0 412 412
631 0 $cache->{$self->NAME} = ${"${class}::${name}"};
632 0 last;
633 }
634 }
635  
636 137 ▶ if (!$cache->{$self->NAME}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($$cache{$self->NAME}) 137 0 137
637 137 Hash::Util::FieldHash::fieldhash(my %data);
638  
639 137 $cache->{$self->NAME} = ${"@{[$self->NAME]}::${name}"} = \%data;
640 }
641 }
642  
643 188 ▶ return $cache->{$self->NAME} if $caller eq __PACKAGE__;
Branch: 1 branch
BranchTrueFalseTotal
if $caller eq __PACKAGE__ 188 0 188
644  
645 0 require Scalar::Util;
646  
647 0 ▶ if (!Scalar::Util::blessed($self)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 0 0 0
648 0 require Venus;
649 0 Venus::fault(
650 "Can't access STORE from \"${caller}\""
651 );
652 }
653  
654 0 my $class = ref $self;
655  
656 0 ▶ return $cache->{$self->NAME} if $caller eq $class || $class->isa($caller);
Branch: 1 branch
BranchTrueFalseTotal
if $caller eq $class or $class->isa($caller) 0 0 0
Condition0%0/3
$caller eq $class or $class->isa($caller)
l!l&&r!l&&!r
000
MC/DC0%0/2
$caller eq $class or $class->isa($caller)
$caller eq $class $class->isa($caller)
Truth table0%0/3
A or B
A= $caller eq $classB= $class->isa($caller)
ABresult
1X1
011
000
657  
658 0 require Venus::Meta;
659  
660 0 my $meta = Venus::Meta->new(name => $class);
661  
662 0 ▶ if ($meta->role($caller) || $meta->mixin($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($meta->role($caller) or $meta->mixin($caller)) 0 0 0
Condition0%0/3
$meta->role($caller) or $meta->mixin($caller)
l!l&&r!l&&!r
000
MC/DC0%0/2
$meta->role($caller) or $meta->mixin($caller)
$meta->role($caller) $meta->mixin($caller)
Truth table0%0/3
A or B
A= $meta->role($caller)B= $meta->mixin($caller)
ABresult
1X1
011
000
663 0 return $cache->{$self->NAME};
664 }
665  
666 0 require Venus;
667  
668 0 Venus::fault(
669 "Can't access STORE outside the class or subclass of \"${class}\""
670 );
671 }
672  
673 # SUBS hook
674 2 ▶sub SUBS {
Subroutine SUBS: called CC=1 SCAR=0.0
Pod documented
675 2 my ($self) = @_;
676  
677 120 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
678  
679 return [
680 20 sort grep *{"@{[$self->NAME]}::$_"}{"CODE"},
681 2 grep /^[_a-zA-Z]\w*$/, keys %{"@{[$self->NAME]}::"}
682 ];
683 }
684  
685 # TEST hook
686 4496 ▶sub TEST {
Subroutine TEST: called CC=2 SCAR=7.0
Pod documented
687 4496 my ($self, $role) = @_;
688  
689 4496 $self->ROLE($role);
690  
691 4496 ▶ $role->AUDIT($self->NAME) if $role->can('AUDIT');
Branch: 1 branch
BranchTrueFalseTotal
if $role->can("AUDIT") 4496 0 4496
692  
693 4488 return $self;
694 }
695  
696 # UNIMPORT hook
697 2 ▶sub UNIMPORT {
Subroutine UNIMPORT: called CC=1 SCAR=0.0
Pod documented
698 2 my ($self, $into, @args) = @_;
699  
700 2 return $self;
701 }
702  
703 # USE hook
704 5567 ▶sub USE {
Subroutine USE: called CC=1 SCAR=0.0
Pod documented
705 5567 my ($self, $into, @args) = @_;
706  
707 5567 return $self;
708 }
709  
710 120 1;
711  
712  
713 =head1 NAME
714  
715 Venus::Hook - Venus Lifecycle Hooks
716  
717 =cut
718  
719 =head1 ABSTRACT
720  
721 Lifecycle Hooks for Perl 5
722  
723 =cut
724  
725 =head1 SYNOPSIS
726  
727 package User;
728  
729 use base 'Venus::Core';
730  
731 # Define attributes
732 User->ATTR('name');
733 User->ATTR('email');
734  
735 # Post-construction initialization
736 sub BUILD {
737 my ($self) = @_;
738 $self->{created} = time;
739 return $self;
740 }
741  
742 # Pre-destruction cleanup
743 sub DECONSTRUCT {
744 my ($self) = @_;
745 $self->log("User destroyed");
746 return $self;
747 }
748  
749 package main;
750  
751 my $user = User->BLESS(name => 'Elliot', email => 'e@example.com');
752  
753 # bless({name => 'Elliot', email => 'e@example.com', created => ...}, 'User')
754  
755 =cut
756  
757 =head1 DESCRIPTION
758  
759 This document provides a comprehensive reference for all lifecycle hooks
760 available in the Venus OOP framework. Venus provides a rich set of hooks that
761 allow you to customize class building, object construction, and object
762 destruction behavior.
763  
764 Venus lifecycle hooks are special methods that are automatically invoked at
765 specific points during class building, object construction, and object
766 destruction. These hooks provide extension points for customizing behavior
767 without modifying core Venus code. Hooks are conventionally named in UPPERCASE
768 to distinguish them from regular methods.
769  
770 =cut
771  
772 =head1 SUPER
773  
774 B<When overriding lifecycle hooks in a subclass, you should almost always call
775 the parent implementation using C<SUPER>>, or risk breaking the framework in
776 unexpected ways.
777  
778 The Venus framework relies on proper hook execution throughout the inheritance
779 chain. Failing to call the parent implementation can break functionality in
780 subtle ways, including:
781  
782 =over 4
783  
784 =item * Breaking role/mixin composition and their lifecycle hooks
785  
786 =item * Skipping critical initialization or cleanup code from parent classes
787  
788 =item * Bypassing framework-level validations and setup
789  
790 =item * Causing memory leaks by not cleaning up instance data properly
791  
792 =back
793  
794 =head2 Required
795  
796 When overriding any of the following hooks, you should call C<SUPER> unless you
797 have a very specific reason not to:
798  
799 ARGS, ATTR, AUDIT, BASE, BLESS, BUILD, BUILDARGS, CONSTRUCT, CLONE,
800 DECONSTRUCT, DESTROY, DOES, EXPORT, FROM, GET, IMPORT, ITEM, META,
801 MIXIN, MASK, NAME, ROLE, SET, SUBS, TEST, UNIMPORT, USE
802  
803 =head2 Correct Pattern
804  
805 B<Always call the parent implementation first, then add your custom logic:>
806  
807 package Child;
808  
809 use base 'Parent';
810  
811 sub BUILD {
812 my ($self, $data) = @_;
813  
814 # CRITICAL: Call parent implementation first
815 $self->SUPER::BUILD($data);
816  
817 # Then add your custom logic
818 $self->{child_field} = 'value';
819  
820 return $self;
821 }
822  
823 =head2 Incorrect Pattern
824  
825 B<DO NOT skip the SUPER call:>
826  
827 # WRONG - This breaks the framework!
828 sub BUILD {
829 my ($self, $data) = @_;
830  
831 # Missing: $self->SUPER::BUILD($data);
832  
833 $self->{child_field} = 'value'; # Parent's BUILD never runs!
834  
835 return $self;
836 }
837  
838 =head2 When You Might Skip SUPER
839  
840 There are very rare cases where you might intentionally skip calling SUPER:
841  
842 =over 4
843  
844 =item * You are B<replacing> the parent's behavior entirely (use with extreme caution)
845  
846 =item * You are implementing a base hook that has no parent (e.g., in Venus::Core itself)
847  
848 =item * You are implementing certain introspection hooks like C<DATA> that are meant to be completely overridden
849  
850 =back
851  
852 B<Rule of thumb:> If you're unsure whether to call SUPER, B<call it>. It's almost
853 always the right choice.
854  
855 =cut
856  
857 =head1 HOOKS
858  
859 This package provides the following hooks:
860  
861 =cut
862  
863 =head2 Object Construction Hooks
864  
865 These hooks control how objects are constructed and initialized.
866  
867 =over 4
868  
869 =item args
870  
871 ARGS(any @args) (hashref)
872  
873 The ARGS hook accepts constructor arguments and returns a blessable data
874 structure. It is called during object construction, before blessing.
875  
876 I<Since C<1.00>>
877  
878 =over 4
879  
880 =item args example 1
881  
882 package List;
883  
884 use base 'Venus::Core';
885  
886 sub ARGS {
887 my ($self, @args) = @_;
888  
889 return @args
890 ? ((@args == 1 && ref $args[0] eq 'ARRAY') ? @args : [@args])
891 : $self->DATA;
892 }
893  
894 package main;
895  
896 my $list = List->BLESS(1..4);
897  
898 # bless([1..4], 'List')
899  
900 =back
901  
902 =cut
903  
904 =item bless
905  
906 BLESS(any @args) (object)
907  
908 The BLESS hook is the main object construction hook that creates and returns an
909 instance. It is called when you call the constructor (or C<BLESS> directly).
910 The default behavior is equivalent to calling C<BUILD(bless(ARGS(BUILDARGS(@args)
911 || DATA), $class))>.
912  
913 I<Since C<1.00>>
914  
915 =over 4
916  
917 =item bless example 1
918  
919 package User;
920  
921 use base 'Venus::Core';
922  
923 package main;
924  
925 my $user = User->BLESS(name => 'Elliot');
926  
927 # bless({name => 'Elliot'}, 'User')
928  
929 =back
930  
931 =cut
932  
933 =item buildargs
934  
935 BUILDARGS(any @args) (any @args | hashref $data)
936  
937 The BUILDARGS hook pre-processes constructor arguments before they are converted
938 to a data structure. It is called before C<ARGS>, and receives raw constructor
939 arguments.
940  
941 I<Since C<1.00>>
942  
943 =over 4
944  
945 =item buildargs example 1
946  
947 package User;
948  
949 use base 'Venus::Core';
950  
951 sub BUILDARGS {
952 my ($self, @args) = @_;
953  
954 # Convert single string arg to hashref
955 my $data = @args == 1 && !ref $args[0] ? {name => $args[0]} : {};
956  
957 return $data;
958 }
959  
960 package main;
961  
962 my $user = User->BLESS('Elliot');
963  
964 # bless({name => 'Elliot'}, 'User')
965  
966 =back
967  
968 =cut
969  
970 =item build
971  
972 BUILD(hashref $data) (object)
973  
974 The BUILD hook is a post-construction initialization hook. It receives the
975 blessed object and can modify it. It is called after the object is blessed,
976 before it's returned to the caller. While the return value is ignored by
977 C<BLESS>, it should return C<$self> for chaining.
978  
979 B<Note:> When inheriting, you should call the parent's BUILD using
980 C<$self-E<gt>SUPER::BUILD($data)>.
981  
982 I<Since C<1.00>>
983  
984 =over 4
985  
986 =item build example 1
987  
988 package User;
989  
990 use base 'Venus::Core';
991  
992 sub BUILD {
993 my ($self) = @_;
994  
995 $self->{name} = 'Mr. Robot';
996  
997 return $self;
998 }
999  
1000 package main;
1001  
1002 my $user = User->BLESS(name => 'Elliot');
1003  
1004 # bless({name => 'Mr. Robot'}, 'User')
1005  
1006 =back
1007  
1008 =over 4
1009  
1010 =item build example 2
1011  
1012 package Elliot;
1013  
1014 use base 'User';
1015  
1016 sub BUILD {
1017 my ($self, $data) = @_;
1018  
1019 $self->SUPER::BUILD($data);
1020  
1021 $self->{name} = 'Elliot';
1022  
1023 return $self;
1024 }
1025  
1026 package main;
1027  
1028 my $user = Elliot->BLESS;
1029  
1030 # bless({name => 'Elliot'}, 'Elliot')
1031  
1032 =back
1033  
1034 =cut
1035  
1036 =item construct
1037  
1038 CONSTRUCT() (any)
1039  
1040 The CONSTRUCT hook is an additional post-construction hook for instance
1041 preparation, separate from the build process. It is called automatically after
1042 C<BLESS>, without arguments. The return value is not used in subsequent
1043 processing.
1044  
1045 I<Since C<4.15>>
1046  
1047 =over 4
1048  
1049 =item construct example 1
1050  
1051 package User;
1052  
1053 use base 'Venus::Core';
1054  
1055 sub CONSTRUCT {
1056 my ($self) = @_;
1057  
1058 $self->{ready} = 1;
1059  
1060 return $self;
1061 }
1062  
1063 package main;
1064  
1065 my $user = User->BLESS(name => 'Elliot');
1066  
1067 # bless({name => 'Elliot', ready => 1}, 'User')
1068  
1069 =back
1070  
1071 =cut
1072  
1073 =item data
1074  
1075 DATA() (Ref)
1076  
1077 The DATA hook returns the default data structure to bless when no arguments are
1078 provided. It is called during object construction when no arguments are given.
1079 The default implementation returns an empty hashref C<{}>.
1080  
1081 I<Since C<1.00>>
1082  
1083 =over 4
1084  
1085 =item data example 1
1086  
1087 package Example;
1088  
1089 use base 'Venus::Core';
1090  
1091 sub DATA {
1092 return []; # Use arrayref instead of hashref
1093 }
1094  
1095 package main;
1096  
1097 my $example = Example->BLESS;
1098  
1099 # bless([], 'Example')
1100  
1101 =back
1102  
1103 =cut
1104  
1105 =item clone
1106  
1107 CLONE() (object)
1108  
1109 The CLONE hook creates a deep clone of the invocant. It is called when you call
1110 C<clone> or C<CLONE>. It must be called on an object instance (not a class).
1111 Private data (from C<MASK>) is not included in the clone.
1112  
1113 I<Since C<4.15>>
1114  
1115 =over 4
1116  
1117 =item clone example 1
1118  
1119 package User;
1120  
1121 use base 'Venus::Core';
1122  
1123 User->MASK('password');
1124  
1125 sub get_password {
1126 my ($self) = @_;
1127 $self->password;
1128 }
1129  
1130 sub set_password {
1131 my ($self) = @_;
1132 $self->password('secret');
1133 }
1134  
1135 package main;
1136  
1137 my $user = User->BLESS(name => 'Elliot');
1138 $user->set_password;
1139  
1140 my $clone = $user->CLONE;
1141  
1142 # bless({name => 'Elliot'}, 'User')
1143 # Note: Private data (password) is not cloned
1144  
1145 =back
1146  
1147 =cut
1148  
1149 =back
1150  
1151 =head2 Object Destruction Hooks
1152  
1153 These hooks are invoked when objects are being destroyed.
1154  
1155 =over 4
1156  
1157 =item deconstruct
1158  
1159 DECONSTRUCT() (any)
1160  
1161 The DECONSTRUCT hook is a pre-destruction cleanup hook for releasing resources
1162 before the object is destroyed. It is called just before C<DESTROY>. The return
1163 value is not used in subsequent processing.
1164  
1165 I<Since C<4.15>>
1166  
1167 =over 4
1168  
1169 =item deconstruct example 1
1170  
1171 package User;
1172  
1173 use base 'Venus::Core';
1174  
1175 our $CALLS = 0;
1176 our $USERS = 0;
1177  
1178 sub CONSTRUCT {
1179 return $CALLS = $USERS += 1;
1180 }
1181  
1182 sub DECONSTRUCT {
1183 return $USERS--;
1184 }
1185  
1186 package main;
1187  
1188 my $user = User->BLESS('Elliot');
1189 # $User::USERS is now 1
1190  
1191 undef $user;
1192 # $User::USERS is now 0
1193  
1194 =back
1195  
1196 =cut
1197  
1198 =item destroy
1199  
1200 DESTROY() (any)
1201  
1202 The DESTROY hook is the object destruction lifecycle hook. It is called when the
1203 last reference to the object goes away.
1204  
1205 I<Since C<1.00>>
1206  
1207 =over 4
1208  
1209 =item destroy example 1
1210  
1211 package User;
1212  
1213 use base 'Venus::Core';
1214  
1215 our $TRIES = 0;
1216  
1217 sub BUILD {
1218 return $TRIES++;
1219 }
1220  
1221 sub DESTROY {
1222 return $TRIES--;
1223 }
1224  
1225 package main;
1226  
1227 my $user = User->BLESS(name => 'Elliot');
1228 undef $user;
1229 # $User::TRIES is now 0
1230  
1231 =back
1232  
1233 =cut
1234  
1235 =back
1236  
1237 =head2 Class Building Hooks
1238  
1239 These hooks are used during class definition to set up the class structure.
1240  
1241 =over 4
1242  
1243 =item attr
1244  
1245 ATTR(string $name, any @args) (string | object)
1246  
1247 The ATTR hook installs attribute accessors in the calling package. It is called
1248 during class building when you call C<attr> or C<ATTR>. It creates getter/setter
1249 methods for the named attribute.
1250  
1251 I<Since C<1.00>>
1252  
1253 =over 4
1254  
1255 =item attr example 1
1256  
1257 package User;
1258  
1259 use base 'Venus::Core';
1260  
1261 User->ATTR('name');
1262 User->ATTR('role');
1263  
1264 package main;
1265  
1266 my $user = User->BLESS(role => 'Engineer');
1267  
1268 $user->name; # ""
1269 $user->name('Elliot'); # "Elliot"
1270 $user->role; # "Engineer"
1271 $user->role('Hacker'); # "Hacker"
1272  
1273 =back
1274  
1275 =cut
1276  
1277 =item base
1278  
1279 BASE(string $name) (string | object)
1280  
1281 The BASE hook registers one or more base classes for the calling package. It is
1282 called during class building. B<Note:> Unlike C<FROM>, this does NOT invoke the
1283 C<AUDIT> hook.
1284  
1285 I<Since C<1.00>>
1286  
1287 =over 4
1288  
1289 =item base example 1
1290  
1291 package Entity;
1292  
1293 sub work {
1294 return;
1295 }
1296  
1297 package User;
1298  
1299 use base 'Venus::Core';
1300  
1301 User->BASE('Entity');
1302  
1303 package main;
1304  
1305 my $user = User->BLESS;
1306 # $user->can('work') is true
1307  
1308 =back
1309  
1310 =cut
1311  
1312 =item mask
1313  
1314 MASK(string $name, any @args) (string | object)
1315  
1316 The MASK hook installs private instance data accessors that can only be accessed
1317 within the class or its subclasses. It is called during class building. It
1318 creates accessors that raise an exception if accessed outside the class
1319 hierarchy.
1320  
1321 I<Since C<4.15>>
1322  
1323 =over 4
1324  
1325 =item mask example 1
1326  
1327 package User;
1328  
1329 use base 'Venus::Core';
1330  
1331 User->MASK('password');
1332  
1333 sub get_password {
1334 my ($self) = @_;
1335 $self->password; # OK: called from within class
1336 }
1337  
1338 sub set_password {
1339 my ($self, $value) = @_;
1340 $self->password($value); # OK: called from within class
1341 }
1342  
1343 package main;
1344  
1345 my $user = User->BLESS(name => 'Elliot');
1346 $user->set_password('secret'); # Works
1347  
1348 # $user->password; # Exception! Can't access private variable
1349  
1350 =back
1351  
1352 =cut
1353  
1354 =back
1355  
1356 =head2 Composition Hooks
1357  
1358 These hooks handle role and mixin composition.
1359  
1360 =over 4
1361  
1362 =item role
1363  
1364 ROLE(string $name) (string | object)
1365  
1366 The ROLE hook consumes a role into the calling package. It is called during
1367 class building via the C<role> function.
1368  
1369 B<Behavior:>
1370  
1371 =over 4
1372  
1373 =item * Methods are copied from the role to the consumer
1374  
1375 =item * Methods are NOT copied if they already exist in the consumer
1376  
1377 =item * First method wins in naming collisions
1378  
1379 =item * Automatically invokes the role's C<IMPORT> hook
1380  
1381 =item * Does NOT invoke the role's C<AUDIT> hook
1382  
1383 =back
1384  
1385 I<Since C<1.00>>
1386  
1387 =over 4
1388  
1389 =item role example 1
1390  
1391 package Admin;
1392  
1393 use base 'Venus::Core';
1394  
1395 package User;
1396  
1397 use base 'Venus::Core';
1398  
1399 User->ROLE('Admin');
1400  
1401 package main;
1402  
1403 User->DOES('Admin'); # 1
1404  
1405 =back
1406  
1407 =cut
1408  
1409 =item mixin
1410  
1411 MIXIN(string $name) (string | object)
1412  
1413 The MIXIN hook consumes a mixin into the calling package. It is called during
1414 class building via the C<mixin> function.
1415  
1416 B<Behavior:>
1417  
1418 =over 4
1419  
1420 =item * Methods are ALWAYS copied, even if they already exist (override)
1421  
1422 =item * Last mixin wins in naming collisions
1423  
1424 =item * Automatically invokes the mixin's C<IMPORT> hook
1425  
1426 =item * More aggressive than roles
1427  
1428 =back
1429  
1430 I<Since C<1.02>>
1431  
1432 =over 4
1433  
1434 =item mixin example 1
1435  
1436 package Action;
1437  
1438 use base 'Venus::Core';
1439  
1440 package User;
1441  
1442 use base 'Venus::Core';
1443  
1444 User->MIXIN('Action');
1445  
1446 package main;
1447  
1448 User->DOES('Action'); # 0 (mixins don't register as roles)
1449  
1450 =back
1451  
1452 =cut
1453  
1454 =item test
1455  
1456 TEST(string $name) (string | object)
1457  
1458 The TEST hook consumes a role and invokes its C<AUDIT> hook for interface
1459 validation. It is called during class building via the C<test> or C<with>
1460 function.
1461  
1462 B<Behavior:>
1463  
1464 =over 4
1465  
1466 =item * Same as C<ROLE> but also invokes C<AUDIT> hook
1467  
1468 =item * Allows roles to act as interfaces
1469  
1470 =back
1471  
1472 I<Since C<1.00>>
1473  
1474 =over 4
1475  
1476 =item test example 1
1477  
1478 package Admin;
1479  
1480 use base 'Venus::Core';
1481  
1482 package IsAdmin;
1483  
1484 use base 'Venus::Core';
1485  
1486 sub shutdown {
1487 return;
1488 }
1489  
1490 sub AUDIT {
1491 my ($self, $from) = @_;
1492 die "${from} is not a super-user" if !$from->DOES('Admin');
1493 }
1494  
1495 sub EXPORT {
1496 ['shutdown']
1497 }
1498  
1499 package User;
1500  
1501 use base 'Venus::Core';
1502  
1503 User->ROLE('Admin');
1504 User->TEST('IsAdmin'); # Will validate User->DOES('Admin')
1505  
1506 package main;
1507  
1508 my $user = User->BLESS; # OK
1509  
1510 =back
1511  
1512 =cut
1513  
1514 =item from
1515  
1516 FROM(string $name) (string | object)
1517  
1518 The FROM hook registers a base class and invokes its C<AUDIT> and C<IMPORT>
1519 hooks. It is called during class building via the C<from> function.
1520  
1521 B<Behavior:>
1522  
1523 =over 4
1524  
1525 =item * Registers inheritance
1526  
1527 =item * Automatically invokes C<AUDIT> hook for validation
1528  
1529 =item * Automatically invokes C<IMPORT> hook
1530  
1531 =back
1532  
1533 I<Since C<1.00>>
1534  
1535 =over 4
1536  
1537 =item from example 1
1538  
1539 package Entity;
1540  
1541 use base 'Venus::Core';
1542  
1543 sub AUDIT {
1544 my ($self, $from) = @_;
1545 die "Missing startup" if !$from->can('startup');
1546 die "Missing shutdown" if !$from->can('shutdown');
1547 }
1548  
1549 package User;
1550  
1551 use base 'Venus::Core';
1552  
1553 User->ATTR('startup');
1554 User->ATTR('shutdown');
1555  
1556 User->FROM('Entity'); # Will validate interface
1557  
1558 package main;
1559  
1560 my $user = User->BLESS; # OK
1561  
1562 =back
1563  
1564 =cut
1565  
1566 =back
1567  
1568 =head2 Interface and Validation Hooks
1569  
1570 =over 4
1571  
1572 =item audit
1573  
1574 AUDIT(string $role) (string | object)
1575  
1576 The AUDIT hook is an interface validation callback executed when a role is
1577 consumed via C<TEST> or C<FROM>. It is called when the consumer invokes C<TEST>
1578 or C<FROM> hooks. It receives the role itself and the consuming class name, and
1579 should die/throw if the interface contract is not satisfied.
1580  
1581 I<Since C<1.00>>
1582  
1583 =over 4
1584  
1585 =item audit example 1
1586  
1587 package HasType;
1588  
1589 use base 'Venus::Core';
1590  
1591 sub AUDIT {
1592 my ($self, $from) = @_;
1593 die 'Consumer missing "type" attribute' if !$from->can('type');
1594 }
1595  
1596 package User;
1597  
1598 use base 'Venus::Core';
1599  
1600 User->ATTR('type');
1601 User->TEST('HasType'); # OK: User has 'type'
1602  
1603 package Admin;
1604  
1605 use base 'Venus::Core';
1606  
1607 # Admin->TEST('HasType'); # Would die: Admin missing 'type'
1608  
1609 =back
1610  
1611 =cut
1612  
1613 =back
1614  
1615 =head2 Import/Export Hooks
1616  
1617 These hooks control what gets exported when roles/mixins are composed.
1618  
1619 =over 4
1620  
1621 =item export
1622  
1623 EXPORT(any @args) (arrayref)
1624  
1625 The EXPORT hook returns an arrayref of routine names to be automatically
1626 imported by consumers. It is called when a class is used via C<use>, or whenever
1627 C<import> is called, or during role/mixin composition via C<ROLE>, C<TEST>, or
1628 C<MIXIN> hooks. Only methods listed in EXPORT are copied to the consumer.
1629 B<Note:> By default, if no C<EXPORT> routine is declared, and if a package
1630 variable exists named `@EXPORT`, the package variable is used as the list of
1631 routines to be automatically exported.
1632  
1633 I<Since C<1.00>>
1634  
1635 =over 4
1636  
1637 =item export example 1
1638  
1639 package Admin;
1640  
1641 use base 'Venus::Core';
1642  
1643 sub shutdown {
1644 return;
1645 }
1646  
1647 sub restart {
1648 return;
1649 }
1650  
1651 sub EXPORT {
1652 ['shutdown'] # Only shutdown will be exported
1653 }
1654  
1655 package User;
1656  
1657 use base 'Venus::Core';
1658  
1659 User->ROLE('Admin');
1660  
1661 package main;
1662  
1663 my $user = User->BLESS;
1664 # $user->can('shutdown') is true
1665 # $user->can('restart') is false
1666  
1667 =back
1668  
1669 =cut
1670  
1671 =item import
1672  
1673 IMPORT(string $into, any @args) (string | object)
1674  
1675 The IMPORT hook dispatches the C<EXPORT> hook when roles/mixins are consumed. It
1676 is called when a class is used via C<use>, or whenever C<import> is called, or
1677 during role/mixin composition via C<ROLE>, C<TEST>, or C<MIXIN> hooks. Override
1678 this hook to track or customize the import process.
1679  
1680 I<Since C<1.00>>
1681  
1682 =over 4
1683  
1684 =item import example 1
1685  
1686 package Admin;
1687  
1688 use base 'Venus::Core';
1689  
1690 our $USES = 0;
1691  
1692 sub shutdown {
1693 return;
1694 }
1695  
1696 sub EXPORT {
1697 ['shutdown']
1698 }
1699  
1700 sub IMPORT {
1701 my ($self, $into) = @_;
1702  
1703 $self->SUPER::IMPORT($into);
1704  
1705 $USES++;
1706  
1707 return $self;
1708 }
1709  
1710 package User;
1711  
1712 use base 'Venus::Core';
1713  
1714 User->ROLE('Admin');
1715  
1716 package main;
1717  
1718 # $Admin::USES is now 1
1719  
1720 =back
1721  
1722 =cut
1723  
1724 =item use
1725  
1726 USE(string $into, any @args) (any)
1727  
1728 The USE hook is invoked when the Perl C<use> declaration is used. It is called
1729 during compilation when you C<use> a package.
1730  
1731 I<Since C<2.91>>
1732  
1733 =over 4
1734  
1735 =item use example 1
1736  
1737 package User;
1738  
1739 use base 'Venus::Core';
1740  
1741 package main;
1742  
1743 User->USE; # 'User'
1744  
1745 =back
1746  
1747 =cut
1748  
1749 =item unimport
1750  
1751 UNIMPORT(string $into, any @args) (any)
1752  
1753 The UNIMPORT hook is invoked when the Perl C<no> declaration is used. It is
1754 called when you C<no> a package.
1755  
1756 I<Since C<2.91>>
1757  
1758 =over 4
1759  
1760 =item unimport example 1
1761  
1762 package User;
1763  
1764 use base 'Venus::Core';
1765  
1766 package main;
1767  
1768 User->UNIMPORT; # 'User'
1769  
1770 =back
1771  
1772 =cut
1773  
1774 =back
1775  
1776 =head2 Instance Data Hooks
1777  
1778 These hooks control how instance data (attributes) are accessed and modified.
1779  
1780 =over 4
1781  
1782 =item get
1783  
1784 GET(string $name) (any)
1785  
1786 The GET hook is responsible for getting instance attribute values. By default,
1787 all attribute getters dispatch to this method. Override this hook to implement
1788 custom getter logic for all attributes.
1789  
1790 I<Since C<2.91>>
1791  
1792 =over 4
1793  
1794 =item get example 1
1795  
1796 package User;
1797  
1798 use base 'Venus::Core';
1799  
1800 User->ATTR('name');
1801  
1802 package main;
1803  
1804 my $user = User->BLESS(title => 'Engineer');
1805  
1806 my $value = $user->GET('title'); # "Engineer"
1807  
1808 =back
1809  
1810 =cut
1811  
1812 =item set
1813  
1814 SET(string $name, any @args) (any)
1815  
1816 The SET hook is responsible for setting instance attribute values. By default,
1817 all attribute setters dispatch to this method. Override this hook to implement
1818 custom setter logic for all attributes.
1819  
1820 I<Since C<2.91>>
1821  
1822 =over 4
1823  
1824 =item set example 1
1825  
1826 package User;
1827  
1828 use base 'Venus::Core';
1829  
1830 User->ATTR('name');
1831  
1832 package main;
1833  
1834 my $user = User->BLESS(title => 'Engineer');
1835  
1836 $user->SET('title', 'Manager'); # "Manager"
1837  
1838 =back
1839  
1840 =cut
1841  
1842 =item item
1843  
1844 ITEM(string $name, any @args) (string | object)
1845  
1846 The ITEM hook is responsible for both getting and setting instance attributes. By
1847 default, all attribute accessors dispatch to this method. Without extra args, it
1848 acts as a getter; with args, it acts as a setter.
1849  
1850 I<Since C<1.11>>
1851  
1852 =over 4
1853  
1854 =item item example 1
1855  
1856 package User;
1857  
1858 use base 'Venus::Core';
1859  
1860 User->ATTR('name');
1861  
1862 package main;
1863  
1864 my $user = User->BLESS;
1865  
1866 $user->ITEM('name', 'unknown'); # "unknown" (set)
1867 $user->ITEM('name'); # "unknown" (get)
1868  
1869 =back
1870  
1871 =cut
1872  
1873 =back
1874  
1875 =head2 Introspection Hooks
1876  
1877 These hooks provide information about the package/object structure.
1878  
1879 =over 4
1880  
1881 =item meta
1882  
1883 META() (Venus::Meta)
1884  
1885 The META hook returns a L<Venus::Meta> object describing the package
1886 configuration. It is called when you call C<meta> or C<META> on a class or
1887 instance.
1888  
1889 I<Since C<1.00>>
1890  
1891 =over 4
1892  
1893 =item meta example 1
1894  
1895 package User;
1896  
1897 use base 'Venus::Core';
1898  
1899 package main;
1900  
1901 my $meta = User->META;
1902 # bless({name => 'User'}, 'Venus::Meta')
1903  
1904 # Query the meta object
1905 $meta->attrs; # List attributes
1906 $meta->bases; # List base classes
1907 $meta->roles; # List consumed roles
1908 $meta->subs; # List methods
1909  
1910 =back
1911  
1912 =cut
1913  
1914 =item name
1915  
1916 NAME() (string)
1917  
1918 The NAME hook returns the name of the package. It is called whenever the package
1919 name is accessed via C<NAME>.
1920  
1921 I<Since C<1.00>>
1922  
1923 =over 4
1924  
1925 =item name example 1
1926  
1927 package User;
1928  
1929 use base 'Venus::Core';
1930  
1931 package main;
1932  
1933 my $name = User->NAME; # "User"
1934 my $user = User->BLESS;
1935 my $instance_name = $user->NAME; # "User"
1936  
1937 =back
1938  
1939 =cut
1940  
1941 =item does
1942  
1943 DOES(string $name) (boolean)
1944  
1945 The DOES hook returns true if the invocant consumed the specified role or mixin.
1946 It is called on-demand, typically to check role composition.
1947  
1948 I<Since C<1.00>>
1949  
1950 =over 4
1951  
1952 =item does example 1
1953  
1954 package Admin;
1955  
1956 use base 'Venus::Core';
1957  
1958 package User;
1959  
1960 use base 'Venus::Core';
1961  
1962 User->ROLE('Admin');
1963  
1964 package main;
1965  
1966 User->DOES('Admin'); # 1
1967 User->DOES('Owner'); # 0
1968  
1969 =back
1970  
1971 =cut
1972  
1973 =item subs
1974  
1975 SUBS() (arrayref)
1976  
1977 The SUBS hook returns the routines defined on the package and consumed from
1978 roles (excluding inherited methods). It is called on-demand, typically for
1979 introspection of available methods, whenever C<SUBS> is accessed.
1980  
1981 I<Since C<1.00>>
1982  
1983 =over 4
1984  
1985 =item subs example 1
1986  
1987 package Example;
1988  
1989 use base 'Venus::Core';
1990  
1991 sub custom_method {
1992 return;
1993 }
1994  
1995 package main;
1996  
1997 my $subs = Example->SUBS;
1998 # [...list of method names...]
1999  
2000 =back
2001  
2002 =cut
2003  
2004 =back
2005  
2006 =head2 Hook Execution Order
2007  
2008 Understanding the order in which hooks are executed is crucial for proper
2009 initialization.
2010  
2011 =head3 Class Building Phase
2012  
2013 =over 4
2014  
2015 =item 1. C<BASE> / C<FROM> - Register base classes
2016  
2017 C<FROM> also triggers: C<AUDIT> (from parent), C<IMPORT> (from parent)
2018  
2019 =item 2. C<ATTR> / C<MASK> - Define attributes
2020  
2021 =item 3. C<ROLE> / C<TEST> / C<MIXIN> - Compose roles/mixins
2022  
2023 C<ROLE> triggers: C<IMPORT> (from role)
2024  
2025 C<TEST> triggers: C<AUDIT> (from role), C<IMPORT> (from role)
2026  
2027 C<MIXIN> triggers: C<IMPORT> (from mixin)
2028  
2029 =back
2030  
2031 =head3 Object Construction Phase
2032  
2033 =over 4
2034  
2035 =item 1. C<BUILDARGS> - Pre-process constructor arguments
2036  
2037 =item 2. C<ARGS> - Convert arguments to blessable data structure
2038  
2039 =item 3. C<DATA> - Provide default data structure (if no args)
2040  
2041 =item 4. C<bless> - Perl's built-in blessing
2042  
2043 =item 5. C<BUILD> - Post-construction initialization
2044  
2045 =item 6. C<CONSTRUCT> - Additional post-construction setup
2046  
2047 =item 7. Return object to caller
2048  
2049 =back
2050  
2051 =head3 Object Destruction Phase
2052  
2053 =over 4
2054  
2055 =item 1. C<DECONSTRUCT> - Pre-destruction cleanup
2056  
2057 =item 2. C<DESTROY> - Final destruction
2058  
2059 =back
2060  
2061 =head3 Role/Mixin Composition Phase
2062  
2063 When a role/mixin is consumed:
2064  
2065 =over 4
2066  
2067 =item 1. Consumer calls C<ROLE> / C<TEST> / C<MIXIN>
2068  
2069 =item 2. If TEST or FROM: C<AUDIT> is called on the role/parent
2070  
2071 =item 3. C<IMPORT> is called on the role/mixin
2072  
2073 =item 4. C<EXPORT> is called to determine what to copy
2074  
2075 =item 5. Methods are copied according to composition rules
2076  
2077 =back
2078  
2079 =head2 Best Practices
2080  
2081 =head3 1. Always Return $self in BUILD
2082  
2083 sub BUILD {
2084 my ($self) = @_;
2085 # ... initialization ...
2086 return $self; # Always return $self
2087 }
2088  
2089 =head3 2. Call SUPER in Inherited BUILD
2090  
2091 sub BUILD {
2092 my ($self, $data) = @_;
2093 $self->SUPER::BUILD($data); # Call parent's BUILD
2094 # ... your initialization ...
2095 return $self;
2096 }
2097  
2098 =head3 3. Explicitly Declare EXPORT
2099  
2100 sub EXPORT {
2101 # Be explicit about what you export
2102 ['method1', 'method2']
2103 }
2104  
2105 =head3 4. Use AUDIT for Interface Enforcement
2106  
2107 sub AUDIT {
2108 my ($self, $from) = @_;
2109 die "Missing required method 'foo'" if !$from->can('foo');
2110 die "Missing required method 'bar'" if !$from->can('bar');
2111 }
2112  
2113 =head3 5. Use MASK for Encapsulation
2114  
2115 # Instead of documenting "don't use this attribute"
2116 # Use MASK to enforce it programmatically
2117 User->MASK('internal_cache');
2118  
2119 =head3 6. Keep BUILDARGS Simple
2120  
2121 sub BUILDARGS {
2122 my ($self, @args) = @_;
2123 # Simple transformations only
2124 # Complex logic goes in BUILD
2125 return @args == 1 && !ref $args[0] ? {id => $args[0]} : {@args};
2126 }
2127  
2128 =cut
2129  
2130 =head1 SUMMARY
2131  
2132 Venus provides a comprehensive set of lifecycle hooks organized into several
2133 categories:
2134  
2135 =over 4
2136  
2137 =item * B<Construction>: ARGS, BLESS, BUILDARGS, BUILD, CONSTRUCT, DATA, CLONE
2138  
2139 =item * B<Destruction>: DECONSTRUCT, DESTROY
2140  
2141 =item * B<Class Building>: ATTR, BASE, MASK
2142  
2143 =item * B<Composition>: ROLE, MIXIN, TEST, FROM
2144  
2145 =item * B<Validation>: AUDIT
2146  
2147 =item * B<Import/Export>: EXPORT, IMPORT, USE, UNIMPORT
2148  
2149 =item * B<Instance Data>: GET, SET, ITEM, STORE
2150  
2151 =item * B<Introspection>: META, METACACHE, NAME, DOES, SUBS
2152  
2153 =back
2154  
2155 These hooks provide fine-grained control over every aspect of object-oriented
2156 programming in Venus, from class construction to object lifecycle management.
2157  
2158 =cut
2159  
2160 =head1 AUTHORS
2161  
2162 Awncorp, C<awncorp@cpan.org>
2163  
2164 =cut
2165  
2166 =head1 LICENSE
2167  
2168 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
2169  
2170 This program is free software, you can redistribute it and/or modify it under
2171 the terms of the Apache license version 2.0.
2172  
2173 =cut
« blib/lib/Venus/Role/Encaseable.pm ↑ Summary blib/lib/Venus/Hash.pm »