blib/lib/Venus/Role/Optional.pm

filter: Statementstmt 90.7% 177 / 195 Branchbran 84.6% 83 / 98 Conditioncond 73.3% 33 / 45 MC/DCmcdc 59.2% 16 / 27 Subroutinesub 100% 28 / 28 Podpod 14.2% 3 / 21 totaltotal 82.1% 340 / 414 CC 66 SCAR 16.6
CC
66
Cov
87%
option_assert
15.0
option_coerce
9.1
option_self_coerce
6.1
CRAP 5.3
« blib/lib/Venus/Gather.pm ↑ Summary blib/lib/Venus/Meta.pm »
1 package Venus::Role::Optional;
2  
3 4 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 4 ▶use Venus::Role 'catch', 'error', 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # BUILDERS
13  
14 95 ▶sub BUILD {
Subroutine BUILD: called CC=6 SCAR=17.9
Pod undocumented
15 95 my ($self, $data) = @_;
16  
17 95 for my $name (@{$self->META->attrs}) {
18 298 ▶ my @data = (exists $data->{$name} ? $data->{$name} : ());
Branch: 1 branch
BranchTrueFalseTotal
exists $data->{$name} ? : 81 217 298
19  
20 # option: default
21 298 option_default($self, $name, @data);
22  
23 # option: initial
24 298 option_initial($self, $name, @data);
25  
26 # option: require
27 298 option_require($self, $name, @data);
28  
29 # option: build
30 296 ▶ @data = option_builder($self, $name, @data) if exists $data->{$name};
Branch: 1 branch
BranchTrueFalseTotal
if exists $data->{$name} 265 31 296
31  
32 # option: coerce
33 296 ▶ @data = option_coerce($self, $name, @data) if exists $data->{$name};
Branch: 1 branch
BranchTrueFalseTotal
if exists $data->{$name} 265 31 296
34  
35 # option: self-coerce
36 296 ▶ @data = option_self_coerce($self, $name, @data) if exists $data->{$name};
Branch: 1 branch
BranchTrueFalseTotal
if exists $data->{$name} 265 31 296
37  
38 # option: check
39 296 option_check($self, $name, @data);
40  
41 # option: self-assert
42 296 option_self_assert($self, $name, @data);
43  
44 # option: assert
45 293 option_assert($self, $name, @data);
46 }
47  
48 87 return $self;
49 }
50  
51 # METHODS
52  
53 8 ▶sub clear {
Subroutine clear: called CC=2 SCAR=7.1
Pod documented
54 8 my ($self, $name) = @_;
55  
56 8 ▶ return if !$name;
Branch: 1 branch
BranchTrueFalseTotal
unless $name 0 8 8
57  
58 8 return delete $self->{$name};
59 }
60  
61 2 ▶sub has {
Subroutine has: called CC=3 SCAR=11.1
Pod documented
62 2 my ($self, $name) = @_;
63  
64 2 ▶ return if !$name;
Branch: 1 branch
BranchTrueFalseTotal
unless $name 0 2 2
65  
66 2 ▶ return exists $self->{$name} ? true : false;
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{$name} ? : 1 1 2
67 }
68  
69 5 ▶sub reset {
Subroutine reset: called CC=3 SCAR=11.8
Pod documented
70 5 my ($self, $name, @data) = @_;
71  
72 5 ▶ return if !$name || !$self->can($name);
Branch: 1 branch
BranchTrueFalseTotal
unless $name and $self->can($name) 0 5 5
Condition33%1/3
$name and $self->can($name)
!ll&&!rl&&r
005
MC/DC0%0/2
$name and $self->can($name)
$name $self->can($name)
Truth table33%1/3
A and B
A= $nameB= $self->can($name)
ABresult
0X0
100
111
73  
74 5 my $value = $self->clear($name);
75  
76 5 $self->$name(@data);
77  
78 5 return $value;
79 }
80  
81 # EXTENSIONS
82  
83 938 ▶sub ITEM {
Subroutine ITEM: called CC=3 SCAR=11.0
Pod undocumented
84 938 my ($self, $name, @data) = @_;
85  
86 938 my $value;
87  
88 938 ▶ return undef if !$name;
Branch: 1 branch
BranchTrueFalseTotal
unless $name 0 938 938
89  
90 938 ▶ @data = (!@data ? READ($self, $name, @data) : WRITE($self, $name, @data));
Branch: 1 branch
BranchTrueFalseTotal
!@data ? : 920 18 938
91  
92 # option: check
93 936 option_check($self, $name, @data);
94  
95 # option: self-assert
96 935 option_self_assert($self, $name, @data);
97  
98 # option: assert
99 935 option_assert($self, $name, @data);
100  
101 # option: trigger
102 935 option_trigger($self, $name, @data);
103  
104 935 return $data[0];
105 }
106  
107 920 ▶sub READ {
Subroutine READ: called CC=1 SCAR=0.0
108 920 my ($self, $name, @data) = @_;
109  
110 # option: default
111 920 option_default($self, $name, @data);
112  
113 # option: builder
114 920 option_builder($self, $name, @data);
115  
116 # option: lazy-builder
117 920 option_lazy_builder($self, $name, @data);
118  
119 # option: coerce
120 920 option_coerce($self, $name, @data);
121  
122 # option: self-coerce
123 920 option_self_coerce($self, $name, @data);
124  
125 # option: reader
126 920 return option_reader($self, $name, @data);
127 }
128  
129 18 ▶sub WRITE {
Subroutine WRITE: called CC=1 SCAR=0.0
130 18 my ($self, $name, @data) = @_;
131  
132 # option: readwrite
133 18 option_readwrite($self, $name, @data);
134  
135 # option: readonly
136 17 option_readonly($self, $name, @data);
137  
138 # option: builder
139 16 @data = option_builder($self, $name, @data);
140  
141 # option: lazy-builder
142 16 @data = option_lazy_builder($self, $name, @data);
143  
144 # option: coerce
145 16 @data = option_coerce($self, $name, @data);
146  
147 # option: self-coerce
148 16 @data = option_self_coerce($self, $name, @data);
149  
150 # option: writer
151 16 return option_writer($self, $name, @data);
152 }
153  
154 # EXPORTS
155  
156 44 ▶sub EXPORT {
Subroutine EXPORT: called CC=1 SCAR=0.0
Pod undocumented
157 44 ['clear', 'has', 'ITEM', 'reset']
158 }
159  
160 # OPTIONS
161  
162 1228 ▶sub option_assert {
Subroutine option_assert: called CC=7 SCAR=27.0
Pod undocumented
163 1228 my ($self, $name, @data) = @_;
164  
165 1228 ▶ if ((my $code = $self->can("assert_${name}")) && @data) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("assert_$name") and @data) 12 1216 1228
Condition66%2/3
my $code = $self->can("assert_$name") and @data
!ll&&!rl&&r
1216012
MC/DC50%1/2
my $code = $self->can("assert_$name") and @data
my $code = $self->can("assert_$name") @data
Truth table66%2/3
A and B
A= my $code = $self->can("assert_$name")B= @data
ABresult
0X0
100
111
166 12 require Scalar::Util;
167 12 require Venus::Assert;
168 12 my $from = ref $self;
169 12 my $label = qq(attribute "$name" in $from);
170 12 my $assert = Venus::Assert->new($label);
171 12 ▶ my $value = @data ? $data[0] : $self->{$name};
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 12 0 12
172 12 my $return = $code->($self, $value, $assert);
173 12 ▶ if (Scalar::Util::blessed($return)) {
Branch: 2 branches
BranchTrueFalseTotal
if (builtin::blessed($return)) { } 0 12 12
elsif (length $return) { } 12 0 12
174 0 ▶ if ($return->isa('Venus::Assert')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($return->isa('Venus::Assert')) { } 0 0 0
175 0 $return->validate($value);
176 }
177 else {
178 0 require Venus::Throw;
179 0 my $throw = Venus::Throw->new(join('::', map ucfirst, ref($self), 'error'));
180 0 $throw->name('on.assert');
181 0 $throw->message("Invalid return value: \"assert_$name\" in $self");
182 0 $throw->stash(data => $value);
183 0 $throw->stash(name => $name);
184 0 $throw->stash(self => $self);
185 0 $throw->die;
186 }
187 }
188 elsif (length($return)) {
189 12 $assert->name($label);
190 12 $assert->expression($return)->validate($value);
191 }
192 else {
193 0 require Venus::Throw;
194 0 my $throw = Venus::Throw->new(join('::', map ucfirst, ref($self), 'error'));
195 0 $throw->name('on.assert');
196 0 $throw->message("Invalid return value: \"assert_$name\" in $self");
197 0 $throw->stash(data => $value);
198 0 $throw->stash(name => $name);
199 0 $throw->stash(self => $self);
200 0 $throw->die;
201 }
202 }
203 1225 return;
204 }
205  
206 1201 ▶sub option_builder {
Subroutine option_builder: called CC=5 SCAR=16.1
Pod undocumented
207 1201 my ($self, $name, @data) = @_;
208  
209 1201 ▶ if (my $code = $self->can("build_${name}")) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("build_$name")) 24 1177 1201
210 24 ▶ my @return = $code->($self, (@data ? @data : $self->{$name}));
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 8 16 24
211 24 ▶ $self->{$name} = $return[0] if @return;
Branch: 1 branch
BranchTrueFalseTotal
if @return 24 0 24
212 }
213 1201 ▶ return @data ? $data[0] : ();
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 97 1104 1201
214 }
215  
216 1232 ▶sub option_check {
Subroutine option_check: called CC=4 SCAR=13.9
Pod undocumented
217 1232 my ($self, $name, @data) = @_;
218  
219 1232 ▶ if ((my $code = $self->can("check_${name}")) && @data) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("check_$name") and @data) 8 1224 1232
Condition66%2/3
my $code = $self->can("check_$name") and @data
!ll&&!rl&&r
122408
MC/DC50%1/2
my $code = $self->can("check_$name") and @data
my $code = $self->can("check_$name") @data
Truth table66%2/3
A and B
A= my $code = $self->can("check_$name")B= @data
ABresult
0X0
100
111
220 8 require Venus::Throw;
221 8 my $throw = Venus::Throw->new(join('::', map ucfirst, ref($self), 'error'));
222 8 $throw->name('on.check');
223 8 $throw->message("Checking attribute value failed: \"$name\" in $self");
224 8 $throw->stash(data => [@data]);
225 8 $throw->stash(name => $name);
226 8 $throw->stash(self => $self);
227 8 ▶ if (!$code->($self, @data)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (&$code($self, @data)) 1 7 8
228 1 $throw->die;
229 }
230 }
231 1231 return;
232 }
233  
234 1201 ▶sub option_coerce {
Subroutine option_coerce: called CC=9 SCAR=22.1
Pod undocumented
235 1201 my ($self, $name, @data) = @_;
236  
237 1201 ▶ if ((my $code = $self->can("coerce_${name}")) && (@data || exists $self->{$name})) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("coerce_$name") and @data || exists $self->{$name}) 24 1177 1201
Condition100%6/6
my $code = $self->can("coerce_$name") and @data || exists $self->{$name}
!ll&&!rl&&r
1174324
@data or exists $self->{$name}
l!l&&r!l&&!r
6183
MC/DC100%3/3
my $code = $self->can("coerce_$name") and @data || exists $self->{$name}
my $code = $self->can("coerce_$name") @data exists $self->{$name}
Truth table100%4/4
A and B or C
A= my $code = $self->can("coerce_$name")B= @dataC= exists $self->{$name}
ABCresult
0XX0
1000
11X1
1011
238 24 require Scalar::Util;
239 24 require Venus::Space;
240 24 ▶ my $value = @data ? $data[0] : $self->{$name};
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 6 18 24
241 24 my $return = $code->($self, @data);
242 24 my $package = Venus::Space->new($return)->load;
243 24 my $method = 'new';
244 24 ▶ return $self->{$name} = $package->$method($value)
Branch: 1 branch
BranchTrueFalseTotal
if not builtin::blessed($value) or builtin::blessed($value) and not $value->isa($return) 15 9 24
Condition50%3/6
not builtin::blessed($value) or builtin::blessed($value) and not $value->isa($return)
l!l&&r!l&&!r
1509
builtin::blessed($value) and not $value->isa($return)
!ll&&!rl&&r
090
MC/DC33%1/3
not builtin::blessed($value) or builtin::blessed($value) and not $value->isa($return)
not builtin::blessed($value) builtin::blessed($value) not $value->isa($return)
Truth table50%2/4
not(A) or B and not(C)
A= not builtin::blessed($value)B= builtin::blessed($value)C= not $value->isa($return)
ABCresult
1XX1
0111
00X0
0100
245 if !Scalar::Util::blessed($value)
246 || (Scalar::Util::blessed($value) && !$value->isa($return));
247 }
248 1186 ▶ return @data ? $data[0] : ();
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 91 1095 1186
249 }
250  
251 1218 ▶sub option_default {
Subroutine option_default: called CC=4 SCAR=13.9
Pod undocumented
252 1218 my ($self, $name, @data) = @_;
253  
254 1218 ▶ if ((my $code = $self->can("default_${name}")) && !@data) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("default_$name") and not @data) 1046 172 1218
Condition100%3/3
my $code = $self->can("default_$name") and not @data
!ll&&!rl&&r
154181046
MC/DC100%2/2
my $code = $self->can("default_$name") and not @data
my $code = $self->can("default_$name") not @data
Truth table100%3/3
A and not(B)
A= my $code = $self->can("default_$name")B= not @data
ABresult
0X0
100
111
255 1046 ▶ $self->{$name} = $code->($self, @data) if !exists $self->{$name};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{$name} 184 862 1046
256 }
257 1218 return;
258 }
259  
260 298 ▶sub option_initial {
Subroutine option_initial: called CC=2 SCAR=6.9
Pod undocumented
261 298 my ($self, $name, @data) = @_;
262  
263 298 ▶ if ((my $code = $self->can("initial_${name}"))) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("initial_$name")) 1 297 298
264 1 $self->{$name} = $code->($self, @data);
265 }
266 298 return;
267 }
268  
269 936 ▶sub option_lazy_builder {
Subroutine option_lazy_builder: called CC=5 SCAR=16.3
Pod undocumented
270 936 my ($self, $name, @data) = @_;
271  
272 936 ▶ if (my $code = $self->can("lazy_build_${name}")) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("lazy_build_$name")) 4 932 936
273 4 ▶ my @return = $code->($self, (@data ? @data : $self->{$name}));
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 0 4 4
274 4 ▶ $self->{$name} = $return[0] if @return;
Branch: 1 branch
BranchTrueFalseTotal
if @return 4 0 4
275 }
276 936 ▶ return @data ? $data[0] : ();
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 16 920 936
277 }
278  
279 920 ▶sub option_reader {
Subroutine option_reader: called CC=3 SCAR=11.0
Pod undocumented
280 920 my ($self, $name, @data) = @_;
281  
282 920 ▶ if ((my $code = $self->can("read_${name}")) && !@data) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("read_$name") and not @data) { } 2 918 920
Condition66%2/3
my $code = $self->can("read_$name") and not @data
!ll&&!rl&&r
91802
MC/DC50%1/2
my $code = $self->can("read_$name") and not @data
my $code = $self->can("read_$name") not @data
Truth table66%2/3
A and not(B)
A= my $code = $self->can("read_$name")B= not @data
ABresult
0X0
100
111
283 2 return $code->($self, @data);
284 }
285 else {
286 918 return $self->{$name};
287 }
288 }
289  
290 17 ▶sub option_readonly {
Subroutine option_readonly: called CC=4 SCAR=13.9
Pod undocumented
291 17 my ($self, $name, @data) = @_;
292  
293 17 ▶ if (my $code = ($self->can("readonly_${name}") || $self->can("readonly"))) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("readonly_$name") || $self->can("readonly")) 1 16 17
Condition66%2/3
$self->can("readonly_$name") || $self->can('readonly')
l!l&&r!l&&!r
1016
MC/DC50%1/2
$self->can("readonly_$name") || $self->can('readonly')
$self->can("readonly_$name") $self->can('readonly')
Truth table66%2/3
A || B
A= $self->can("readonly_$name")B= $self->can('readonly')
ABresult
1X1
011
000
294 1 require Venus::Throw;
295 1 my $throw = Venus::Throw->new(join('::', map ucfirst, ref($self), 'error'));
296 1 $throw->name('on.readonly');
297 1 $throw->message("Setting read-only attribute: \"$name\" in $self");
298 1 $throw->stash(data => $data[0]);
299 1 $throw->stash(name => $name);
300 1 $throw->stash(self => $self);
301 1 ▶ if ($code->($self, @data)) {
Branch: 1 branch
BranchTrueFalseTotal
if (&$code($self, @data)) 1 0 1
302 1 $throw->die;
303 }
304 }
305 16 return;
306 }
307  
308 18 ▶sub option_readwrite {
Subroutine option_readwrite: called CC=4 SCAR=13.9
Pod undocumented
309 18 my ($self, $name, @data) = @_;
310  
311 18 ▶ if (my $code = ($self->can("readwrite_${name}") || $self->can("readwrite"))) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("readwrite_$name") || $self->can("readwrite")) 1 17 18
Condition66%2/3
$self->can("readwrite_$name") || $self->can('readwrite')
l!l&&r!l&&!r
1017
MC/DC50%1/2
$self->can("readwrite_$name") || $self->can('readwrite')
$self->can("readwrite_$name") $self->can('readwrite')
Truth table66%2/3
A || B
A= $self->can("readwrite_$name")B= $self->can('readwrite')
ABresult
1X1
011
000
312 1 require Venus::Throw;
313 1 my $throw = Venus::Throw->new(join('::', map ucfirst, ref($self), 'error'));
314 1 $throw->name('on.readwrite');
315 1 $throw->message("Setting read-only attribute: \"$name\" in $self");
316 1 $throw->stash(data => $data[0]);
317 1 $throw->stash(name => $name);
318 1 $throw->stash(self => $self);
319 1 ▶ if (!$code->($self, @data)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (&$code($self, @data)) 1 0 1
320 1 $throw->die;
321 }
322 }
323 17 return;
324 }
325  
326 298 ▶sub option_require {
Subroutine option_require: called CC=4 SCAR=13.9
Pod undocumented
327 298 my ($self, $name, @data) = @_;
328  
329 298 ▶ if (my $code = $self->can("require_${name}")) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("require_$name")) 6 292 298
330 6 require Venus::Throw;
331 6 my $throw = Venus::Throw->new(join('::', map ucfirst, ref($self), 'error'));
332 6 $throw->name('on.require');
333 6 $throw->message("Missing required attribute: \"$name\" in $self");
334 6 $throw->stash(data => [@data]);
335 6 $throw->stash(name => $name);
336 6 $throw->stash(self => $self);
337 6 ▶ if ($code->($self, @data) && !@data) {
Branch: 1 branch
BranchTrueFalseTotal
if (&$code($self, @data) and not @data) 2 4 6
Condition100%3/3
&$code($self, @data) and not @data
!ll&&!rl&&r
132
MC/DC100%2/2
&$code($self, @data) and not @data
&$code($self, @data) not @data
Truth table100%3/3
A and not(B)
A= &$code($self, @data)B= not @data
ABresult
0X0
100
111
338 2 $throw->die;
339 }
340 }
341 296 return;
342 }
343  
344 1231 ▶sub option_self_assert {
Subroutine option_self_assert: called CC=6 SCAR=17.9
Pod undocumented
345 1231 my ($self, $name, @data) = @_;
346  
347 1231 ▶ if ((my $code = $self->can("self_assert_${name}")) && @data) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("self_assert_$name") and @data) 15 1216 1231
Condition100%3/3
my $code = $self->can("self_assert_$name") and @data
!ll&&!rl&&r
1215115
MC/DC100%2/2
my $code = $self->can("self_assert_$name") and @data
my $code = $self->can("self_assert_$name") @data
Truth table100%3/3
A and B
A= my $code = $self->can("self_assert_$name")B= @data
ABresult
0X0
100
111
348 15 ▶ if (my $error = catch {$code->($self, (@data ? $data[0] : $self->{$name}))}) {
Subroutine __ANON__: called CC=2 SCAR=7.0
Branch: 2 branches
BranchTrueFalseTotal
if (my $error = &catch(sub { &$code($self, @data ? $data[0] : $self->{$name}); } )) 3 12 15
@data ? : 15 0 15
349 3 ▶ if (do {require Scalar::Util; Scalar::Util::blessed($error)}) {
Branch: 1 branch
BranchTrueFalseTotal
if (do { require Scalar::Util; builtin::blessed($error) }) { } 2 1 3
350 2 ▶ return $error->isa('Venus::Error') ? $error->throw : die $error;
Branch: 1 branch
BranchTrueFalseTotal
$error->isa('Venus::Error') ? : 1 1 2
351 }
352 else {
353 1 return error {message => $error};
354 }
355 }
356 }
357 1228 return;
358 }
359  
360 1201 ▶sub option_self_coerce {
Subroutine option_self_coerce: called CC=6 SCAR=18.0
Pod undocumented
361 1201 my ($self, $name, @data) = @_;
362  
363 1201 ▶ if ((my $code = $self->can("self_coerce_${name}")) && (@data || exists $self->{$name})) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("self_coerce_$name") and @data || exists $self->{$name}) 10 1191 1201
Condition66%4/6
my $code = $self->can("self_coerce_$name") and @data || exists $self->{$name}
!ll&&!rl&&r
1191010
@data or exists $self->{$name}
l!l&&r!l&&!r
280
MC/DC33%1/3
my $code = $self->can("self_coerce_$name") and @data || exists $self->{$name}
my $code = $self->can("self_coerce_$name") @data exists $self->{$name}
Truth table75%3/4
A and B or C
A= my $code = $self->can("self_coerce_$name")B= @dataC= exists $self->{$name}
ABCresult
0XX0
1000
11X1
1011
364 10 ▶ return $self->{$name} = $code->($self, @data ? $data[0] : $self->{$name});
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 2 8 10
365 }
366 1191 ▶ return @data ? $data[0] : ();
Branch: 1 branch
BranchTrueFalseTotal
@data ? : 96 1095 1191
367 }
368  
369 935 ▶sub option_trigger {
Subroutine option_trigger: called CC=2 SCAR=6.9
Pod undocumented
370 935 my ($self, $name, @data) = @_;
371  
372 935 ▶ if (my $code = $self->can("trigger_${name}")) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("trigger_$name")) 2 933 935
373 2 $code->($self, @data);
374 }
375 935 return;
376 }
377  
378 16 ▶sub option_writer {
Subroutine option_writer: called CC=2 SCAR=6.9
Pod undocumented
379 16 my ($self, $name, @data) = @_;
380  
381 16 ▶ if (my $code = $self->can("write_${name}")) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $code = $self->can("write_$name")) { } 2 14 16
382 2 return $code->($self, @data);
383 }
384 else {
385 14 return $self->{$name} = $data[0];
386 }
387 }
388  
389 4 1;
390  
391  
392  
393 =head1 NAME
394  
395 Venus::Role::Optional - Optional Role
396  
397 =cut
398  
399 =head1 ABSTRACT
400  
401 Optional Role for Perl 5
402  
403 =cut
404  
405 =head1 SYNOPSIS
406  
407 package Person;
408  
409 use Venus::Class;
410  
411 with 'Venus::Role::Optional';
412  
413 attr 'fname';
414 attr 'lname';
415 attr 'email';
416  
417 package main;
418  
419 my $person = Person->new(
420 fname => 'Elliot',
421 lname => 'Alderson',
422 );
423  
424 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
425  
426 =cut
427  
428 =head1 DESCRIPTION
429  
430 This package modifies the consuming package and provides methods for automating
431 object construction and attribute accessors.
432  
433 =cut
434  
435 =head1 METHODS
436  
437 This package provides the following methods:
438  
439 =cut
440  
441 =head2 clear
442  
443 clear(string $name) (any)
444  
445 The clear method deletes an attribute and returns the removed value.
446  
447 I<Since C<1.55>>
448  
449 =over 4
450  
451 =item clear example 1
452  
453 # given: synopsis
454  
455 package main;
456  
457 my $fname = $person->clear('fname');
458  
459 # "Elliot"
460  
461 =back
462  
463 =over 4
464  
465 =item clear example 2
466  
467 # given: synopsis
468  
469 package main;
470  
471 my $lname = $person->clear('lname');
472  
473 # "Alderson"
474  
475 my $object = $person;
476  
477 # bless({fname => "Elliot"}, "Person")
478  
479 =back
480  
481 =over 4
482  
483 =item clear example 3
484  
485 # given: synopsis
486  
487 package main;
488  
489 my $lname = $person->clear('lname');
490  
491 # "Alderson"
492  
493 =back
494  
495 =cut
496  
497 =head2 has
498  
499 has(string $name) (boolean)
500  
501 The has method returns truthy if the attribute specified exists, otherwise
502 returns falsy.
503  
504 I<Since C<1.55>>
505  
506 =over 4
507  
508 =item has example 1
509  
510 # given: synopsis
511  
512 package main;
513  
514 my $has_fname = $person->has('fname');
515  
516 # true
517  
518 =back
519  
520 =over 4
521  
522 =item has example 2
523  
524 # given: synopsis
525  
526 package main;
527  
528 my $has_mname = $person->has('mname');
529  
530 # false
531  
532 =back
533  
534 =cut
535  
536 =head2 reset
537  
538 reset(string $name) (any)
539  
540 The reset method rebuilds an attribute and returns the deleted value.
541  
542 I<Since C<1.55>>
543  
544 =over 4
545  
546 =item reset example 1
547  
548 # given: synopsis
549  
550 package main;
551  
552 my $fname = $person->reset('fname');
553  
554 # "Elliot"
555  
556 =back
557  
558 =over 4
559  
560 =item reset example 2
561  
562 # given: synopsis
563  
564 package main;
565  
566 my $lname = $person->reset('lname');
567  
568 # "Alderson"
569  
570 my $object = $person;
571  
572 # bless({fname => "Elliot"}, "Person")
573  
574 =back
575  
576 =over 4
577  
578 =item reset example 3
579  
580 # given: synopsis
581  
582 package main;
583  
584 my $lname = $person->reset('lname', 'Smith');
585  
586 # "Alderson"
587  
588 my $object = $person;
589  
590 # bless({fname => "Elliot", lname => "Smith"}, "Person")
591  
592 =back
593  
594 =cut
595  
596 =head1 FEATURES
597  
598 This package provides the following features:
599  
600 =cut
601  
602 =over 4
603  
604 =item asserting
605  
606 This library provides a mechanism for automatically validating class attributes
607 using L<Venus::Assert> based on the return value of the attribute callback. The
608 callback should be in the form of C<assert_${name}>, and should return a
609 L<Venus::Assert> object or a "validation expression" (string) to be passed to
610 the L<Venus::Assert/expression> method.
611  
612 B<example 1>
613  
614 package Person;
615  
616 use Venus::Class;
617  
618 with 'Venus::Role::Optional';
619  
620 attr 'fname';
621 attr 'lname';
622 attr 'email';
623  
624 sub assert_fname {
625 return 'string';
626 }
627  
628 sub assert_lname {
629 return 'string';
630 }
631  
632 package main;
633  
634 my $person = Person->new(
635 fname => 'Elliot',
636 lname => 'Alderson',
637 );
638  
639 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
640  
641 B<example 2>
642  
643 package Person;
644  
645 use Venus::Class;
646  
647 with 'Venus::Role::Optional';
648  
649 attr 'fname';
650 attr 'lname';
651 attr 'email';
652  
653 sub assert_fname {
654 return 'string';
655 }
656  
657 sub assert_lname {
658 return 'string';
659 }
660  
661 package main;
662  
663 my $person = Person->new(
664 fname => 'Elliot',
665 lname => 1234567890,
666 );
667  
668 # Exception! (isa Venus::Check::Error)
669  
670 B<example 3>
671  
672 package Person;
673  
674 use Venus::Class;
675  
676 with 'Venus::Role::Optional';
677  
678 attr 'fname';
679 attr 'lname';
680 attr 'email';
681  
682 sub assert_fname {
683 return 'string';
684 }
685  
686 sub assert_lname {
687 return 'string';
688 }
689  
690 package main;
691  
692 my $person = Person->new(
693 fname => 1234567890,
694 lname => 'Alderson',
695 );
696  
697 # Exception! (isa Venus::Check::Error)
698  
699 B<example 4>
700  
701 package Person;
702  
703 use Venus::Class;
704  
705 with 'Venus::Role::Optional';
706  
707 attr 'progress';
708  
709 sub assert_progress {
710 return 'number | float';
711 }
712  
713 package main;
714  
715 my $person = Person->new(
716 progress => 1,
717 );
718  
719 # bless({progress => 1}, 'Person')
720  
721 # my $person = Person->new(
722 # progress => 7.89,
723 # );
724  
725 # bless({progress => 7.89}, 'Person')
726  
727 # my $person = Person->new(
728 # progress => '1',
729 # );
730  
731 # Exception! (isa Venus::Check::Error)
732  
733 =back
734  
735 =over 4
736  
737 =item building
738  
739 This library provides a mechanism for automatically building class attributes
740 on construction, and during getting and setting its value, after any default
741 values are processed, based on the return value of the attribute callback. The
742 callback should be in the form of C<build_${name}>, and is passed any arguments
743 provided.
744  
745 B<example 1>
746  
747 package Person;
748  
749 use Venus::Class;
750  
751 with 'Venus::Role::Optional';
752  
753 attr 'fname';
754 attr 'lname';
755 attr 'email';
756  
757 sub build_fname {
758 my ($self, $value) = @_;
759 return $value ? ucfirst $value : undef;
760 }
761  
762 sub build_lname {
763 my ($self, $value) = @_;
764 return $value ? ucfirst $value : undef;
765 }
766  
767 sub build_email {
768 my ($self, $value) = @_;
769 return $value ? lc $value : undef;
770 }
771  
772 package main;
773  
774 my $person = Person->new(
775 fname => 'elliot',
776 lname => 'alderson',
777 email => 'E.ALDERSON@E-CORP.org',
778 );
779  
780 # bless({fname => 'Elliot', lname => 'Alderson', ...}, 'Person')
781  
782 # $person->fname;
783  
784 # "Elliot"
785  
786 # $person->lname;
787  
788 # "Alderson"
789  
790 # $person->email;
791  
792 # "e.alderson@e-corp.org"
793  
794 B<example 2>
795  
796 package Person;
797  
798 use Venus::Class;
799  
800 with 'Venus::Role::Optional';
801  
802 attr 'fname';
803 attr 'lname';
804 attr 'email';
805  
806 sub build_fname {
807 my ($self, $value) = @_;
808 return $value ? ucfirst $value : undef;
809 }
810  
811 sub build_lname {
812 my ($self, $value) = @_;
813 return $value ? ucfirst $value : undef;
814 }
815  
816 sub build_email {
817 my ($self, $value) = @_;
818 return $value ? lc $value : undef;
819 }
820  
821 package Person;
822  
823 sub build_email {
824 my ($self, $value) = @_;
825 return lc join '@', (join '.', substr($self->fname, 0, 1), $self->lname),
826 'e-corp.org';
827 }
828  
829 package main;
830  
831 my $person = Person->new(
832 fname => 'Elliot',
833 lname => 'Alderson',
834 );
835  
836 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
837  
838 # $person->email;
839  
840 # "e.alderson@e-corp.org"
841  
842 B<example 3>
843  
844 package Person;
845  
846 use Venus::Class;
847  
848 with 'Venus::Role::Optional';
849  
850 attr 'fname';
851 attr 'lname';
852  
853 sub build_fname {
854 my ($self, $value) = @_;
855 return $value ? ucfirst $value : undef;
856 }
857  
858 sub coerce_fname {
859 return 'Venus::String';
860 }
861  
862 sub build_lname {
863 my ($self, $value) = @_;
864 return $value ? ucfirst $value : undef;
865 }
866  
867 sub coerce_lname {
868 return 'Venus::String';
869 }
870  
871 package main;
872  
873 my $person = Person->new(
874 fname => 'elliot',
875 lname => 'alderson',
876 );
877  
878 # bless({
879 # fname => bless({value => 'Elliot'}, 'Venus::String'),
880 # lname => bless({value => 'Alderson'}, 'Venus::String')
881 # }, 'Person')
882  
883 B<example 4>
884  
885 package Person;
886  
887 use Venus::Class;
888  
889 with 'Venus::Role::Optional';
890  
891 attr 'email';
892  
893 sub build_email {
894 my ($self, $value) = @_;
895 return $value ? lc $value : undef;
896 }
897  
898 sub coerce_email {
899 return 'Venus::String';
900 }
901  
902 package main;
903  
904 my $person = Person->new(
905 email => 'Elliot.Alderson@e-corp.org',
906 );
907  
908 # bless({
909 # email => bless({value => 'elliot.alderson@e-corp.org'}, 'Venus::String'),
910 # }, 'Person')
911  
912 B<example 5>
913  
914 package Person;
915  
916 use Venus::Class;
917  
918 with 'Venus::Role::Optional';
919  
920 attr 'email';
921  
922 sub build_email {
923 my ($self, $value) = @_;
924 return $value ? lc $value : undef;
925 }
926  
927 sub default_email {
928 return 'NO-REPLY@E-CORP.ORG';
929 }
930  
931 package main;
932  
933 my $person = Person->new;
934  
935 # bless({email => 'no-reply@e-corp.org'}, 'Person')
936  
937 =back
938  
939 =over 4
940  
941 =item checking
942  
943 This library provides a mechanism for automatically checking class attributes
944 after getting or setting its value. The callback should be in the form of
945 C<check_${name}>, and is passed any arguments provided.
946  
947 B<example 1>
948  
949 package Person;
950  
951 use Venus::Class;
952  
953 with 'Venus::Role::Optional';
954  
955 attr 'fname';
956 attr 'lname';
957 attr 'email';
958  
959 sub check_fname {
960 my ($self, $value) = @_;
961 if ($value) {
962 return true if lc($value) eq 'elliot';
963 }
964 return false;
965 }
966  
967 sub check_lname {
968 my ($self, $value) = @_;
969 if ($value) {
970 return true if lc($value) eq 'alderson';
971 }
972 return false;
973 }
974  
975 package main;
976  
977 my $person = Person->new(
978 fname => 'Elliot',
979 lname => 'Alderson',
980 );
981  
982 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
983  
984 B<example 2>
985  
986 package Person;
987  
988 use Venus::Class;
989  
990 with 'Venus::Role::Optional';
991  
992 attr 'fname';
993 attr 'lname';
994 attr 'email';
995  
996 sub check_fname {
997 my ($self, $value) = @_;
998 if ($value) {
999 return true if lc($value) eq 'elliot';
1000 }
1001 return false;
1002 }
1003  
1004 sub check_lname {
1005 my ($self, $value) = @_;
1006 if ($value) {
1007 return true if lc($value) eq 'alderson';
1008 }
1009 return false;
1010 }
1011  
1012 package main;
1013  
1014 my $person = Person->new(
1015 fname => 'Elliot',
1016 lname => 'Alderson',
1017 );
1018  
1019 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1020  
1021 # $person->lname('Alderson');
1022  
1023 # "Alderson"
1024  
1025 # $person->lname('');
1026  
1027 # Exception! (isa Person::Error)
1028  
1029 =back
1030  
1031 =over 4
1032  
1033 =item coercing
1034  
1035 This library provides a mechanism for automatically coercing class attributes
1036 into class instances using L<Venus::Space> based on the return value of the
1037 attribute callback. The callback should be in the form of C<coerce_${name}>,
1038 and should return the name of the package to be constructed. That package will
1039 be instantiated via the customary C<new> method, passing the data recevied as
1040 its arguments.
1041  
1042 B<example 1>
1043  
1044 package Person;
1045  
1046 use Venus::Class;
1047  
1048 with 'Venus::Role::Optional';
1049  
1050 attr 'fname';
1051 attr 'lname';
1052 attr 'email';
1053  
1054 sub coerce_fname {
1055 my ($self, $value) = @_;
1056  
1057 return 'Venus::String';
1058 }
1059  
1060 sub coerce_lname {
1061 my ($self, $value) = @_;
1062  
1063 return 'Venus::String';
1064 }
1065  
1066 sub coerce_email {
1067 my ($self, $value) = @_;
1068  
1069 return 'Venus::String';
1070 }
1071  
1072 package main;
1073  
1074 my $person = Person->new(
1075 fname => 'Elliot',
1076 lname => 'Alderson',
1077 );
1078  
1079 # bless({
1080 # 'fname' => bless({'value' => 'Elliot'}, 'Venus::String'),
1081 # 'lname' => bless({'value' => 'Alderson'}, 'Venus::String')
1082 # }, 'Person')
1083  
1084 B<example 2>
1085  
1086 package Person;
1087  
1088 use Venus::Class;
1089 use Venus::String;
1090  
1091 with 'Venus::Role::Optional';
1092  
1093 attr 'fname';
1094 attr 'lname';
1095 attr 'email';
1096  
1097 sub coerce_fname {
1098 my ($self, $value) = @_;
1099  
1100 return 'Venus::String';
1101 }
1102  
1103 sub coerce_lname {
1104 my ($self, $value) = @_;
1105  
1106 return 'Venus::String';
1107 }
1108  
1109 sub coerce_email {
1110 my ($self, $value) = @_;
1111  
1112 return 'Venus::String';
1113 }
1114  
1115 package main;
1116  
1117 my $person = Person->new(
1118 email => 'e.alderson@e-corp.org',
1119 );
1120  
1121 # bless({
1122 # 'email' => bless({'value' => 'e.alderson@e-corp.org'}, 'Venus::String'),
1123 # }, 'Person')
1124  
1125 B<example 3>
1126  
1127 package Person;
1128  
1129 use Venus::Class;
1130  
1131 with 'Venus::Role::Optional';
1132  
1133 attr 'email';
1134  
1135 sub coerce_email {
1136 my ($self, $value) = @_;
1137  
1138 return 'Venus::String';
1139 }
1140  
1141 sub default_email {
1142 my ($self, $value) = @_;
1143  
1144 return 'no-reply@e-corp.org';
1145 }
1146  
1147 package main;
1148  
1149 my $person = Person->new;
1150  
1151 # bless({
1152 # 'email' => bless({'value' => 'no-reply@e-corp.org'}, 'Venus::String'),
1153 # }, 'Person')
1154  
1155 =back
1156  
1157 =over 4
1158  
1159 =item defaulting
1160  
1161 This library provides a mechanism for automatically defaulting class attributes
1162 to predefined values, statically or dynamically based on the return value of
1163 the attribute callback. The callback should be in the form of
1164 C<default_${name}>, and should return the value to be used if no value exists
1165 or has been provided to the constructor.
1166  
1167 B<example 1>
1168  
1169 package Person;
1170  
1171 use Venus::Class;
1172  
1173 with 'Venus::Role::Optional';
1174  
1175 attr 'fname';
1176 attr 'lname';
1177 attr 'email';
1178  
1179 sub default_lname {
1180 my ($self, $value) = @_;
1181  
1182 return 'Alderson';
1183 }
1184  
1185 package main;
1186  
1187 my $person = Person->new(
1188 fname => 'Elliot',
1189 );
1190  
1191 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1192  
1193 # $person->lname('Johnston');
1194  
1195 # "Johnston"
1196  
1197 # $person->reset('lname');
1198  
1199 # "Johnston"
1200  
1201 # $person->lname;
1202  
1203 # "Alderson"
1204  
1205 =back
1206  
1207 =over 4
1208  
1209 =item initialing
1210  
1211 This library provides a mechanism for automatically setting class attributes to
1212 predefined values, statically or dynamically based on the return value of the
1213 attribute callback. The callback should be in the form of C<initial_${name}>,
1214 and should return the value to be used if no value has been provided to the
1215 constructor. This behavior is similar to the I<"defaulting"> mechanism but is
1216 only executed during object construction.
1217  
1218 B<example 1>
1219  
1220 package Person;
1221  
1222 use Venus::Class;
1223  
1224 with 'Venus::Role::Optional';
1225  
1226 attr 'fname';
1227 attr 'lname';
1228 attr 'email';
1229  
1230 sub initial_lname {
1231 my ($self, $value) = @_;
1232  
1233 return 'Alderson';
1234 }
1235  
1236 package main;
1237  
1238 my $person = Person->new(
1239 fname => 'Elliot',
1240 );
1241  
1242 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1243  
1244 # $person->lname('Johnston');
1245  
1246 # "Johnston"
1247  
1248 # $person->reset('lname');
1249  
1250 # "Johnston"
1251  
1252 # $person->lname;
1253  
1254 # undef
1255  
1256 =back
1257  
1258 =over 4
1259  
1260 =item lazy-building
1261  
1262 This library provides a mechanism for automatically building class attributes
1263 during getting and setting its value, after any default values are processed,
1264 based on the return value of the attribute callback. The callback should be in
1265 the form of C<lazy_build_${name}>, and is passed any arguments provided.
1266  
1267 B<example 1>
1268  
1269 package Person;
1270  
1271 use Venus::Class;
1272  
1273 with 'Venus::Role::Optional';
1274  
1275 attr 'email';
1276  
1277 sub lazy_build_email {
1278 my ($self, $value) = @_;
1279 return $value ? lc $value : 'no-reply@e-corp.org';
1280 }
1281  
1282 package main;
1283  
1284 my $person = Person->new;
1285  
1286 # bless({}, 'Person')
1287  
1288 # $person->email;
1289  
1290 # "no-reply@e-corp.org"
1291  
1292 B<example 2>
1293  
1294 package Person;
1295  
1296 use Venus::Class;
1297  
1298 with 'Venus::Role::Optional';
1299  
1300 attr 'email';
1301  
1302 sub coerce_email {
1303 return 'Venus::String';
1304 }
1305  
1306 sub lazy_build_email {
1307 my ($self, $value) = @_;
1308 return $value ? lc $value : 'no-reply@e-corp.org';
1309 }
1310  
1311 package main;
1312  
1313 my $person = Person->new;
1314  
1315 # bless({}, 'Person')
1316  
1317 # $person->email;
1318  
1319 # bless({value => 'no-reply@e-corp.org'}, 'Venus::String')
1320  
1321 B<example 3>
1322  
1323 package Person;
1324  
1325 use Venus::Class;
1326  
1327 with 'Venus::Role::Optional';
1328  
1329 attr 'email';
1330  
1331 sub default_email {
1332 return 'NO-REPLY@E-CORP.ORG';
1333 }
1334  
1335 sub lazy_build_email {
1336 my ($self, $value) = @_;
1337 return $value ? lc $value : undef;
1338 }
1339  
1340 package main;
1341  
1342 my $person = Person->new;
1343  
1344 # bless({}, 'Person')
1345  
1346 # $person->email;
1347  
1348 # "no-reply@e-corp.org"
1349  
1350 =back
1351  
1352 =over 4
1353  
1354 =item reading
1355  
1356 This library provides a mechanism for hooking into the class attribute reader
1357 (accessor) for reading values via the the attribute reader callback. The
1358 callback should be in the form of C<read_${name}>, and should read and return
1359 the value for the attribute specified.
1360  
1361 B<example 1>
1362  
1363 package Person;
1364  
1365 use Venus::Class;
1366  
1367 with 'Venus::Role::Optional';
1368  
1369 attr 'fname';
1370 attr 'lname';
1371 attr 'email';
1372  
1373 sub read_fname {
1374 my ($self, $value) = @_;
1375  
1376 return ucfirst $self->{fname};
1377 }
1378  
1379 sub read_lname {
1380 my ($self, $value) = @_;
1381  
1382 return ucfirst $self->{lname};
1383 }
1384  
1385 package main;
1386  
1387 my $person = Person->new(
1388 fname => 'elliot',
1389 lname => 'alderson',
1390 );
1391  
1392 # bless({fname => 'elliot', lname => 'alderson'}, 'Person')
1393  
1394 # $person->fname;
1395  
1396 # "Elliot"
1397  
1398 # $person->lname;
1399  
1400 # "Alderson"
1401  
1402 =back
1403  
1404 =over 4
1405  
1406 =item readonly
1407  
1408 This library provides a mechanism for marking class attributes as I<"readonly">
1409 (or not) based on the return value of the attribute callback. The callback
1410 should be in the form of C<readonly_${name}>, and should return truthy to
1411 automatically throw an exception if a change is attempted.
1412  
1413 B<example 1>
1414  
1415 package Person;
1416  
1417 use Venus::Class;
1418  
1419 with 'Venus::Role::Optional';
1420  
1421 attr 'fname';
1422 attr 'lname';
1423 attr 'email';
1424  
1425 sub readonly_fname {
1426 my ($self, $value) = @_;
1427  
1428 return true;
1429 }
1430  
1431 sub readonly_lname {
1432 my ($self, $value) = @_;
1433  
1434 return true;
1435 }
1436  
1437 package main;
1438  
1439 my $person = Person->new(
1440 fname => 'Elliot',
1441 lname => 'Alderson',
1442 );
1443  
1444 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1445  
1446 $person->fname('Mister');
1447  
1448 # Exception! (isa Person::Error)
1449  
1450 # $person->lname('Johnston');
1451  
1452 # Exception! (isa Person::Error)
1453  
1454 =back
1455  
1456 =over 4
1457  
1458 =item readwrite
1459  
1460 This library provides a mechanism for marking class attributes as I<"readwrite">
1461 (or not) based on the return value of the attribute callback. The callback
1462 should be in the form of C<readwrite_${name}>, and should return falsy to
1463 automatically throw an exception if a change is attempted.
1464  
1465 B<example 1>
1466  
1467 package Person;
1468  
1469 use Venus::Class;
1470  
1471 with 'Venus::Role::Optional';
1472  
1473 attr 'fname';
1474 attr 'lname';
1475 attr 'email';
1476  
1477 sub readwrite_fname {
1478 my ($self, $value) = @_;
1479  
1480 return false;
1481 }
1482  
1483 sub readwrite_lname {
1484 my ($self, $value) = @_;
1485  
1486 return false;
1487 }
1488  
1489 package main;
1490  
1491 my $person = Person->new(
1492 fname => 'Elliot',
1493 lname => 'Alderson',
1494 );
1495  
1496 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1497  
1498 $person->fname('Mister');
1499  
1500 # Exception! (isa Person::Error)
1501  
1502 # $person->lname('Johnston');
1503  
1504 # Exception! (isa Person::Error)
1505  
1506 =back
1507  
1508 =over 4
1509  
1510 =item requiring
1511  
1512 This library provides a mechanism for marking class attributes as I<"required">
1513 (i.e. to be provided to the constructor) based on the return value of the
1514 attribute callback. The callback should be in the form of C<require_${name}>,
1515 and should return truthy to automatically throw an exception if the related
1516 attribute is missing.
1517  
1518 B<example 1>
1519  
1520 package Person;
1521  
1522 use Venus::Class;
1523  
1524 with 'Venus::Role::Optional';
1525  
1526 attr 'fname';
1527 attr 'lname';
1528 attr 'email';
1529  
1530 sub require_fname {
1531 my ($self, $value) = @_;
1532  
1533 return true;
1534 }
1535  
1536 sub require_lname {
1537 my ($self, $value) = @_;
1538  
1539 return true;
1540 }
1541  
1542 sub require_email {
1543 my ($self, $value) = @_;
1544  
1545 return false;
1546 }
1547  
1548 package main;
1549  
1550 my $person = Person->new(
1551 fname => 'Elliot',
1552 lname => 'Alderson',
1553 );
1554  
1555 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1556  
1557 B<example 2>
1558  
1559 package Person;
1560  
1561 use Venus::Class;
1562  
1563 with 'Venus::Role::Optional';
1564  
1565 attr 'fname';
1566 attr 'lname';
1567 attr 'email';
1568  
1569 sub require_fname {
1570 my ($self, $value) = @_;
1571  
1572 return true;
1573 }
1574  
1575 sub require_lname {
1576 my ($self, $value) = @_;
1577  
1578 return true;
1579 }
1580  
1581 sub require_email {
1582 my ($self, $value) = @_;
1583  
1584 return false;
1585 }
1586  
1587 package main;
1588  
1589 my $person = Person->new(
1590 fname => 'Elliot',
1591 );
1592  
1593 # Exception! (isa Person::Error)
1594  
1595 B<example 3>
1596  
1597 package Person;
1598  
1599 use Venus::Class;
1600  
1601 with 'Venus::Role::Optional';
1602  
1603 attr 'fname';
1604 attr 'lname';
1605 attr 'email';
1606  
1607 sub require_fname {
1608 my ($self, $value) = @_;
1609  
1610 return true;
1611 }
1612  
1613 sub require_lname {
1614 my ($self, $value) = @_;
1615  
1616 return true;
1617 }
1618  
1619 sub require_email {
1620 my ($self, $value) = @_;
1621  
1622 return false;
1623 }
1624  
1625 package main;
1626  
1627 my $person = Person->new(
1628 lname => 'Alderson',
1629 );
1630  
1631 # Exception! (isa Person::Error)
1632  
1633 =back
1634  
1635 =over 4
1636  
1637 =item self-asserting
1638  
1639 This library provides a mechanism for automatically validating class attributes
1640 using the attribute callback provided. The author is resposible for validating
1641 the state of the attribute and raising an exception when an attribute fails
1642 validation. The callback should be in the form of C<self_assert_${name}>.
1643  
1644 B<example 1>
1645  
1646 package Person;
1647  
1648 use Venus::Class;
1649  
1650 with 'Venus::Role::Optional';
1651  
1652 attr 'fname';
1653 attr 'lname';
1654  
1655 sub self_assert_fname {
1656 my ($self, $value) = @_;
1657 die 'Bad fname' if $value && $value !~ '^[a-zA-Z]';
1658 }
1659  
1660 sub self_assert_lname {
1661 my ($self, $value) = @_;
1662 die 'Bad lname' if $value && $value !~ '^[a-zA-Z]';
1663 }
1664  
1665 package main;
1666  
1667 my $person = Person->new(
1668 fname => 'Elliot',
1669 lname => 'Alderson',
1670 );
1671  
1672 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1673  
1674 # my $person = Person->new(fname => '@ElliotAlderson');
1675  
1676 # Exception! (isa Venus::Error)
1677  
1678 B<example 2>
1679  
1680 package Person;
1681  
1682 use Venus::Class 'attr', 'raise', 'with';
1683  
1684 with 'Venus::Role::Optional';
1685  
1686 attr 'fname';
1687 attr 'lname';
1688  
1689 sub self_assert_fname {
1690 my ($self, $value) = @_;
1691 raise 'Person::Error::BadFname' if $value && $value !~ '^[a-zA-Z]';
1692 }
1693  
1694 sub self_assert_lname {
1695 my ($self, $value) = @_;
1696 raise 'Person::Error::BadLname' if $value && $value !~ '^[a-zA-Z]';
1697 }
1698  
1699 package main;
1700  
1701 my $person = Person->new(
1702 fname => 'Elliot',
1703 lname => 'Alderson',
1704 );
1705  
1706 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1707  
1708 # my $person = Person->new(lname => '@AldersonElliot');
1709  
1710 # Exception! (isa Person::Error::BadLname, isa Venus::Error)
1711  
1712 B<example 3>
1713  
1714 package Person;
1715  
1716 use Venus::Class;
1717  
1718 with 'Venus::Role::Optional';
1719  
1720 attr 'fname';
1721 attr 'lname';
1722  
1723 sub self_assert_fname {
1724 my ($self, $value) = @_;
1725 die $self if $value && $value !~ '^[a-zA-Z]';
1726 }
1727  
1728 sub self_assert_lname {
1729 my ($self, $value) = @_;
1730 die $self if $value && $value !~ '^[a-zA-Z]';
1731 }
1732  
1733 package main;
1734  
1735 my $person = Person->new(
1736 fname => 'Elliot',
1737 lname => 'Alderson',
1738 );
1739  
1740 # bless({fname => 'Elliot', lname => 'Alderson'}, 'Person')
1741  
1742 # my $person = Person->new(fname => rand);
1743  
1744 # Exception! (isa Person)
1745  
1746 =back
1747  
1748 =over 4
1749  
1750 =item self-coercing
1751  
1752 This library provides a mechanism for automatically coercing class attributes
1753 using the attribute callback provided. The author is resposible for any
1754 transformations to the attribute and value. The callback should be in the form
1755 of C<self_coerce_${name}>.
1756  
1757 B<example 1>
1758  
1759 package Person;
1760  
1761 use Venus::Class;
1762  
1763 with 'Venus::Role::Optional';
1764  
1765 attr 'fname';
1766 attr 'lname';
1767  
1768 sub self_coerce_fname {
1769 my ($self, $value) = @_;
1770  
1771 require Venus::String;
1772  
1773 return Venus::String->new($value || '');
1774 }
1775  
1776 sub self_coerce_lname {
1777 my ($self, $value) = @_;
1778  
1779 require Venus::String;
1780  
1781 return Venus::String->new($value || '');
1782 }
1783  
1784 package main;
1785  
1786 my $person = Person->new(
1787 fname => 'Elliot',
1788 lname => 'Alderson',
1789 );
1790  
1791 # bless({
1792 # fname => bless({value => 'Elliot'}, 'Venus::String'),
1793 # lname => bless({value => 'Alderson'}, 'Venus::String')
1794 # }, 'Person')
1795  
1796 B<example 2>
1797  
1798 package Person;
1799  
1800 use Venus::Class;
1801  
1802 with 'Venus::Role::Optional';
1803  
1804 attr 'email';
1805  
1806 sub default_email {
1807 my ($self, $value) = @_;
1808  
1809 return 'no-reply@e-corp.org';
1810 }
1811  
1812 sub self_coerce_email {
1813 my ($self, $value) = @_;
1814  
1815 require Venus::String;
1816  
1817 return Venus::String->new($value || '');
1818 }
1819  
1820 package main;
1821  
1822 my $person = Person->new;
1823  
1824 # bless({
1825 # 'email' => bless({'value' => 'no-reply@e-corp.org'}, 'Venus::String'),
1826 # }, 'Person')
1827  
1828 =back
1829  
1830 =over 4
1831  
1832 =item triggering
1833  
1834 This library provides a mechanism for automatically triggering routines after
1835 reading or writing class attributes via an attribute callback. The callback
1836 should be in the form of C<trigger_${name}>, and will be invoked after the
1837 related attribute is read or written.
1838  
1839 B<example 1>
1840  
1841 package Person;
1842  
1843 use Venus::Class;
1844  
1845 with 'Venus::Role::Optional';
1846  
1847 attr 'fname';
1848 attr 'lname';
1849 attr 'email';
1850  
1851 sub trigger_fname {
1852 my ($self, $value) = @_;
1853  
1854 if ($value) {
1855 $self->{dirty}{fname} = $value;
1856 }
1857 return;
1858 }
1859  
1860 sub trigger_lname {
1861 my ($self, $value) = @_;
1862  
1863 if ($value) {
1864 $self->{dirty}{lname} = $value;
1865 }
1866 return;
1867 }
1868  
1869 package main;
1870  
1871 my $person = Person->new;
1872  
1873 # bless({}, 'Person')
1874  
1875 # $person->fname('Elliot');
1876  
1877 # "Elliot"
1878  
1879 # $person->lname('Alderson');
1880  
1881 # "Alderson"
1882  
1883 # my $object = $person;
1884  
1885 # bless({..., dirty => {fname => 'Elliot', lname => 'Alderson'}}, 'Person')
1886  
1887 =back
1888  
1889 =over 4
1890  
1891 =item writing
1892  
1893 This library provides a mechanism for hooking into the class attribute writer
1894 (accessor) for writing values via the the attribute writer callback. The
1895 callback should be in the form of C<write_${name}>, and should set and return
1896 the value for the attribute specified.
1897  
1898 B<example 1>
1899  
1900 package Person;
1901  
1902 use Venus::Class;
1903  
1904 with 'Venus::Role::Optional';
1905  
1906 attr 'fname';
1907 attr 'lname';
1908 attr 'email';
1909  
1910 sub write_fname {
1911 my ($self, $value) = @_;
1912  
1913 return $self->{fname} = ucfirst $value;
1914 }
1915  
1916 sub write_lname {
1917 my ($self, $value) = @_;
1918  
1919 return $self->{lname} = ucfirst $value;
1920 }
1921  
1922 package main;
1923  
1924 my $person = Person->new;
1925  
1926 # bless({}, 'Person')
1927  
1928 # $person->fname('elliot');
1929  
1930 # "Elliot"
1931  
1932 # $person->lname('alderson');
1933  
1934 # "Alderson"
1935  
1936 =back
1937  
1938 =head1 AUTHORS
1939  
1940 Awncorp, C<awncorp@cpan.org>
1941  
1942 =cut
1943  
1944 =head1 LICENSE
1945  
1946 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
1947  
1948 This program is free software, you can redistribute it and/or modify it under
1949 the terms of the Apache license version 2.0.
1950  
1951 =cut
« blib/lib/Venus/Gather.pm ↑ Summary blib/lib/Venus/Meta.pm »