blib/lib/Venus/Core.pm

filter: Statementstmt 100% 46 / 46 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod n/a totaltotal 100% 51 / 51 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« blib/lib/Venus/Role/Unpackable.pm ↑ Summary blib/lib/Venus/Float.pm »
1 package Venus::Core;
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 # IMPORTS
9  
10 120 ▶use Venus::Hook;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # METHODS
13  
14 {
15 120 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 120 *ARGS = *Venus::Hook::ARGS;
18  
19 120 *ATTR = *Venus::Hook::ATTR;
20  
21 120 *AUDIT = *Venus::Hook::AUDIT;
22  
23 120 *BASE = *Venus::Hook::BASE;
24  
25 120 *BLESS = *Venus::Hook::BLESS;
26  
27 120 *BUILD = *Venus::Hook::BUILD;
28  
29 120 *BUILDARGS = *Venus::Hook::BUILDARGS;
30  
31 120 *CONSTRUCT = *Venus::Hook::CONSTRUCT;
32  
33 120 *CLONE = *Venus::Hook::CLONE;
34  
35 120 *DATA = *Venus::Hook::DATA;
36  
37 120 *DECONSTRUCT = *Venus::Hook::DECONSTRUCT;
38  
39 120 *DESTROY = *Venus::Hook::DESTROY;
40  
41 120 *DOES = *Venus::Hook::DOES;
42  
43 120 *EXPORT = *Venus::Hook::EXPORT;
44  
45 120 *FROM = *Venus::Hook::FROM;
46  
47 120 *GET = *Venus::Hook::GET;
48  
49 120 *IMPORT = *Venus::Hook::IMPORT;
50  
51 120 *ITEM = *Venus::Hook::ITEM;
52  
53 120 *META = *Venus::Hook::META;
54  
55 120 *METACACHE = *Venus::Hook::METACACHE;
56  
57 120 *MIXIN = *Venus::Hook::MIXIN;
58  
59 120 *MASK = *Venus::Hook::MASK;
60  
61 120 *NAME = *Venus::Hook::NAME;
62  
63 120 *ROLE = *Venus::Hook::ROLE;
64  
65 120 *SET = *Venus::Hook::SET;
66  
67 120 *STORE = *Venus::Hook::STORE;
68  
69 120 *SUBS = *Venus::Hook::SUBS;
70  
71 120 *TEST = *Venus::Hook::TEST;
72  
73 120 *UNIMPORT = *Venus::Hook::UNIMPORT;
74  
75 120 *USE = *Venus::Hook::USE;
76 }
77  
78 120 1;
79  
80  
81  
82 =head1 NAME
83  
84 Venus::Core - Core Base Class
85  
86 =cut
87  
88 =head1 ABSTRACT
89  
90 Core Base Class for Perl 5
91  
92 =cut
93  
94 =head1 SYNOPSIS
95  
96 package User;
97  
98 use base 'Venus::Core';
99  
100 package main;
101  
102 my $user = User->BLESS(
103 fname => 'Elliot',
104 lname => 'Alderson',
105 );
106  
107 # bless({fname => 'Elliot', lname => 'Alderson'}, 'User')
108  
109 # i.e. BLESS is somewhat equivalent to writing
110  
111 # User->BUILD(bless(User->ARGS(User->BUILDARGS(@args) || User->DATA), 'User'))
112  
113 =cut
114  
115 =head1 DESCRIPTION
116  
117 This package provides a base class for L<"class"|Venus::Core::Class> and
118 L<"role"|Venus::Core::Role> (kind) derived packages and provides class building,
119 object construction, and object deconstruction lifecycle hooks. The
120 L<Venus::Class> and L<Venus::Role> packages provide a simple DSL for automating
121 L<Venus::Core> derived base classes.
122  
123 =cut
124  
125 =head1 METHODS
126  
127 This package provides the following methods:
128  
129 =cut
130  
131 =head2 args
132  
133 ARGS(any @args) (hashref)
134  
135 The ARGS method is a object construction lifecycle hook which accepts a list of
136 arguments and returns a blessable data structure.
137  
138 I<Since C<1.00>>
139  
140 =over 4
141  
142 =item args example 1
143  
144 # given: synopsis
145  
146 package main;
147  
148 my $args = User->ARGS;
149  
150 # {}
151  
152 =back
153  
154 =over 4
155  
156 =item args example 2
157  
158 # given: synopsis
159  
160 package main;
161  
162 my $args = User->ARGS(name => 'Elliot');
163  
164 # {name => 'Elliot'}
165  
166 =back
167  
168 =over 4
169  
170 =item args example 3
171  
172 # given: synopsis
173  
174 package main;
175  
176 my $args = User->ARGS({name => 'Elliot'});
177  
178 # {name => 'Elliot'}
179  
180 =back
181  
182 =cut
183  
184 =head2 attr
185  
186 ATTR(string $name, any @args) (string | object)
187  
188 The ATTR method is a class building lifecycle hook which installs an attribute
189 accessors in the calling package.
190  
191 I<Since C<1.00>>
192  
193 =over 4
194  
195 =item attr example 1
196  
197 package User;
198  
199 use base 'Venus::Core';
200  
201 User->ATTR('name');
202  
203 package main;
204  
205 my $user = User->BLESS;
206  
207 # bless({}, 'User')
208  
209 # $user->name;
210  
211 # ""
212  
213 # $user->name('Elliot');
214  
215 # "Elliot"
216  
217 =back
218  
219 =over 4
220  
221 =item attr example 2
222  
223 package User;
224  
225 use base 'Venus::Core';
226  
227 User->ATTR('role');
228  
229 package main;
230  
231 my $user = User->BLESS(role => 'Engineer');
232  
233 # bless({role => 'Engineer'}, 'User')
234  
235 # $user->role;
236  
237 # "Engineer"
238  
239 # $user->role('Hacker');
240  
241 # "Hacker"
242  
243 =back
244  
245 =cut
246  
247 =head2 audit
248  
249 AUDIT(string $role) (string | object)
250  
251 The AUDIT method is a class building lifecycle hook which exist in roles and is
252 executed as a callback when the consuming class invokes the L</TEST> hook.
253  
254 I<Since C<1.00>>
255  
256 =over 4
257  
258 =item audit example 1
259  
260 package HasType;
261  
262 use base 'Venus::Core';
263  
264 sub AUDIT {
265 die 'Consumer missing "type" attribute' if !$_[1]->can('type');
266 }
267  
268 package User;
269  
270 use base 'Venus::Core';
271  
272 User->TEST('HasType');
273  
274 package main;
275  
276 my $user = User->BLESS;
277  
278 # Exception! Consumer missing "type" attribute
279  
280 =back
281  
282 =over 4
283  
284 =item audit example 2
285  
286 package HasType;
287  
288 sub AUDIT {
289 die 'Consumer missing "type" attribute' if !$_[1]->can('type');
290 }
291  
292 package User;
293  
294 use base 'Venus::Core';
295  
296 User->ATTR('type');
297  
298 User->TEST('HasType');
299  
300 package main;
301  
302 my $user = User->BLESS;
303  
304 # bless({}, 'User')
305  
306 =back
307  
308 =cut
309  
310 =head2 base
311  
312 BASE(string $name) (string | object)
313  
314 The BASE method is a class building lifecycle hook which registers a base class
315 for the calling package. B<Note:> Unlike the L</FROM> hook, this hook doesn't
316 invoke the L</AUDIT> hook.
317  
318 I<Since C<1.00>>
319  
320 =over 4
321  
322 =item base example 1
323  
324 package Entity;
325  
326 sub work {
327 return;
328 }
329  
330 package User;
331  
332 use base 'Venus::Core';
333  
334 User->BASE('Entity');
335  
336 package main;
337  
338 my $user = User->BLESS;
339  
340 # bless({}, 'User')
341  
342 =back
343  
344 =over 4
345  
346 =item base example 2
347  
348 package Engineer;
349  
350 sub debug {
351 return;
352 }
353  
354 package Entity;
355  
356 sub work {
357 return;
358 }
359  
360 package User;
361  
362 use base 'Venus::Core';
363  
364 User->BASE('Entity');
365  
366 User->BASE('Engineer');
367  
368 package main;
369  
370 my $user = User->BLESS;
371  
372 # bless({}, 'User')
373  
374 =back
375  
376 =over 4
377  
378 =item base example 3
379  
380 package User;
381  
382 use base 'Venus::Core';
383  
384 User->BASE('Manager');
385  
386 # Exception! "Can't locate Manager.pm in @INC"
387  
388 =back
389  
390 =cut
391  
392 =head2 bless
393  
394 BLESS(any @args) (object)
395  
396 The BLESS method is an object construction lifecycle hook which returns an
397 instance of the calling package.
398  
399 I<Since C<1.00>>
400  
401 =over 4
402  
403 =item bless example 1
404  
405 package User;
406  
407 use base 'Venus::Core';
408  
409 package main;
410  
411 my $example = User->BLESS;
412  
413 # bless({}, 'User')
414  
415 =back
416  
417 =over 4
418  
419 =item bless example 2
420  
421 package User;
422  
423 use base 'Venus::Core';
424  
425 package main;
426  
427 my $example = User->BLESS(name => 'Elliot');
428  
429 # bless({name => 'Elliot'}, 'User')
430  
431 =back
432  
433 =over 4
434  
435 =item bless example 3
436  
437 package User;
438  
439 use base 'Venus::Core';
440  
441 package main;
442  
443 my $example = User->BLESS({name => 'Elliot'});
444  
445 # bless({name => 'Elliot'}, 'User')
446  
447 =back
448  
449 =over 4
450  
451 =item bless example 4
452  
453 package List;
454  
455 use base 'Venus::Core';
456  
457 sub ARGS {
458 my ($self, @args) = @_;
459  
460 return @args
461 ? ((@args == 1 && ref $args[0] eq 'ARRAY') ? @args : [@args])
462 : $self->DATA;
463 }
464  
465 sub DATA {
466 my ($self, $data) = @_;
467  
468 return $data ? [@$data] : [];
469 }
470  
471 package main;
472  
473 my $list = List->BLESS(1..4);
474  
475 # bless([1..4], 'List')
476  
477 =back
478  
479 =over 4
480  
481 =item bless example 5
482  
483 package List;
484  
485 use base 'Venus::Core';
486  
487 sub ARGS {
488 my ($self, @args) = @_;
489  
490 return @args
491 ? ((@args == 1 && ref $args[0] eq 'ARRAY') ? @args : [@args])
492 : $self->DATA;
493 }
494  
495 sub DATA {
496 my ($self, $data) = @_;
497  
498 return $data ? [@$data] : [];
499 }
500  
501 package main;
502  
503 my $list = List->BLESS([1..4]);
504  
505 # bless([1..4], 'List')
506  
507 =back
508  
509 =cut
510  
511 =head2 build
512  
513 BUILD(hashref $data) (object)
514  
515 The BUILD method is an object construction lifecycle hook which receives an
516 object and the data structure that was blessed, and should return an object
517 although its return value is ignored by the L</BLESS> hook.
518  
519 I<Since C<1.00>>
520  
521 =over 4
522  
523 =item build example 1
524  
525 package User;
526  
527 use base 'Venus::Core';
528  
529 sub BUILD {
530 my ($self) = @_;
531  
532 $self->{name} = 'Mr. Robot';
533  
534 return $self;
535 }
536  
537 package main;
538  
539 my $example = User->BLESS(name => 'Elliot');
540  
541 # bless({name => 'Mr. Robot'}, 'User')
542  
543 =back
544  
545 =over 4
546  
547 =item build example 2
548  
549 package User;
550  
551 use base 'Venus::Core';
552  
553 sub BUILD {
554 my ($self) = @_;
555  
556 $self->{name} = 'Mr. Robot';
557  
558 return $self;
559 }
560  
561 package Elliot;
562  
563 use base 'User';
564  
565 sub BUILD {
566 my ($self, $data) = @_;
567  
568 $self->SUPER::BUILD($data);
569  
570 $self->{name} = 'Elliot';
571  
572 return $self;
573 }
574  
575 package main;
576  
577 my $elliot = Elliot->BLESS;
578  
579 # bless({name => 'Elliot'}, 'Elliot')
580  
581 =back
582  
583 =cut
584  
585 =head2 buildargs
586  
587 BUILDARGS(any @args) (any @args | hashref $data)
588  
589 The BUILDARGS method is an object construction lifecycle hook which receives
590 the arguments provided to the constructor (unaltered) and should return a list
591 of arguments, a hashref, or key/value pairs.
592  
593 I<Since C<1.00>>
594  
595 =over 4
596  
597 =item buildargs example 1
598  
599 package User;
600  
601 use base 'Venus::Core';
602  
603 sub BUILD {
604 my ($self) = @_;
605  
606 return $self;
607 }
608  
609 sub BUILDARGS {
610 my ($self, @args) = @_;
611  
612 my $data = @args == 1 && !ref $args[0] ? {name => $args[0]} : {};
613  
614 return $data;
615 }
616  
617 package main;
618  
619 my $user = User->BLESS('Elliot');
620  
621 # bless({name => 'Elliot'}, 'User')
622  
623 =back
624  
625 =cut
626  
627 =head2 clone
628  
629 clone() (object)
630  
631 The CLONE method is an object construction lifecycle hook that returns a deep
632 clone of the invocant. The invocant must be blessed, meaning that the method
633 only applies to objects that are instances of a package. If the invocant is not
634 blessed, an exception will be raised. This method uses deep cloning to create
635 an independent copy of the object, including any private instance data, nested
636 structures or references within the object.
637  
638 I<Since C<4.15>>
639  
640 =over 4
641  
642 =item clone example 1
643  
644 package User;
645  
646 use base 'Venus::Core';
647  
648 package main;
649  
650 my $user = User->BLESS('Elliot');
651  
652 my $clone = $user->CLONE;
653  
654 # bless({name => 'Elliot'}, 'User')
655  
656 =back
657  
658 =over 4
659  
660 =item clone example 2
661  
662 package User;
663  
664 use base 'Venus::Core';
665  
666 package main;
667  
668 my $user = User->BLESS('Elliot');
669  
670 my $clone = User->CLONE;
671  
672 # Exception! "Can't clone without an instance of \"User\""
673  
674 =back
675  
676 =over 4
677  
678 =item clone example 3
679  
680 package User;
681  
682 use base 'Venus::Core';
683  
684 User->MASK('password');
685  
686 sub get_password {
687 my ($self) = @_;
688  
689 $self->password;
690 }
691  
692 sub set_password {
693 my ($self) = @_;
694  
695 $self->password('secret');
696 }
697  
698 package main;
699  
700 my $user = User->BLESS('Elliot');
701  
702 $user->set_password;
703  
704 my $clone = $user->CLONE;
705  
706 # bless({name => 'Elliot'}, 'User')
707  
708 =back
709  
710 =cut
711  
712 =head2 construct
713  
714 construct() (any)
715  
716 The CONSTRUCT method is an object construction lifecycle hook that is
717 automatically called after the L</BLESS> method, without any arguments. It is
718 intended to prepare the instance for usage, separate from the build process,
719 allowing for any setup or post-processing needed after the object has been
720 blessed. This method's return value is not used in any subsequent processing,
721 so its primary purpose is side effects or additional setup.
722  
723 I<Since C<4.15>>
724  
725 =over 4
726  
727 =item construct example 1
728  
729 package User;
730  
731 use base 'Venus::Core';
732  
733 sub CONSTRUCT {
734 my ($self) = @_;
735  
736 $self->{ready} = 1;
737  
738 return $self;
739 }
740  
741 package main;
742  
743 my $user = User->BLESS('Elliot');
744  
745 # bless({name => 'Elliot', ready => 1}, 'User')
746  
747 =back
748  
749 =cut
750  
751 =head2 data
752  
753 DATA() (Ref)
754  
755 The DATA method is an object construction lifecycle hook which returns the
756 default data structure reference to be blessed when no arguments are provided
757 to the constructor. The default data structure is an empty hashref.
758  
759 I<Since C<1.00>>
760  
761 =over 4
762  
763 =item data example 1
764  
765 package Example;
766  
767 use base 'Venus::Core';
768  
769 sub DATA {
770 return [];
771 }
772  
773 package main;
774  
775 my $example = Example->BLESS;
776  
777 # bless([], 'Example')
778  
779 =back
780  
781 =over 4
782  
783 =item data example 2
784  
785 package Example;
786  
787 use base 'Venus::Core';
788  
789 sub DATA {
790 return {};
791 }
792  
793 package main;
794  
795 my $example = Example->BLESS;
796  
797 # bless({}, 'Example')
798  
799 =back
800  
801 =cut
802  
803 =head2 deconstruct
804  
805 deconstruct() (any)
806  
807 The DECONSTRUCT method is an object destruction lifecycle hook that is called
808 just before the L</DESTROY> method. It provides an opportunity to perform any
809 necessary cleanup or resource release on the instance before it is destroyed.
810 This can include actions like disconnecting from external resources, clearing
811 caches, or logging. The method returns the instance, but its return value is
812 not used in subsequent processing.
813  
814 I<Since C<4.15>>
815  
816 =over 4
817  
818 =item deconstruct example 1
819  
820 package User;
821  
822 use base 'Venus::Core';
823  
824 our $CALLS = 0;
825  
826 our $USERS = 0;
827  
828 sub CONSTRUCT {
829 return $CALLS = $USERS += 1;
830 }
831  
832 sub DECONSTRUCT {
833 return $USERS--;
834 }
835  
836 package main;
837  
838 my $user;
839  
840 $user = User->BLESS('Elliot');
841  
842 $user = User->BLESS('Elliot');
843  
844 undef $user;
845  
846 # undef
847  
848 =back
849  
850 =cut
851  
852 =head2 destroy
853  
854 DESTROY() (any)
855  
856 The DESTROY method is an object destruction lifecycle hook which is called when
857 the last reference to the object goes away.
858  
859 I<Since C<1.00>>
860  
861 =over 4
862  
863 =item destroy example 1
864  
865 package User;
866  
867 use base 'Venus::Core';
868  
869 our $TRIES = 0;
870  
871 sub BUILD {
872 return $TRIES++;
873 }
874  
875 sub DESTROY {
876 return $TRIES--;
877 }
878  
879 package main;
880  
881 my $user = User->BLESS(name => 'Elliot');
882  
883 undef $user;
884  
885 # undef
886  
887 =back
888  
889 =cut
890  
891 =head2 does
892  
893 DOES(string $name) (boolean)
894  
895 The DOES method returns true or false if the invocant consumed the role or
896 interface provided.
897  
898 I<Since C<1.00>>
899  
900 =over 4
901  
902 =item does example 1
903  
904 package Admin;
905  
906 use base 'Venus::Core';
907  
908 package User;
909  
910 use base 'Venus::Core';
911  
912 User->ROLE('Admin');
913  
914 sub BUILD {
915 my ($self) = @_;
916  
917 return $self;
918 }
919  
920 sub BUILDARGS {
921 my ($self, @args) = @_;
922  
923 return (@args);
924 }
925  
926 package main;
927  
928 my $admin = User->DOES('Admin');
929  
930 # 1
931  
932 =back
933  
934 =over 4
935  
936 =item does example 2
937  
938 package Admin;
939  
940 use base 'Venus::Core';
941  
942 package User;
943  
944 use base 'Venus::Core';
945  
946 User->ROLE('Admin');
947  
948 sub BUILD {
949 my ($self) = @_;
950  
951 return $self;
952 }
953  
954 sub BUILDARGS {
955 my ($self, @args) = @_;
956  
957 return (@args);
958 }
959  
960 package main;
961  
962 my $is_owner = User->DOES('Owner');
963  
964 # 0
965  
966 =back
967  
968 =cut
969  
970 =head2 export
971  
972 EXPORT(any @args) (arrayref)
973  
974 The EXPORT method is a class building lifecycle hook which returns an arrayref
975 of routine names to be automatically imported by the calling package whenever
976 the L</ROLE> or L</TEST> hooks are used.
977  
978 I<Since C<1.00>>
979  
980 =over 4
981  
982 =item export example 1
983  
984 package Admin;
985  
986 use base 'Venus::Core';
987  
988 sub shutdown {
989 return;
990 }
991  
992 sub EXPORT {
993 ['shutdown']
994 }
995  
996 package User;
997  
998 use base 'Venus::Core';
999  
1000 User->ROLE('Admin');
1001  
1002 package main;
1003  
1004 my $user = User->BLESS;
1005  
1006 # bless({}, 'User')
1007  
1008 =back
1009  
1010 =cut
1011  
1012 =head2 from
1013  
1014 FROM(string $name) (string | object)
1015  
1016 The FROM method is a class building lifecycle hook which registers a base class
1017 for the calling package, automatically invoking the L</AUDIT> and L</IMPORT>
1018 hooks on the base class.
1019  
1020 I<Since C<1.00>>
1021  
1022 =over 4
1023  
1024 =item from example 1
1025  
1026 package Entity;
1027  
1028 use base 'Venus::Core';
1029  
1030 sub AUDIT {
1031 my ($self, $from) = @_;
1032 die "Missing startup" if !$from->can('startup');
1033 die "Missing shutdown" if !$from->can('shutdown');
1034 }
1035  
1036 package User;
1037  
1038 use base 'Venus::Core';
1039  
1040 User->ATTR('startup');
1041 User->ATTR('shutdown');
1042  
1043 User->FROM('Entity');
1044  
1045 package main;
1046  
1047 my $user = User->BLESS;
1048  
1049 # bless({}, 'User')
1050  
1051 =back
1052  
1053 =over 4
1054  
1055 =item from example 2
1056  
1057 package Entity;
1058  
1059 use base 'Venus::Core';
1060  
1061 sub AUDIT {
1062 my ($self, $from) = @_;
1063 die "Missing startup" if !$from->can('startup');
1064 die "Missing shutdown" if !$from->can('shutdown');
1065 }
1066  
1067 package User;
1068  
1069 use base 'Venus::Core';
1070  
1071 User->FROM('Entity');
1072  
1073 sub startup {
1074 return;
1075 }
1076  
1077 sub shutdown {
1078 return;
1079 }
1080  
1081 package main;
1082  
1083 my $user = User->BLESS;
1084  
1085 # bless({}, 'User')
1086  
1087 =back
1088  
1089 =cut
1090  
1091 =head2 get
1092  
1093 GET(string $name) (any)
1094  
1095 The GET method is a class instance lifecycle hook which is responsible for
1096 I<"getting"> instance items (or attribute values). By default, all class
1097 attributes I<"getters"> are dispatched to this method.
1098  
1099 I<Since C<2.91>>
1100  
1101 =over 4
1102  
1103 =item get example 1
1104  
1105 package User;
1106  
1107 use base 'Venus::Core';
1108  
1109 User->ATTR('name');
1110  
1111 package main;
1112  
1113 my $user = User->BLESS(title => 'Engineer');
1114  
1115 # bless({title => 'Engineer'}, 'User')
1116  
1117 my $get = $user->GET('title');
1118  
1119 # "Engineer"
1120  
1121 =back
1122  
1123 =cut
1124  
1125 =head2 import
1126  
1127 IMPORT(string $into, any @args) (string | object)
1128  
1129 The IMPORT method is a class building lifecycle hook which dispatches the
1130 L</EXPORT> lifecycle hook whenever the L</ROLE> or L</TEST> hooks are used.
1131  
1132 I<Since C<1.00>>
1133  
1134 =over 4
1135  
1136 =item import example 1
1137  
1138 package Admin;
1139  
1140 use base 'Venus::Core';
1141  
1142 our $USES = 0;
1143  
1144 sub shutdown {
1145 return;
1146 }
1147  
1148 sub EXPORT {
1149 ['shutdown']
1150 }
1151  
1152 sub IMPORT {
1153 my ($self, $into) = @_;
1154  
1155 $self->SUPER::IMPORT($into);
1156  
1157 $USES++;
1158  
1159 return $self;
1160 }
1161  
1162 package User;
1163  
1164 use base 'Venus::Core';
1165  
1166 User->ROLE('Admin');
1167  
1168 package main;
1169  
1170 my $user = User->BLESS;
1171  
1172 # bless({}, 'User')
1173  
1174 =back
1175  
1176 =cut
1177  
1178 =head2 item
1179  
1180 ITEM(string $name, any @args) (string | object)
1181  
1182 The ITEM method is a class instance lifecycle hook which is responsible for
1183 I<"getting"> and I<"setting"> instance items (or attributes). By default, all
1184 class attributes are dispatched to this method.
1185  
1186 I<Since C<1.11>>
1187  
1188 =over 4
1189  
1190 =item item example 1
1191  
1192 package User;
1193  
1194 use base 'Venus::Core';
1195  
1196 User->ATTR('name');
1197  
1198 package main;
1199  
1200 my $user = User->BLESS;
1201  
1202 # bless({}, 'User')
1203  
1204 my $item = $user->ITEM('name', 'unknown');
1205  
1206 # "unknown"
1207  
1208 =back
1209  
1210 =over 4
1211  
1212 =item item example 2
1213  
1214 package User;
1215  
1216 use base 'Venus::Core';
1217  
1218 User->ATTR('name');
1219  
1220 package main;
1221  
1222 my $user = User->BLESS;
1223  
1224 # bless({}, 'User')
1225  
1226 $user->ITEM('name', 'known');
1227  
1228 my $item = $user->ITEM('name');
1229  
1230 # "known"
1231  
1232 =back
1233  
1234 =cut
1235  
1236 =head2 mask
1237  
1238 mask(string $name, any @args) (string | object)
1239  
1240 The MASK method is a class-building lifecycle hook that installs private
1241 instance data accessors in the calling package. The accessor created allows
1242 private access to an instance variable, ensuring that it can only be accessed
1243 within the class or its subclasses. The method takes the name of the private
1244 variable as the first argument and any additional parameters needed for
1245 configuration. Attempting to access or set this variable outside of the class
1246 will raise an exception. This feature is useful for creating encapsulated
1247 attributes that maintain controlled visibility.
1248  
1249 I<Since C<4.15>>
1250  
1251 =over 4
1252  
1253 =item mask example 1
1254  
1255 package User;
1256  
1257 use base 'Venus::Core';
1258  
1259 User->MASK('password');
1260  
1261 package main;
1262  
1263 my $user = User->BLESS(name => 'Elliot');
1264  
1265 $user->password;
1266  
1267 # Exception! "Can't get/set private variable \"password\" outside the class or subclass of \"User\""
1268  
1269 =back
1270  
1271 =over 4
1272  
1273 =item mask example 2
1274  
1275 package User;
1276  
1277 use base 'Venus::Core';
1278  
1279 User->MASK('password');
1280  
1281 package main;
1282  
1283 my $user = User->BLESS(name => 'Elliot');
1284  
1285 User->password;
1286  
1287 # Exception! "Can't get/set private variable \"password\" without an instance of \"User\""
1288  
1289 =back
1290  
1291 =over 4
1292  
1293 =item mask example 3
1294  
1295 package User;
1296  
1297 use base 'Venus::Core';
1298  
1299 User->MASK('password');
1300  
1301 sub get_password {
1302 my ($self) = @_;
1303  
1304 $self->password;
1305 }
1306  
1307 sub set_password {
1308 my ($self) = @_;
1309  
1310 $self->password('secret');
1311 }
1312  
1313 package main;
1314  
1315 my $user = User->BLESS(name => 'Elliot');
1316  
1317 $user->set_password;
1318  
1319 # "secret"
1320  
1321 $user;
1322  
1323 # bless({name => 'Elliot'}, 'User')
1324  
1325 =back
1326  
1327 =cut
1328  
1329 =head2 meta
1330  
1331 META() (Venus::Meta)
1332  
1333 The META method return a L<Venus::Meta> object which describes the invocant's
1334 configuration.
1335  
1336 I<Since C<1.00>>
1337  
1338 =over 4
1339  
1340 =item meta example 1
1341  
1342 package User;
1343  
1344 use base 'Venus::Core';
1345  
1346 package main;
1347  
1348 my $meta = User->META;
1349  
1350 # bless({name => 'User'}, 'Venus::Meta')
1351  
1352 =back
1353  
1354 =cut
1355  
1356 =head2 mixin
1357  
1358 MIXIN(string $name) (string | object)
1359  
1360 The MIXIN method is a class building lifecycle hook which consumes the mixin
1361 provided, automatically invoking the mixin's L</IMPORT> hook. The role
1362 composition semantics are as follows: Routines to be consumed must be
1363 explicitly declared via the L</EXPORT> hook. Routines will be copied to the
1364 consumer even if they already exist. If multiple roles are consumed having
1365 routines with the same name (i.e. naming collisions) the last routine copied
1366 wins.
1367  
1368 I<Since C<1.02>>
1369  
1370 =over 4
1371  
1372 =item mixin example 1
1373  
1374 package Action;
1375  
1376 use base 'Venus::Core';
1377  
1378 package User;
1379  
1380 use base 'Venus::Core';
1381  
1382 User->MIXIN('Action');
1383  
1384 package main;
1385  
1386 my $admin = User->DOES('Action');
1387  
1388 # 0
1389  
1390 =back
1391  
1392 =cut
1393  
1394 =head2 name
1395  
1396 NAME() (string)
1397  
1398 The NAME method is a class building lifecycle hook which returns the name of
1399 the package.
1400  
1401 I<Since C<1.00>>
1402  
1403 =over 4
1404  
1405 =item name example 1
1406  
1407 package User;
1408  
1409 use base 'Venus::Core';
1410  
1411 package main;
1412  
1413 my $name = User->NAME;
1414  
1415 # "User"
1416  
1417 =back
1418  
1419 =over 4
1420  
1421 =item name example 2
1422  
1423 package User;
1424  
1425 use base 'Venus::Core';
1426  
1427 package main;
1428  
1429 my $name = User->BLESS->NAME;
1430  
1431 # "User"
1432  
1433 =back
1434  
1435 =cut
1436  
1437 =head2 role
1438  
1439 ROLE(string $name) (string | object)
1440  
1441 The ROLE method is a class building lifecycle hook which consumes the role
1442 provided, automatically invoking the role's L</IMPORT> hook. B<Note:> Unlike
1443 the L</TEST> and L</WITH> hooks, this hook doesn't invoke the L</AUDIT> hook.
1444 The role composition semantics are as follows: Routines to be consumed must be
1445 explicitly declared via the L</EXPORT> hook. Routines will be copied to the
1446 consumer unless they already exist (excluding routines from base classes, which
1447 will be overridden). If multiple roles are consumed having routines with the
1448 same name (i.e. naming collisions) the first routine copied wins.
1449  
1450 I<Since C<1.00>>
1451  
1452 =over 4
1453  
1454 =item role example 1
1455  
1456 package Admin;
1457  
1458 use base 'Venus::Core';
1459  
1460 package User;
1461  
1462 use base 'Venus::Core';
1463  
1464 User->ROLE('Admin');
1465  
1466 package main;
1467  
1468 my $admin = User->DOES('Admin');
1469  
1470 # 1
1471  
1472 =back
1473  
1474 =over 4
1475  
1476 =item role example 2
1477  
1478 package Create;
1479  
1480 use base 'Venus::Core';
1481  
1482 package Delete;
1483  
1484 use base 'Venus::Core';
1485  
1486 package Manage;
1487  
1488 use base 'Venus::Core';
1489  
1490 Manage->ROLE('Create');
1491 Manage->ROLE('Delete');
1492  
1493 package User;
1494  
1495 use base 'Venus::Core';
1496  
1497 User->ROLE('Manage');
1498  
1499 package main;
1500  
1501 my $create = User->DOES('Create');
1502  
1503 # 1
1504  
1505 =back
1506  
1507 =cut
1508  
1509 =head2 set
1510  
1511 SET(string $name, any @args) (any)
1512  
1513 The SET method is a class instance lifecycle hook which is responsible for
1514 I<"setting"> instance items (or attribute values). By default, all class
1515 attributes I<"setters"> are dispatched to this method.
1516  
1517 I<Since C<2.91>>
1518  
1519 =over 4
1520  
1521 =item set example 1
1522  
1523 package User;
1524  
1525 use base 'Venus::Core';
1526  
1527 User->ATTR('name');
1528  
1529 package main;
1530  
1531 my $user = User->BLESS(title => 'Engineer');
1532  
1533 # bless({title => 'Engineer'}, 'User')
1534  
1535 my $set = $user->SET('title', 'Manager');
1536  
1537 # "Manager"
1538  
1539 =back
1540  
1541 =cut
1542  
1543 =head2 subs
1544  
1545 SUBS() (arrayref)
1546  
1547 The SUBS method returns the routines defined on the package and consumed from
1548 roles, but not inherited by superclasses.
1549  
1550 I<Since C<1.00>>
1551  
1552 =over 4
1553  
1554 =item subs example 1
1555  
1556 package Example;
1557  
1558 use base 'Venus::Core';
1559  
1560 package main;
1561  
1562 my $subs = Example->SUBS;
1563  
1564 # [...]
1565  
1566 =back
1567  
1568 =cut
1569  
1570 =head2 test
1571  
1572 TEST(string $name) (string | object)
1573  
1574 The TEST method is a class building lifecycle hook which consumes the role
1575 provided, automatically invoking the role's L</IMPORT> hook as well as the
1576 L</AUDIT> hook if defined.
1577  
1578 I<Since C<1.00>>
1579  
1580 =over 4
1581  
1582 =item test example 1
1583  
1584 package Admin;
1585  
1586 use base 'Venus::Core';
1587  
1588 package IsAdmin;
1589  
1590 use base 'Venus::Core';
1591  
1592 sub shutdown {
1593 return;
1594 }
1595  
1596 sub AUDIT {
1597 my ($self, $from) = @_;
1598 die "${from} is not a super-user" if !$from->DOES('Admin');
1599 }
1600  
1601 sub EXPORT {
1602 ['shutdown']
1603 }
1604  
1605 package User;
1606  
1607 use base 'Venus::Core';
1608  
1609 User->ROLE('Admin');
1610  
1611 User->TEST('IsAdmin');
1612  
1613 package main;
1614  
1615 my $user = User->BLESS;
1616  
1617 # bless({}, 'User')
1618  
1619 =back
1620  
1621 =cut
1622  
1623 =head2 unimport
1624  
1625 UNIMPORT(string $into, any @args) (any)
1626  
1627 The UNIMPORT method is a class building lifecycle hook which is invoked
1628 whenever the L<perlfunc/no> declaration is used.
1629  
1630 I<Since C<2.91>>
1631  
1632 =over 4
1633  
1634 =item unimport example 1
1635  
1636 package User;
1637  
1638 use base 'Venus::Core';
1639  
1640 package main;
1641  
1642 User->UNIMPORT;
1643  
1644 # 'User'
1645  
1646 =back
1647  
1648 =cut
1649  
1650 =head2 use
1651  
1652 USE(string $into, any @args) (any)
1653  
1654 The USE method is a class building lifecycle hook which is invoked
1655 whenever the L<perlfunc/use> declaration is used.
1656  
1657 I<Since C<2.91>>
1658  
1659 =over 4
1660  
1661 =item use example 1
1662  
1663 package User;
1664  
1665 use base 'Venus::Core';
1666  
1667 package main;
1668  
1669 User->USE;
1670  
1671 # 'User'
1672  
1673 =back
1674  
1675 =cut
1676  
1677 =head1 AUTHORS
1678  
1679 Awncorp, C<awncorp@cpan.org>
1680  
1681 =cut
1682  
1683 =head1 LICENSE
1684  
1685 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
1686  
1687 This program is free software, you can redistribute it and/or modify it under
1688 the terms of the Apache license version 2.0.
1689  
1690 =cut
« blib/lib/Venus/Role/Unpackable.pm ↑ Summary blib/lib/Venus/Float.pm »