blib/lib/Venus/Space.pm

filter: Statementstmt 94.7% 519 / 548 Branchbran 84.5% 93 / 110 Conditioncond 63.1% 12 / 19 MC/DCmcdc 36.3% 4 / 11 Subroutinesub 97.5% 118 / 121 Podpod 88.1% 67 / 76 totaltotal 91.8% 813 / 885 CC 75 SCAR 8.8
CC
75
Cov
92%
unpatch
6.0
__ANON__
5.2
__ANON__
5.2
CRAP 2.4
« blib/lib/Venus/Role/Subscribable.pm ↑ Summary blib/lib/Venus/Coercion.pm »
1 package Venus::Space;
2  
3 29 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 29 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 29 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 29 ▶use Venus::Class 'base';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 29 base 'Venus::Name';
15  
16 # STATE
17  
18 29 state $SERIAL = 0;
19  
20 # BUILDERS
21  
22 605 ▶sub build_self {
Subroutine build_self: called CC=2 SCAR=7.1
Pod undocumented
23 605 my ($self, $data) = @_;
24  
25 605 ▶ $self->{value} = $self->package if !$self->lookslike_a_pragma;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->lookslike_a_pragma 605 0 605
26  
27 605 return $self;
28 }
29  
30 # METHODS
31  
32 3 ▶sub all {
Subroutine all: called CC=2 SCAR=6.9
Pod documented
33 3 my ($self, $name, @args) = @_;
34  
35 3 my $result = [];
36 3 my $class = $self->class;
37  
38 3 for my $package ($self->package, @{$self->inherits}) {
39 7 push @$result, [$package, $class->new($package)->$name(@args)];
40 }
41  
42 3 return $result;
43 }
44  
45 12 ▶sub after {
Subroutine after: called CC=1 SCAR=0.0
Pod documented
46 12 my ($self, $name, $code) = @_;
47  
48 11 ▶ my $orig = $self->handle($name, sub{
Subroutine __ANON__: called CC=5 SCAR=16.4
49 11 my ($orig, @args) = @_;
50  
51 11 my @return;
52  
53 11 ▶ if (wantarray) {
Branch: 2 branches
BranchTrueFalseTotal
if (wantarray) { } 0 11 11
elsif (defined wantarray) { } 6 5 11
54 0 @return = $orig->(@args);
55 }
56 elsif (defined wantarray) {
57 6 $return[0] = $orig->(@args);
58 }
59 else {
60 5 $orig->(@args);
61 }
62  
63 11 $code->(@args);
64  
65 11 ▶ return wantarray ? @return : defined(wantarray) ? $return[0] : ();
Branch: 2 branches
BranchTrueFalseTotal
wantarray ? : 0 11 11
defined wantarray ? : 6 5 11
66 12 });
67  
68 12 return $orig;
69 }
70  
71 12 ▶sub append {
Subroutine append: called CC=1 SCAR=0.0
Pod documented
72 12 my ($self, @args) = @_;
73  
74 12 my $class = $self->class;
75  
76 12 my $path = join '/',
77 $self->path, map $class->new($_)->path, @args;
78  
79 12 return $class->new($path);
80 }
81  
82 11 ▶sub array {
Subroutine array: called CC=2 SCAR=6.9
Pod documented
83 11 my ($self, $name, @data) = @_;
84  
85 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
86  
87 11 my $class = $self->package;
88  
89 29 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
90  
91 11 ▶ @{"${class}::${name}"} = @data if @data;
Branch: 1 branch
BranchTrueFalseTotal
if @data 2 9 11
92  
93 11 return [@{"${class}::${name}"}];
94 }
95  
96 2 ▶sub arrays {
Subroutine arrays: called CC=1 SCAR=0.0
Pod documented
97 2 my ($self) = @_;
98  
99 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
100  
101 2 my $class = $self->package;
102  
103 my $arrays = [
104 13 sort grep !!@{"${class}::$_"},
105 2 grep /^[_a-zA-Z]\w*$/, keys %{"${class}::"}
106 ];
107  
108 2 return $arrays;
109 }
110  
111 10 ▶sub around {
Subroutine around: called CC=2 SCAR=6.9
Pod documented
112 10 my ($self, $name, $code) = @_;
113  
114 10 my $package = $self->package;
115  
116 10 my $qualified = "${package}::${name}";
117  
118 10 my $current = $package->can($name);
119  
120 10 ▶ if (!$current) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($current) 1 9 10
121 1 $self->error_on_around_missing({package => $package, routine => $name})
122 ->input($self, $name, $code)
123 ->throw;
124 }
125  
126 9 return $self->handle($name, $code);
127 }
128  
129 2 ▶sub attributes {
Subroutine attributes: called CC=1 SCAR=0.0
Pod documented
130 2 my ($self) = @_;
131  
132 2 return $self->meta->local('attrs');
133 }
134  
135 2 ▶sub authority {
Subroutine authority: called CC=1 SCAR=0.0
Pod documented
136 2 my ($self) = @_;
137  
138 2 return $self->scalar('AUTHORITY');
139 }
140  
141 2 ▶sub basename {
Subroutine basename: called CC=1 SCAR=0.0
Pod documented
142 2 my ($self) = @_;
143  
144 2 return $self->parse->[-1];
145 }
146  
147 11 ▶sub before {
Subroutine before: called CC=1 SCAR=0.0
Pod documented
148 11 my ($self, $name, $code) = @_;
149  
150 9 ▶ my $orig = $self->handle($name, sub{
Subroutine __ANON__: called CC=5 SCAR=16.4
151 9 my ($orig, @args) = @_;
152  
153 9 $code->(@args);
154  
155 9 my @return;
156  
157 9 ▶ if (wantarray) {
Branch: 2 branches
BranchTrueFalseTotal
if (wantarray) { } 0 9 9
elsif (defined wantarray) { } 3 6 9
158 0 @return = $orig->(@args);
159 }
160 elsif (defined wantarray) {
161 3 $return[0] = $orig->(@args);
162 }
163 else {
164 6 $orig->(@args);
165 }
166  
167 9 ▶ return wantarray ? @return : defined(wantarray) ? $return[0] : ();
Branch: 2 branches
BranchTrueFalseTotal
wantarray ? : 0 9 9
defined wantarray ? : 3 6 9
168 11 });
169  
170 11 return $orig;
171 }
172  
173 7 ▶sub blessed {
Subroutine blessed: called CC=2 SCAR=6.9
Pod documented
174 7 my ($self, $data) = @_;
175  
176 7 ▶ $data //= {};
Condition100%2/2
$data //= {}
l!l
25
MC/DC100%1/1
$data //= {}
$data
Truth table100%2/2
A
A= $data
Aresult
11
00
177  
178 7 my $class = $self->load;
179  
180 7 return CORE::bless($data, $class);
181 }
182  
183 9 ▶sub build {
Subroutine build: called CC=1 SCAR=0.0
Pod documented
184 9 my ($self, @args) = @_;
185  
186 9 my $class = $self->load;
187  
188 9 return $self->call('new', $class, @args);
189 }
190  
191 13 ▶sub call {
Subroutine call: called CC=5 SCAR=16.1
Pod documented
192 13 my ($self, $func, @args) = @_;
193  
194 13 my $class = $self->load;
195  
196 13 ▶ unless ($func) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($func) 0 13 13
197 0 $self->error_on_call_undefined({package => $class, routine => $func})
198 ->input($self, $func, @args)
199 ->throw;
200 }
201  
202 13 my $next = $class->can($func);
203  
204 13 ▶ unless ($next) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($next) 3 10 13
205 3 ▶ if ($class->can('AUTOLOAD')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($class->can("AUTOLOAD")) 1 2 3
206 29 ▶ $next = sub { no strict 'refs'; &{"${class}::${func}"}(@args) };
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
207 }
208 }
209  
210 13 ▶ unless ($next) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($next) 2 11 13
211 2 $self->error_on_call_missing({package => $class, routine => $func})
212 ->input($self, $func, @args)
213 ->throw;
214 }
215  
216 11 @_ = @args; goto $next;
217 }
218  
219 3 ▶sub chain {
Subroutine chain: called CC=3 SCAR=11.0
Pod documented
220 3 my ($self, @steps) = @_;
221  
222 3 my $result = $self;
223  
224 3 for my $step (@steps) {
225 5 ▶ my ($name, @args) = (ref($step) eq 'ARRAY') ? @$step : ($step);
Branch: 1 branch
BranchTrueFalseTotal
ref $step eq 'ARRAY' ? : 2 3 5
226  
227 5 $result = $result->$name(@args);
228 }
229  
230 3 return $result;
231 }
232  
233 9 ▶sub child {
Subroutine child: called CC=1 SCAR=0.0
Pod documented
234 9 my ($self, @args) = @_;
235  
236 9 return $self->append(@args);
237 }
238  
239 1 ▶sub children {
Subroutine children: called CC=5 SCAR=16.1
Pod documented
240 1 my ($self) = @_;
241  
242 1 my %list;
243 my $path;
244 1 my $type;
245  
246 1 $path = quotemeta $self->path;
247 1 $type = 'pm';
248  
249 1 my $regexp = qr/$path\/[^\/]+\.$type/;
250  
251 1 for my $item (keys %INC) {
252 195 ▶ $list{$item}++ if $item =~ /$regexp$/;
Branch: 1 branch
BranchTrueFalseTotal
if $item =~ /$regexp$/u 2 193 195
253 }
254  
255 1 my %seen;
256  
257 1 for my $dir (@INC) {
258 8 ▶ next if $seen{$dir}++;
Branch: 1 branch
BranchTrueFalseTotal
if $seen{$dir}++ 1 7 8
259  
260 7 my $re = quotemeta $dir;
261 27 map { s/^$re\///; $list{$_}++ }
262 7 ▶ grep !$list{$_}, glob "$dir/@{[$self->path]}/*.$type";
Subroutine BEGIN: called CC=1 SCAR=0.0
263 }
264  
265 1 my $class = $self->class;
266  
267 return [
268 map $class->new($_),
269 1 map {s/(.*)\.$type$/$1/r}
270 sort keys %list
271 ];
272 }
273  
274 5 ▶sub cop {
Subroutine cop: called CC=3 SCAR=11.2
Pod documented
275 5 my ($self, $func, @args) = @_;
276  
277 5 my $class = $self->load;
278  
279 5 ▶ if (!$func) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($func) 0 5 5
280 0 $self->error_on_cop_undefined({package => $class, routine => $func})
281 ->input($self, $func, @args)
282 ->throw;
283 }
284  
285 5 my $next = $class->can($func);
286  
287 5 ▶ unless ($next) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($next) 2 3 5
288 2 $self->error_on_cop_missing({package => $class, routine => $func})
289 ->input($self, $func, @args)
290 ->throw;
291 }
292  
293 3 ▶ return sub { $next->(@args ? (@args, @_) : @_) };
Subroutine __ANON__: called CC=2 SCAR=7.2
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 1 0 1
294 }
295  
296 1 ▶sub data {
Subroutine data: called CC=2 SCAR=7.9
Pod documented
297 1 my ($self) = @_;
298  
299 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
300  
301 1 my $class = $self->package;
302  
303 1 local $.;
304  
305 1 my $handle = \*{"${class}::DATA"};
306  
307 1 ▶ return '' if !fileno $handle;
Branch: 1 branch
BranchTrueFalseTotal
unless fileno $handle 1 0 1
308  
309 0 seek $handle, 0, 0;
310  
311 0 my $data = join '', <$handle>;
312  
313 0 $data =~ s/^.*\n__DATA__\r?\n/\n/s;
314 0 $data =~ s/\n__END__\r?\n.*$/\n/s;
315  
316 0 return $data;
317 }
318  
319 15 ▶sub eval {
Subroutine eval: called CC=2 SCAR=6.9
Pod documented
320 15 my ($self, @args) = @_;
321  
322 15 local $@;
323  
324 15 ▶ my $result = eval join ' ', map "$_", "package @{[$self->package]};", @args;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
325  
326 15 ▶ if (my $error = $@) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $error = $@) 3 12 15
327 3 $self->error_on_eval({package => $self->package, error => $error})
328 ->input($self, @args)
329 ->output($error)
330 ->throw;
331 }
332  
333 12 return $result;
334 }
335  
336 84 ▶sub explain {
Subroutine explain: called CC=1 SCAR=0.0
Pod documented
337 84 my ($self) = @_;
338  
339 84 return $self->package;
340 }
341  
342 42 ▶sub handle {
Subroutine handle: called CC=2 SCAR=6.9
Pod documented
343 42 my ($self, $name, $code) = @_;
344  
345 42 my $package = $self->package;
346  
347 42 my $qualified = "${package}::${name}";
348  
349 42 my $current = $package->can($name);
350  
351 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
352 29 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
353  
354 42 ▶ *{$qualified} = eval "package $package; sub { \$code->(\$current, \@_) }";
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
355  
356 42 ▶ if (my $error = $@) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $error = $@) 0 42 42
357 0 $self->error_on_eval({package => $package, error => $error})
358 ->throw;
359 }
360  
361 42 return $current;
362 }
363  
364 2 ▶sub hash {
Subroutine hash: called CC=2 SCAR=6.9
Pod documented
365 2 my ($self, $name, @data) = @_;
366  
367 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
368  
369 2 my $class = $self->package;
370  
371 29 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
372  
373 2 ▶ %{"${class}::${name}"} = (@data) if @data;
Branch: 1 branch
BranchTrueFalseTotal
if @data 1 1 2
374  
375 2 return {%{"${class}::${name}"}};
376 }
377  
378 2 ▶sub hashes {
Subroutine hashes: called CC=1 SCAR=0.0
Pod documented
379 2 my ($self) = @_;
380  
381 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
382  
383 2 my $class = $self->package;
384  
385 return [
386 17 sort grep !!%{"${class}::$_"},
387 2 grep /^[_a-zA-Z]\w*$/, keys %{"${class}::"}
388 ];
389 }
390  
391 8 ▶sub hook {
Subroutine hook: called CC=1 SCAR=0.0
Pod documented
392 8 my ($self, $method, $name, $code) = @_;
393  
394 8 return $self->$method(uc($name), $code);
395 }
396  
397 2 ▶sub id {
Subroutine id: called CC=1 SCAR=0.0
Pod documented
398 2 my ($self) = @_;
399  
400 2 return $self->label;
401 }
402  
403 15 ▶sub init {
Subroutine init: called CC=2 SCAR=6.9
Pod documented
404 15 my ($self) = @_;
405  
406 15 $self->tryload;
407  
408 15 ▶ $self->eval('sub import') if !$self->loaded;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->loaded 5 10 15
409  
410 15 return $self->package;
411 }
412  
413 8 ▶sub inherits {
Subroutine inherits: called CC=1 SCAR=0.0
Pod documented
414 8 my ($self) = @_;
415  
416 8 return $self->array('ISA');
417 }
418  
419 427 ▶sub included {
Subroutine included: called CC=1 SCAR=0.0
Pod documented
420 427 my ($self) = @_;
421  
422 427 return $INC{$self->format('path', '%s.pm')};
423 }
424  
425 1 ▶sub inject {
Subroutine inject: called CC=2 SCAR=7.1
Pod documented
426 1 my ($self, $name, $coderef) = @_;
427  
428 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
429 29 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
430  
431 1 my $class = $self->package;
432  
433 0 ▶ return *{"${class}::${name}"} = $coderef || sub{$class};
Subroutine __ANON__: not called CC=1 SCAR=1.2
Condition33%1/3
$coderef || sub { $class; }
l!l&&r!l&&!r
100
MC/DC0%0/2
$coderef || sub { $class; }
$coderef sub { $class; }
Truth table33%1/3
A || B
A= $coderefB= sub { $class; }
ABresult
1X1
011
000
434 }
435  
436 2 ▶sub integrates {
Subroutine integrates: called CC=2 SCAR=7.1
Pod documented
437 2 my ($self) = @_;
438  
439 2 my $roles = $self->meta->roles;
440  
441 2 ▶ return $roles || [];
Condition50%1/2
$roles || []
l!l
20
MC/DC0%0/1
$roles || []
$roles
Truth table50%1/2
A
A= $roles
Aresult
11
00
442 }
443  
444 7 ▶sub lfile {
Subroutine lfile: called CC=1 SCAR=0.0
Pod documented
445 7 my ($self) = @_;
446  
447 7 return $self->format('path', '%s.pm');
448 }
449  
450 249 ▶sub load {
Subroutine load: called CC=5 SCAR=16.2
Pod documented
451 249 my ($self) = @_;
452  
453 249 my $class = $self->package;
454  
455 249 ▶ return $class if $class eq 'main' || $self->loaded;
Branch: 1 branch
BranchTrueFalseTotal
if $class eq "main" or $self->loaded 223 26 249
Condition66%2/3
$class eq "main" or $self->loaded
l!l&&r!l&&!r
022326
MC/DC50%1/2
$class eq "main" or $self->loaded
$class eq "main" $self->loaded
Truth table66%2/3
A or B
A= $class eq "main"B= $self->loaded
ABresult
1X1
011
000
456  
457 26 my $error = do{local $@; eval "require $class"; $@};
458  
459 26 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 10 16 26
460 10 ▶ $self->error_on_load({error => $error || 'cause unknown', package => $class})
Condition50%1/2
$error || 'cause unknown'
l!l
100
MC/DC0%0/1
$error || 'cause unknown'
$error
Truth table50%1/2
A
A= $error
Aresult
11
00
461 ->input($self)
462 ->output($error)
463 ->throw;
464 }
465  
466 16 return $class;
467 }
468  
469 426 ▶sub loaded {
Subroutine loaded: called CC=3 SCAR=11.0
Pod documented
470 426 my ($self) = @_;
471  
472 426 ▶ return ($self->included || @{$self->routines}) ? true : false;
Branch: 1 branch
BranchTrueFalseTotal
$self->included || @{$self->routines;} ? : 384 42 426
Condition100%3/3
$self->included or @{$self->routines;}
l!l&&r!l&&!r
14623842
MC/DC100%2/2
$self->included or @{$self->routines;}
$self->included @{$self->routines;}
Truth table100%3/3
A or B
A= $self->includedB= @{$self->routines;}
ABresult
1X1
011
000
473 }
474  
475 5 ▶sub locate {
Subroutine locate: called CC=3 SCAR=11.0
Pod documented
476 5 my ($self) = @_;
477  
478 5 my $found = '';
479  
480 5 my $file = $self->format('path', '%s.pm');
481  
482 5 for my $path (@INC) {
483 20 ▶ do { $found = "$path/$file"; last } if -f "$path/$file";
Branch: 1 branch
BranchTrueFalseTotal
if (-f "$path/$file") 4 16 20
484 }
485  
486 5 return $found;
487 }
488  
489 5 ▶sub meta {
Subroutine meta: called CC=1 SCAR=0.0
Pod documented
490 5 my ($self) = @_;
491  
492 5 require Venus::Meta;
493  
494 5 return Venus::Meta->new(name => $self->package);
495 }
496  
497 1 ▶sub mock {
Subroutine mock: called CC=2 SCAR=7.0
Pod documented
498 1 my ($self) = @_;
499  
500 1 my $name = sprintf '%s::Mock::%04d::%s', $self->class, ++$SERIAL, $self->package;
501  
502 1 my $space = $self->class->new($name);
503  
504 1 ▶ $space->do('init')->array('ISA', $self->package) if !$space->loaded;
Branch: 1 branch
BranchTrueFalseTotal
unless $space->loaded 1 0 1
505  
506 1 return $space;
507 }
508  
509 1 ▶sub name {
Subroutine name: called CC=1 SCAR=0.0
Pod documented
510 1 my ($self) = @_;
511  
512 1 return $self->package;
513 }
514  
515 3 ▶sub parent {
Subroutine parent: called CC=2 SCAR=7.0
Pod documented
516 3 my ($self) = @_;
517  
518 3 my @parts = @{$self->parse};
519  
520 3 ▶ pop @parts if @parts > 1;
Branch: 1 branch
BranchTrueFalseTotal
if @parts > 1 3 0 3
521  
522 3 my $class = $self->class;
523  
524 3 return $class->new(join '/', @parts);
525 }
526  
527 18 ▶sub parse {
Subroutine parse: called CC=1 SCAR=0.0
Pod documented
528 18 my ($self) = @_;
529  
530 return [
531 18 map ucfirst,
532 map join('', map(ucfirst, split /[-_]/)),
533 split /[^-_a-zA-Z0-9.]+/,
534 $self->path
535 ];
536 }
537  
538 7 ▶sub parts {
Subroutine parts: called CC=1 SCAR=0.0
Pod documented
539 7 my ($self) = @_;
540  
541 7 return $self->parse;
542 }
543  
544 44 ▶sub patch {
Subroutine patch: called CC=2 SCAR=7.0
Pod documented
545 44 my ($self, $name, $code) = @_;
546  
547 44 ▶ my $patched = $self->{patched} ||= {};
Condition50%1/2
$self->{"patched"} ||= {}
l!l
044
MC/DC0%0/1
$self->{"patched"} ||= {}
$self->{"patched"}
Truth table50%1/2
A
A= $self->{"patched"}
Aresult
11
00
548  
549 44 my $orig = $self->swap($name, $code);
550  
551 44 $patched->{$name} = $orig;
552  
553 44 return $self;
554 }
555  
556 8 ▶sub patched {
Subroutine patched: called CC=4 SCAR=13.9
Pod documented
557 8 my ($self, $name) = @_;
558  
559 8 my $patched = $self->{patched};
560  
561 8 ▶ return false if !$patched;
Branch: 1 branch
BranchTrueFalseTotal
unless $patched 2 6 8
562  
563 6 ▶ return $name ? ($patched->{$name} ? true : false) : true;
Branch: 2 branches
BranchTrueFalseTotal
$name ? : 2 4 6
$patched->{$name} ? : 1 1 2
564 }
565  
566 2 ▶sub pfile {
Subroutine pfile: called CC=1 SCAR=0.0
Pod documented
567 2 my ($self) = @_;
568  
569 2 return $self->format('path', '%s.pod');
570 }
571  
572 3 ▶sub prepend {
Subroutine prepend: called CC=1 SCAR=0.0
Pod documented
573 3 my ($self, @args) = @_;
574  
575 3 my $class = $self->class;
576  
577 3 my $path = join '/',
578 (map $class->new($_)->path, @args), $self->path;
579  
580 3 return $class->new($path);
581 }
582  
583 40 ▶sub purge {
Subroutine purge: called CC=3 SCAR=11.0
Pod documented
584 40 my ($self) = @_;
585  
586 40 ▶ return $self if $self->unloaded;
Branch: 1 branch
BranchTrueFalseTotal
if $self->unloaded 0 40 40
587  
588 40 my $package = $self->package;
589  
590 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
591  
592 40 for my $name (grep !/\A[^:]+::\z/, keys %{"${package}::"}) {
593 1442 undef *{"${package}::${name}"}; delete ${"${package}::"}{$name};
594 }
595  
596 40 delete $INC{$self->format('path', '%s.pm')};
597  
598 40 return $self;
599 }
600  
601 1 ▶sub rebase {
Subroutine rebase: called CC=1 SCAR=0.0
Pod documented
602 1 my ($self, @args) = @_;
603  
604 1 my $class = $self->class;
605  
606 1 my $path = join '/', map $class->new($_)->path, @args;
607  
608 1 return $class->new($self->basename)->prepend($path);
609 }
610  
611 2 ▶sub reload {
Subroutine reload: called CC=1 SCAR=0.0
Pod documented
612 2 my ($self) = @_;
613  
614 2 $self->unload;
615  
616 2 return $self->load;
617 }
618  
619 4 ▶sub require {
Subroutine require: called CC=2 SCAR=7.1
Pod documented
620 4 my ($self, $target) = @_;
621  
622 4 ▶ $target = "'$target'" if -f $target;
Branch: 1 branch
BranchTrueFalseTotal
if -f $target 0 4 4
623  
624 4 return $self->eval("require $target");
625 }
626  
627 1 ▶sub root {
Subroutine root: called CC=1 SCAR=0.0
Pod documented
628 1 my ($self) = @_;
629  
630 1 return $self->parse->[0];
631 }
632  
633 98 ▶sub routine {
Subroutine routine: called CC=2 SCAR=6.9
Pod documented
634 98 my ($self, $name, $code) = @_;
635  
636 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
637  
638 98 my $class = $self->package;
639  
640 29 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
641  
642 98 ▶ *{"${class}::${name}"} = $code if $code;
Branch: 1 branch
BranchTrueFalseTotal
if $code 97 1 98
643  
644 98 return *{"${class}::${name}"}{"CODE"};
645 }
646  
647 281 ▶sub routines {
Subroutine routines: called CC=1 SCAR=0.0
Pod documented
648 281 my ($self) = @_;
649  
650 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
651  
652 281 my $class = $self->package;
653  
654 return [
655 9353 sort grep *{"${class}::$_"}{"CODE"},
656 281 grep /^[_a-zA-Z]\w*$/, keys %{"${class}::"}
657 ];
658 }
659  
660 7 ▶sub scalar {
Subroutine scalar: called CC=2 SCAR=6.9
Pod documented
661 7 my ($self, $name, @data) = @_;
662  
663 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
664  
665 7 my $class = $self->package;
666  
667 29 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
668  
669 7 ▶ ${"${class}::${name}"} = $data[0] if @data;
Branch: 1 branch
BranchTrueFalseTotal
if @data 1 6 7
670  
671 7 return ${"${class}::${name}"};
672 }
673  
674 2 ▶sub scalars {
Subroutine scalars: called CC=1 SCAR=0.0
Pod documented
675 2 my ($self) = @_;
676  
677 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
678  
679 2 my $class = $self->package;
680  
681 return [
682 22 sort grep defined ${"${class}::$_"},
683 2 grep /^[_a-zA-Z]\w*$/, keys %{"${class}::"}
684 ];
685 }
686  
687 7 ▶sub scrub {
Subroutine scrub: called CC=3 SCAR=11.0
Pod documented
688 7 my ($self) = @_;
689  
690 7 ▶ return $self if $self->unloaded;
Branch: 1 branch
BranchTrueFalseTotal
if $self->unloaded 0 7 7
691  
692 7 my $package = $self->package;
693  
694 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
695  
696 7 my $skip = qr/\A(
697 AUTOLOAD|BEGIN|CHECK|DESTROY|END|EXPORT|EXPORT_OK|EXPORT_TAGS|
698 IMPORT|INIT|ISA|UNITCHECK|VERSION|
699 import|unimport|
700 [^:]+::
701 )\z/x;
702  
703 7 for my $name (grep !/$skip/, keys %{"${package}::"}) {
704 107 undef *{"${package}::${name}"};
705 }
706  
707 7 delete $INC{$self->format('path', '%s.pm')};
708  
709 7 return $self;
710 }
711  
712 1 ▶sub sibling {
Subroutine sibling: called CC=1 SCAR=0.0
Pod documented
713 1 my ($self, @args) = @_;
714  
715 1 return $self->parent->append(@args);
716 }
717  
718 1 ▶sub siblings {
Subroutine siblings: called CC=5 SCAR=16.1
Pod documented
719 1 my ($self) = @_;
720  
721 1 my %list;
722 my $path;
723 1 my $type;
724  
725 1 $path = quotemeta $self->parent->path;
726 1 $type = 'pm';
727  
728 1 my $regexp = qr/$path\/[^\/]+\.$type/;
729  
730 1 for my $item (keys %INC) {
731 250 ▶ $list{$item}++ if $item =~ /$regexp$/;
Branch: 1 branch
BranchTrueFalseTotal
if $item =~ /$regexp$/u 3 247 250
732 }
733  
734 1 my %seen;
735  
736 1 for my $dir (@INC) {
737 11 ▶ next if $seen{$dir}++;
Branch: 1 branch
BranchTrueFalseTotal
if $seen{$dir}++ 3 8 11
738  
739 8 my $re = quotemeta $dir;
740 2 map { s/^$re\///; $list{$_}++ }
741 8 grep !$list{$_}, glob "$dir/@{[$self->path]}/*.$type";
742 }
743  
744 1 my $class = $self->class;
745  
746 return [
747 map $class->new($_),
748 1 map {s/(.*)\.$type$/$1/r}
749 sort keys %list
750 ];
751 }
752  
753 4 ▶sub splice {
Subroutine splice: called CC=4 SCAR=13.9
Pod documented
754 4 my ($self, $offset, $length, @list) = @_;
755  
756 4 my $class = $self->class;
757 4 my $parts = $self->parts;
758  
759 4 ▶ if (@list) {
Branch: 3 branches
BranchTrueFalseTotal
if (@list) { } 1 3 4
elsif (defined $length) { } 2 1 3
elsif (defined $offset) { } 1 0 1
760 1 CORE::splice(@{$parts}, $offset, $length, @list);
761 }
762 elsif (defined $length) {
763 2 CORE::splice(@{$parts}, $offset, $length);
764 }
765 elsif (defined $offset) {
766 1 CORE::splice(@{$parts}, $offset);
767 }
768  
769 4 return $class->new(join '/', @$parts);
770 }
771  
772 46 ▶sub swap {
Subroutine swap: called CC=3 SCAR=11.0
Pod documented
773 46 my ($self, $name, $code) = @_;
774  
775 46 my $orig = (my $package = $self->package)->can($name);
776  
777 46 ▶ return $orig if !$code;
Branch: 1 branch
BranchTrueFalseTotal
unless $code 0 46 46
778  
779 46 ▶ if (!$orig) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($orig) 1 45 46
780 1 $self->error_on_swap({package => $package, routine => $name})->throw;
781 }
782  
783 45 ▶ $self->routine($name, sub {$code->($orig, @_)});
Subroutine __ANON__: called CC=1 SCAR=0.0
784  
785 45 return $orig;
786 }
787  
788 7 ▶sub tfile {
Subroutine tfile: called CC=1 SCAR=0.0
Pod documented
789 7 my ($self) = @_;
790  
791 7 return $self->format('label', '%s.t');
792 }
793  
794 51 ▶sub tryload {
Subroutine tryload: called CC=1 SCAR=0.0
Pod documented
795 51 my ($self) = @_;
796  
797 51 return do { local $@; eval { $self->load }; int!$@ };
798 }
799  
800 3 ▶sub use {
Subroutine use: called CC=3 SCAR=11.0
Pod documented
801 3 my ($self, $target, @params) = @_;
802  
803 3 my $version;
804  
805 3 ▶ ($target, $version) = @$target if ref $target eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
if ref $target eq "ARRAY" 1 2 3
806  
807 3 $self->require($target);
808  
809 3 require Scalar::Util;
810  
811 3 ▶ my @statement = (
Branch: 1 branch
BranchTrueFalseTotal
&Scalar::Util::looks_like_number($version) ? : 1 2 3
812 'no strict "subs";',
813 (
814 Scalar::Util::looks_like_number($version)
815 ? "${target}->VERSION($version);" : ()
816 ),
817 'sub{ my ($target, @params) = @_; $target->import(@params)}'
818 );
819  
820 3 $self->eval(join("\n", @statement))->($target, @params);
821  
822 2 return $self;
823 }
824  
825 1 ▶sub variables {
Subroutine variables: called CC=1 SCAR=0.0
Pod documented
826 1 my ($self) = @_;
827  
828 1 return [map [$_, [sort @{$self->$_}]], qw(arrays hashes scalars)];
829 }
830  
831 3 ▶sub version {
Subroutine version: called CC=1 SCAR=0.0
Pod documented
832 3 my ($self) = @_;
833  
834 3 return $self->scalar('VERSION');
835 }
836  
837 101 ▶sub unload {
Subroutine unload: called CC=3 SCAR=11.0
Pod documented
838 101 my ($self) = @_;
839  
840 101 ▶ return $self if $self->unloaded;
Branch: 1 branch
BranchTrueFalseTotal
if $self->unloaded 3 98 101
841  
842 98 my $package = $self->package;
843  
844 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
845  
846 98 for my $name (grep !/\A[^:]+::\z/, keys %{"${package}::"}) {
847 5046 undef *{"${package}::${name}"};
848 }
849  
850 98 delete $INC{$self->format('path', '%s.pm')};
851  
852 98 return $self;
853 }
854  
855 150 ▶sub unloaded {
Subroutine unloaded: called CC=2 SCAR=6.9
Pod documented
856 150 my ($self) = @_;
857  
858 150 ▶ return $self->loaded ? false : true;
Branch: 1 branch
BranchTrueFalseTotal
$self->loaded ? : 146 4 150
859 }
860  
861 40 ▶sub unpatch {
Subroutine unpatch: called CC=6 SCAR=17.9
Pod documented
862 40 my ($self, @names) = @_;
863  
864 40 ▶ my $patched = $self->{patched} ||= {};
Condition50%1/2
$self->{"patched"} ||= {}
l!l
400
MC/DC0%0/1
$self->{"patched"} ||= {}
$self->{"patched"}
Truth table50%1/2
A
A= $self->{"patched"}
Aresult
11
00
865  
866 40 ▶ @names = keys %{$patched} if !@names;
Branch: 1 branch
BranchTrueFalseTotal
unless @names 34 6 40
867  
868 40 for my $name (@names) {
869 40 ▶ my $orig = delete $patched->{$name} or next;
Branch: 1 branch
BranchTrueFalseTotal
my $orig = delete $patched->{$name} or next 39 1 40
870 39 $self->routine($name, $orig);
871 }
872  
873 40 ▶ delete $self->{patched} if !keys %{$patched};
Branch: 1 branch
BranchTrueFalseTotal
unless keys %{$patched;} 39 1 40
874  
875 40 return $self;
876 }
877  
878 7 ▶sub visible {
Subroutine visible: called CC=2 SCAR=6.9
Pod documented
879 7 my ($self) = @_;
880  
881 29 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
882  
883 7 my $package = $self->package;
884  
885 7 ▶ return (grep !/\A[^:]+::\z/, keys %{"${package}::"}) ? true : false;
Branch: 1 branch
BranchTrueFalseTotal
grep((!/\A[^:]+::\z/u), keys %{"${package}::";}) ? : 5 2 7
886 }
887  
888 # ERRORS
889  
890 2 ▶sub error_on_call_missing {
Subroutine error_on_call_missing: called CC=1 SCAR=0.0
Pod undocumented
891 2 my ($self, $data) = @_;
892  
893 2 my $error = $self->error->sysinfo;
894  
895 2 my $message = 'Unable to locate class method "{{routine}}" via package "{{package}}"';
896  
897 2 $error->name('on.call.missing');
898 2 $error->message($message);
899 2 $error->offset(1);
900 2 $error->stash($data);
901 2 $error->reset;
902  
903 2 return $error;
904 }
905  
906 0 ▶sub error_on_call_undefined {
Subroutine error_on_call_undefined: not called CC=1 SCAR=6.9
Pod undocumented
907 0 my ($self, $data) = @_;
908  
909 0 my $error = $self->error->sysinfo;
910  
911 0 my $message = join ' ', 'Attempt to call undefined class method',
912 'in package "{{package}}"';
913  
914 0 $error->name('on.call.undefined');
915 0 $error->message($message);
916 0 $error->offset(1);
917 0 $error->stash($data);
918 0 $error->reset;
919  
920 0 return $error;
921 }
922  
923 1 ▶sub error_on_around_missing {
Subroutine error_on_around_missing: called CC=1 SCAR=0.0
Pod undocumented
924 1 my ($self, $data) = @_;
925  
926 1 my $error = $self->error->sysinfo;
927  
928 1 my $message = join ' ', 'Unable to locate object method "{{routine}}"',
929 'via package "{{package}}"';
930  
931 1 $error->name('on.around.missing');
932 1 $error->message($message);
933 1 $error->offset(1);
934 1 $error->stash($data);
935 1 $error->reset;
936  
937 1 return $error;
938 }
939  
940 2 ▶sub error_on_cop_missing {
Subroutine error_on_cop_missing: called CC=1 SCAR=0.0
Pod undocumented
941 2 my ($self, $data) = @_;
942  
943 2 my $error = $self->error->sysinfo;
944  
945 2 my $message = join ' ', 'Unable to locate object method "{{routine}}"',
946 'via package "{{package}}"';
947  
948 2 $error->name('on.cop.missing');
949 2 $error->message($message);
950 2 $error->offset(1);
951 2 $error->stash($data);
952 2 $error->reset;
953  
954 2 return $error;
955 }
956  
957 0 ▶sub error_on_cop_undefined {
Subroutine error_on_cop_undefined: not called CC=1 SCAR=6.9
Pod undocumented
958 0 my ($self, $data) = @_;
959  
960 0 my $error = $self->error->sysinfo;
961  
962 0 my $message = join ' ', 'Attempt to cop undefined object method',
963 'from package "{{package}}"';
964  
965 0 $error->name('on.cop.undefined');
966 0 $error->message($message);
967 0 $error->offset(1);
968 0 $error->stash($data);
969 0 $error->reset;
970  
971 0 return $error;
972 }
973  
974 3 ▶sub error_on_eval {
Subroutine error_on_eval: called CC=1 SCAR=0.0
Pod undocumented
975 3 my ($self, $data) = @_;
976  
977 3 my $error = $self->error->sysinfo;
978  
979 3 my $message = $data->{error};
980  
981 3 $error->name('on.eval');
982 3 $error->message($message);
983 3 $error->offset(1);
984 3 $error->stash($data);
985 3 $error->reset;
986  
987 3 return $error;
988 }
989  
990 10 ▶sub error_on_load {
Subroutine error_on_load: called CC=1 SCAR=0.0
Pod undocumented
991 10 my ($self, $data) = @_;
992  
993 10 my $error = $self->error->sysinfo;
994  
995 10 my $message = 'Error attempting to load {{package}}: "{{error}}"';
996  
997 10 $error->name('on.load');
998 10 $error->message($message);
999 10 $error->offset(1);
1000 10 $error->stash($data);
1001 10 $error->reset;
1002  
1003 10 return $error;
1004 }
1005  
1006 1 ▶sub error_on_swap {
Subroutine error_on_swap: called CC=1 SCAR=0.0
Pod undocumented
1007 1 my ($self, $data) = @_;
1008  
1009 1 my $error = $self->error->sysinfo;
1010  
1011 1 my $message = 'Attempt to swap undefined subroutine in package "{{package}}"';
1012  
1013 1 $error->name('on.swap');
1014 1 $error->message($message);
1015 1 $error->offset(1);
1016 1 $error->stash($data);
1017 1 $error->reset;
1018  
1019 1 return $error;
1020 }
1021  
1022 29 1;
1023  
1024  
1025  
1026 =head1 NAME
1027  
1028 Venus::Space - Space Class
1029  
1030 =cut
1031  
1032 =head1 ABSTRACT
1033  
1034 Space Class for Perl 5
1035  
1036 =cut
1037  
1038 =head1 SYNOPSIS
1039  
1040 package main;
1041  
1042 use Venus::Space;
1043  
1044 my $space = Venus::Space->new('foo/bar');
1045  
1046 # $space->package; # Foo::Bar
1047  
1048 =cut
1049  
1050 =head1 DESCRIPTION
1051  
1052 This package provides methods for parsing and manipulating package namespaces.
1053  
1054 =cut
1055  
1056 =head1 INHERITS
1057  
1058 This package inherits behaviors from:
1059  
1060 L<Venus::Name>
1061  
1062 =cut
1063  
1064 =head1 METHODS
1065  
1066 This package provides the following methods:
1067  
1068 =cut
1069  
1070 =head2 after
1071  
1072 after(string $name, coderef $code) (coderef)
1073  
1074 The after method installs a method modifier that executes after the original
1075 method, allowing you to perform actions after a method call. B<Note:> The
1076 return value of the modifier routine is ignored; the wrapped method always
1077 returns the value from the original method. Modifiers are executed in the order
1078 they are stacked.
1079  
1080 I<Since C<4.15>>
1081  
1082 =over 4
1083  
1084 =item after example 1
1085  
1086 package main;
1087  
1088 use Venus::Space;
1089  
1090 my $space = Venus::Space->new('foo/bar');
1091  
1092 $space->do('init');
1093  
1094 $space->routine('execute', sub {
1095 my ($self) = @_;
1096 return [@_];
1097 });
1098  
1099 my $after = $space->after('execute', sub {
1100 my ($self) = @_;
1101 $self->{executed} = 1;
1102 });
1103  
1104 # sub { ... }
1105  
1106 =back
1107  
1108 =over 4
1109  
1110 =item after example 2
1111  
1112 package main;
1113  
1114 use Venus::Space;
1115  
1116 my $space = Venus::Space->new('foo/bar');
1117  
1118 $space->do('init');
1119  
1120 $space->routine('new', sub {
1121 my ($class) = @_;
1122 return bless {}, $class;
1123 });
1124  
1125 $space->routine('execute', sub {
1126 my ($self) = @_;
1127 $self->{executed} = 1;
1128 return $self;
1129 });
1130  
1131 $space->after('execute', sub {
1132 my ($self) = @_;
1133 return [@_];
1134 });
1135  
1136 my $object = $space->build({});
1137  
1138 my $result = $object->execute;
1139  
1140 # bless({executed => 1}, 'Foo::Bar')
1141  
1142 =back
1143  
1144 =cut
1145  
1146 =head2 all
1147  
1148 all(string $method, any @args) (within[arrayref, tuple[string, any]])
1149  
1150 The all method executes any available method on the instance and all instances
1151 representing packages inherited by the package represented by the invocant.
1152 This method supports dispatching, i.e. providing a method name and arguments
1153 whose return value will be acted on by this method.
1154  
1155 I<Since C<0.01>>
1156  
1157 =over 4
1158  
1159 =item all example 1
1160  
1161 package main;
1162  
1163 use Venus::Space;
1164  
1165 my $space = Venus::Space->new('Venus');
1166  
1167 my $all = $space->all('id');
1168  
1169 # [["Venus", "Venus"]]
1170  
1171 =back
1172  
1173 =over 4
1174  
1175 =item all example 2
1176  
1177 package main;
1178  
1179 use Venus::Space;
1180  
1181 my $space = Venus::Space->new('Venus/Space');
1182  
1183 my $all = $space->all('inherits');
1184  
1185 # [
1186 # [
1187 # "Venus::Space", ["Venus::Name"]
1188 # ],
1189 # [
1190 # "Venus::Name", ["Venus::Kind::Utility"]
1191 # ],
1192 # ]
1193  
1194 =back
1195  
1196 =over 4
1197  
1198 =item all example 3
1199  
1200 package main;
1201  
1202 use Venus::Space;
1203  
1204 my $space = Venus::Space->new('Venus/Space');
1205  
1206 my $all = $space->all('locate');
1207  
1208 # [
1209 # [
1210 # "Venus::Space",
1211 # "/path/to/lib/Venus/Space.pm",
1212 # ],
1213 # [
1214 # "Venus::Name",
1215 # "/path/to/lib/Venus/Name.pm",
1216 # ],
1217 # ]
1218  
1219 =back
1220  
1221 =cut
1222  
1223 =head2 append
1224  
1225 append(string @path) (Venus::Space)
1226  
1227 The append method modifies the object by appending to the package namespace
1228 parts.
1229  
1230 I<Since C<0.01>>
1231  
1232 =over 4
1233  
1234 =item append example 1
1235  
1236 # given: synopsis;
1237  
1238 my $append = $space->append('baz');
1239  
1240 # bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
1241  
1242 =back
1243  
1244 =over 4
1245  
1246 =item append example 2
1247  
1248 # given: synopsis;
1249  
1250 my $append = $space->append('baz', 'bax');
1251  
1252 # bless({ value => "Foo/Bar/Baz/Bax" }, "Venus::Space")
1253  
1254 =back
1255  
1256 =cut
1257  
1258 =head2 around
1259  
1260 around(string $name, coderef $code) (coderef)
1261  
1262 The around method installs a method modifier that wraps around the original
1263 method. The callback provided will recieve the original routine as its first
1264 argument. This method will raise an exception if the source routine does not
1265 exist. Modifiers are executed in the order they are stacked.
1266  
1267 I<Since C<4.15>>
1268  
1269 =over 4
1270  
1271 =item around example 1
1272  
1273 package main;
1274  
1275 use Venus::Space;
1276  
1277 my $space = Venus::Space->new('foo/bar');
1278  
1279 $space->do('init');
1280  
1281 $space->routine('execute', sub {
1282 my ($self, $value) = @_;
1283 return [$value];
1284 });
1285  
1286 my $around = $space->around('execute', sub {
1287 my ($orig, $self, $value) = @_;
1288 my $result = $self->$orig($value);
1289 push @$result, 'wrapped';
1290 return $result;
1291 });
1292  
1293 # sub { ... }
1294  
1295 =back
1296  
1297 =over 4
1298  
1299 =item around example 2
1300  
1301 package main;
1302  
1303 use Venus::Space;
1304  
1305 my $space = Venus::Space->new('foo/bar');
1306  
1307 $space->do('init');
1308  
1309 $space->routine('execute', sub {
1310 my ($self, $value) = @_;
1311 return [$value];
1312 });
1313  
1314 $space->around('execute', sub {
1315 my ($orig, $self, $value) = @_;
1316 my $result = $self->$orig($value);
1317 push @$result, 'wrapped';
1318 return $result;
1319 });
1320  
1321 my $object = $space->build({});
1322  
1323 my $result = $object->execute('test');
1324  
1325 # ['test', 'wrapped']
1326  
1327 =back
1328  
1329 =over 4
1330  
1331 =item B<may raise> L<Venus::Space::Error> C<on.around.missing>
1332  
1333 package main;
1334  
1335 use Venus::Space;
1336  
1337 my $space = Venus::Space->new('Venus::Check');
1338  
1339 $space->around('not_a_method');
1340  
1341 # Error! (on.around.missing)
1342  
1343 =back
1344  
1345 =cut
1346  
1347 =head2 array
1348  
1349 array(string $name, any @data) (arrayref)
1350  
1351 The array method gets or sets the value for the given package array variable name.
1352  
1353 I<Since C<0.01>>
1354  
1355 =over 4
1356  
1357 =item array example 1
1358  
1359 # given: synopsis;
1360  
1361 package Foo::Bar;
1362  
1363 our @handler = 'start';
1364  
1365 package main;
1366  
1367 my $array = $space->array('handler');
1368  
1369 # ["start"]
1370  
1371 =back
1372  
1373 =over 4
1374  
1375 =item array example 2
1376  
1377 # given: synopsis;
1378  
1379 package Foo::Bar;
1380  
1381 our @handler = 'start';
1382  
1383 package main;
1384  
1385 my $array = $space->array('handler', 'restart');
1386  
1387 # ["restart"]
1388  
1389 =back
1390  
1391 =cut
1392  
1393 =head2 arrays
1394  
1395 arrays() (arrayref)
1396  
1397 The arrays method searches the package namespace for arrays and returns their
1398 names.
1399  
1400 I<Since C<0.01>>
1401  
1402 =over 4
1403  
1404 =item arrays example 1
1405  
1406 # given: synopsis;
1407  
1408 package Foo::Bar;
1409  
1410 our @handler = 'start';
1411 our @initial = ('next', 'prev');
1412  
1413 package main;
1414  
1415 my $arrays = $space->arrays;
1416  
1417 # ["handler", "initial"]
1418  
1419 =back
1420  
1421 =cut
1422  
1423 =head2 attributes
1424  
1425 attributes() (arrayref)
1426  
1427 The attributes method searches the package namespace for attributes and returns
1428 their names. This will not include attributes from roles, mixins, or superclasses.
1429  
1430 I<Since C<1.02>>
1431  
1432 =over 4
1433  
1434 =item attributes example 1
1435  
1436 package Foo::Attrs;
1437  
1438 use Venus::Class 'attr';
1439  
1440 attr 'start';
1441 attr 'abort';
1442  
1443 package main;
1444  
1445 use Venus::Space;
1446  
1447 my $space = Venus::Space->new('foo/attrs');
1448  
1449 my $attributes = $space->attributes;
1450  
1451 # ["start", "abort"]
1452  
1453 =back
1454  
1455 =over 4
1456  
1457 =item attributes example 2
1458  
1459 package Foo::Base;
1460  
1461 use Venus::Class 'attr', 'base';
1462  
1463 attr 'start';
1464 attr 'abort';
1465  
1466 package Foo::Attrs;
1467  
1468 use Venus::Class 'attr';
1469  
1470 attr 'show';
1471 attr 'hide';
1472  
1473 package main;
1474  
1475 use Venus::Space;
1476  
1477 my $space = Venus::Space->new('foo/attrs');
1478  
1479 my $attributes = $space->attributes;
1480  
1481 # ["show", "hide"]
1482  
1483 =back
1484  
1485 =cut
1486  
1487 =head2 authority
1488  
1489 authority() (maybe[string])
1490  
1491 The authority method returns the C<AUTHORITY> declared on the target package,
1492 if any.
1493  
1494 I<Since C<0.01>>
1495  
1496 =over 4
1497  
1498 =item authority example 1
1499  
1500 package Foo::Boo;
1501  
1502 package main;
1503  
1504 use Venus::Space;
1505  
1506 my $space = Venus::Space->new('foo/boo');
1507  
1508 my $authority = $space->authority;
1509  
1510 # undef
1511  
1512 =back
1513  
1514 =over 4
1515  
1516 =item authority example 2
1517  
1518 package Foo::Boo;
1519  
1520 our $AUTHORITY = 'cpan:CPANERY';
1521  
1522 package main;
1523  
1524 use Venus::Space;
1525  
1526 my $space = Venus::Space->new('foo/boo');
1527  
1528 my $authority = $space->authority;
1529  
1530 # "cpan:CPANERY"
1531  
1532 =back
1533  
1534 =cut
1535  
1536 =head2 basename
1537  
1538 basename() (string)
1539  
1540 The basename method returns the last segment of the package namespace parts.
1541  
1542 I<Since C<0.01>>
1543  
1544 =over 4
1545  
1546 =item basename example 1
1547  
1548 # given: synopsis;
1549  
1550 my $basename = $space->basename;
1551  
1552 # "Bar"
1553  
1554 =back
1555  
1556 =cut
1557  
1558 =head2 before
1559  
1560 before(string $name, coderef $code) (coderef)
1561  
1562 The before method installs a method modifier that executes before the original
1563 method, allowing you to perform actions before a method call. B<Note:> The
1564 return value of the modifier routine is ignored; the wrapped method always
1565 returns the value from the original method. Modifiers are executed in the order
1566 they are stacked.
1567  
1568 I<Since C<4.15>>
1569  
1570 =over 4
1571  
1572 =item before example 1
1573  
1574 package main;
1575  
1576 use Venus::Space;
1577  
1578 my $space = Venus::Space->new('foo/bar');
1579  
1580 $space->do('init');
1581  
1582 $space->routine('execute', sub {
1583 my ($self) = @_;
1584 return [@_];
1585 });
1586  
1587 my $before = $space->before('execute', sub {
1588 my ($self) = @_;
1589 $self->{started} = 1;
1590 });
1591  
1592 # sub { ... }
1593  
1594 =back
1595  
1596 =over 4
1597  
1598 =item before example 2
1599  
1600 package main;
1601  
1602 use Venus::Space;
1603  
1604 my $space = Venus::Space->new('foo/bar');
1605  
1606 $space->do('init');
1607  
1608 $space->routine('new', sub {
1609 my ($class) = @_;
1610 return bless {tick => 1}, $class;
1611 });
1612  
1613 $space->routine('execute', sub {
1614 my ($self) = @_;
1615 $self->{tick} = $self->{step_1} = $self->{tick} + 1;
1616 return $self;
1617 });
1618  
1619 $space->before('execute', sub {
1620 my ($self) = @_;
1621 $self->{tick} = $self->{step_2} = $self->{tick} + 1;
1622 return;
1623 });
1624  
1625 my $object = $space->build({});
1626  
1627 my $result = $object->execute;
1628  
1629 # bless({step_1 => 3, step_2 => 2}, 'Foo::Bar')
1630  
1631 =back
1632  
1633 =cut
1634  
1635 =head2 blessed
1636  
1637 blessed(Ref $data) (Venus::Space)
1638  
1639 The blessed method blesses the given value into the package namespace and
1640 returns an object. If no value is given, an empty hashref is used.
1641  
1642 I<Since C<0.01>>
1643  
1644 =over 4
1645  
1646 =item blessed example 1
1647  
1648 # given: synopsis;
1649  
1650 package Foo::Bar;
1651  
1652 sub import;
1653  
1654 package main;
1655  
1656 my $blessed = $space->blessed;
1657  
1658 # bless({}, "Foo::Bar")
1659  
1660 =back
1661  
1662 =over 4
1663  
1664 =item blessed example 2
1665  
1666 # given: synopsis;
1667  
1668 package Foo::Bar;
1669  
1670 sub import;
1671  
1672 package main;
1673  
1674 my $blessed = $space->blessed({okay => 1});
1675  
1676 # bless({ okay => 1 }, "Foo::Bar")
1677  
1678 =back
1679  
1680 =cut
1681  
1682 =head2 build
1683  
1684 build(any @args) (Venus::Space)
1685  
1686 The build method attempts to call C<new> on the package namespace and if
1687 successful returns the resulting object.
1688  
1689 I<Since C<0.01>>
1690  
1691 =over 4
1692  
1693 =item build example 1
1694  
1695 # given: synopsis;
1696  
1697 package Foo::Bar::Baz;
1698  
1699 sub new {
1700 bless {}, $_[0];
1701 }
1702  
1703 package main;
1704  
1705 my $build = $space->child('baz')->build;
1706  
1707 # bless({}, "Foo::Bar::Baz")
1708  
1709 =back
1710  
1711 =over 4
1712  
1713 =item build example 2
1714  
1715 # given: synopsis;
1716  
1717 package Foo::Bar::Bax;
1718  
1719 sub new {
1720 bless $_[1], $_[0];
1721 }
1722  
1723 package main;
1724  
1725 my $build = $space->child('bax')->build({okay => 1});
1726  
1727 # bless({ okay => 1 }, "Foo::Bar::Bax")
1728  
1729 =back
1730  
1731 =over 4
1732  
1733 =item build example 3
1734  
1735 # given: synopsis;
1736  
1737 package Foo::Bar::Bay;
1738  
1739 sub new {
1740 bless $_[1], $_[0];
1741 }
1742  
1743 package main;
1744  
1745 my $build = $space->child('bay')->build([okay => 1]);
1746  
1747 # bless(["okay", 1], "Foo::Bar::Bay")
1748  
1749 =back
1750  
1751 =cut
1752  
1753 =head2 call
1754  
1755 call(any @args) (any)
1756  
1757 The call method attempts to call the given subroutine on the package namespace
1758 and if successful returns the resulting value.
1759  
1760 I<Since C<0.01>>
1761  
1762 =over 4
1763  
1764 =item call example 1
1765  
1766 package Foo;
1767  
1768 sub import;
1769  
1770 sub start {
1771 'started'
1772 }
1773  
1774 package main;
1775  
1776 use Venus::Space;
1777  
1778 my $space = Venus::Space->new('foo');
1779  
1780 my $result = $space->call('start');
1781  
1782 # "started"
1783  
1784 =back
1785  
1786 =over 4
1787  
1788 =item call example 2
1789  
1790 package Zoo;
1791  
1792 sub import;
1793  
1794 sub AUTOLOAD {
1795 bless {};
1796 }
1797  
1798 sub DESTROY {
1799 ; # noop
1800 }
1801  
1802 package main;
1803  
1804 use Venus::Space;
1805  
1806 my $space = Venus::Space->new('zoo');
1807  
1808 my $result = $space->call('start');
1809  
1810 # bless({}, "Zoo")
1811  
1812 =back
1813  
1814 =over 4
1815  
1816 =item call example 3
1817  
1818 package main;
1819  
1820 use Venus::Space;
1821  
1822 my $space = Venus::Space->new('foo');
1823  
1824 my $result = $space->call('missing');
1825  
1826 # Exception! (isa Venus::Space::Error) (see error_on_call_missing)
1827  
1828 =back
1829  
1830 =over 4
1831  
1832 =item B<may raise> L<Venus::Space::Error> C<on.call.missing>
1833  
1834 package main;
1835  
1836 use Venus::Space;
1837  
1838 my $space = Venus::Space->new('Venus::Check');
1839  
1840 $space->call('not_a_method');
1841  
1842 # Error! (on.call.missing)
1843  
1844 =back
1845  
1846 =cut
1847  
1848 =head2 chain
1849  
1850 chain(string | tuple[string, any] @steps) (any)
1851  
1852 The chain method chains one or more method calls and returns the result.
1853  
1854 I<Since C<0.01>>
1855  
1856 =over 4
1857  
1858 =item chain example 1
1859  
1860 package Chu::Chu0;
1861  
1862 sub import;
1863  
1864 package main;
1865  
1866 use Venus::Space;
1867  
1868 my $space = Venus::Space->new('Chu::Chu0');
1869  
1870 my $result = $space->chain('blessed');
1871  
1872 # bless({}, "Chu::Chu0")
1873  
1874 =back
1875  
1876 =over 4
1877  
1878 =item chain example 2
1879  
1880 package Chu::Chu1;
1881  
1882 sub new {
1883 bless pop;
1884 }
1885  
1886 sub frame {
1887 [@_]
1888 }
1889  
1890 package main;
1891  
1892 use Venus::Space;
1893  
1894 my $space = Venus::Space->new('Chu::Chu1');
1895  
1896 my $result = $space->chain(['blessed', {1..4}], 'frame');
1897  
1898 # [bless({ 1 => 2, 3 => 4 }, "Chu::Chu1")]
1899  
1900 =back
1901  
1902 =over 4
1903  
1904 =item chain example 3
1905  
1906 package Chu::Chu2;
1907  
1908 sub new {
1909 bless pop;
1910 }
1911  
1912 sub frame {
1913 [@_]
1914 }
1915  
1916 package main;
1917  
1918 use Venus::Space;
1919  
1920 my $space = Venus::Space->new('Chu::Chu2');
1921  
1922 my $chain = $space->chain('blessed', ['frame', {1..4}]);
1923  
1924 # [bless({}, "Chu::Chu2"), { 1 => 2, 3 => 4 }]
1925  
1926 =back
1927  
1928 =cut
1929  
1930 =head2 child
1931  
1932 child(string @path) (Venus::Space)
1933  
1934 The child method returns a new L<Venus::Space> object for the child
1935 package namespace.
1936  
1937 I<Since C<0.01>>
1938  
1939 =over 4
1940  
1941 =item child example 1
1942  
1943 # given: synopsis;
1944  
1945 my $child = $space->child('baz');
1946  
1947 # bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
1948  
1949 =back
1950  
1951 =cut
1952  
1953 =head2 children
1954  
1955 children() (within[arrayref, object])
1956  
1957 The children method searches C<%INC> and C<@INC> and retuns a list of
1958 L<Venus::Space> objects for each child namespace found (one level deep).
1959  
1960 I<Since C<0.01>>
1961  
1962 =over 4
1963  
1964 =item children example 1
1965  
1966 package main;
1967  
1968 use Venus::Space;
1969  
1970 my $space = Venus::Space->new('c_p_a_n');
1971  
1972 my $children = $space->children;
1973  
1974 # [
1975 # bless({ value => "CPAN/Author" }, "Venus::Space"),
1976 # bless({ value => "CPAN/Bundle" }, "Venus::Space"),
1977 # bless({ value => "CPAN/CacheMgr" }, "Venus::Space"),
1978 # ...
1979 # ]
1980  
1981 =back
1982  
1983 =cut
1984  
1985 =head2 cop
1986  
1987 cop(string $method, any @args) (coderef)
1988  
1989 The cop method attempts to curry the given subroutine on the package namespace
1990 and if successful returns a closure. This method supports dispatching, i.e.
1991 providing a method name and arguments whose return value will be acted on by
1992 this method.
1993  
1994 I<Since C<0.01>>
1995  
1996 =over 4
1997  
1998 =item cop example 1
1999  
2000 package Foo::Bar;
2001  
2002 sub import;
2003  
2004 sub handler {
2005 [@_]
2006 }
2007  
2008 package main;
2009  
2010 use Venus::Space;
2011  
2012 my $space = Venus::Space->new('foo/bar');
2013  
2014 my $code = $space->cop('handler', $space->blessed);
2015  
2016 # sub { Foo::Bar::handler(..., @_) }
2017  
2018 =back
2019  
2020 =over 4
2021  
2022 =item cop example 2
2023  
2024 package main;
2025  
2026 use Venus::Space;
2027  
2028 my $space = Venus::Space->new('foo/bar');
2029  
2030 my $code = $space->cop('missing', $space->blessed);
2031  
2032 # Exception! (isa Venus::Space::Error) (see error_on_cop_missing)
2033  
2034 =back
2035  
2036 =over 4
2037  
2038 =item B<may raise> L<Venus::Space::Error> C<on.cop.missing>
2039  
2040 package main;
2041  
2042 use Venus::Space;
2043  
2044 my $space = Venus::Space->new('Venus::Check');
2045  
2046 $space->cop('not_a_method');
2047  
2048 # Error! (on.cop.missing)
2049  
2050 =back
2051  
2052 =cut
2053  
2054 =head2 data
2055  
2056 data() (string)
2057  
2058 The data method attempts to read and return any content stored in the C<DATA>
2059 section of the package namespace.
2060  
2061 I<Since C<0.01>>
2062  
2063 =over 4
2064  
2065 =item data example 1
2066  
2067 # given: synopsis;
2068  
2069 my $data = $space->data;
2070  
2071 # ""
2072  
2073 =back
2074  
2075 =cut
2076  
2077 =head2 eval
2078  
2079 eval(string @data) (any)
2080  
2081 The eval method takes a list of strings and evaluates them under the namespace
2082 represented by the instance.
2083  
2084 I<Since C<0.01>>
2085  
2086 =over 4
2087  
2088 =item eval example 1
2089  
2090 package main;
2091  
2092 use Venus::Space;
2093  
2094 my $space = Venus::Space->new('foo');
2095  
2096 my $eval = $space->eval('our $VERSION = 0.01');
2097  
2098 # 0.01
2099  
2100 =back
2101  
2102 =over 4
2103  
2104 =item eval example 2
2105  
2106 package main;
2107  
2108 use Venus::Space;
2109  
2110 my $space = Venus::Space->new('foo');
2111  
2112 my $eval = $space->eval('die');
2113  
2114 # Exception! (isa Venus::Space::Error) (see error_on_eval)
2115  
2116 =back
2117  
2118 =over 4
2119  
2120 =item B<may raise> L<Venus::Space::Error> C<on.eval>
2121  
2122 package main;
2123  
2124 use Venus::Space;
2125  
2126 my $space = Venus::Space->new('Venus::Check');
2127  
2128 $space->eval('die');
2129  
2130 # Error! (on.eval)
2131  
2132 =back
2133  
2134 =cut
2135  
2136 =head2 explain
2137  
2138 explain() (string)
2139  
2140 The explain method returns the package name and is used in stringification
2141 operations.
2142  
2143 I<Since C<0.01>>
2144  
2145 =over 4
2146  
2147 =item explain example 1
2148  
2149 # given: synopsis;
2150  
2151 my $explain = $space->explain;
2152  
2153 # "Foo::Bar"
2154  
2155 =back
2156  
2157 =cut
2158  
2159 =head2 handle
2160  
2161 handle(string $name, coderef $code) (coderef)
2162  
2163 The handle method installs a method modifier that wraps a method similar to
2164 C<around>, providing low-level control over method execution. The modifier
2165 receives the original method as its first argument (which may be C<undef> if
2166 the method doesn't exist), followed by the method's arguments. This is the
2167 foundation for the other method modifiers (L<"before"|/before>,
2168 L<"after"|/after>, L<"around"|/around>). The modifiers are executed in the
2169 order they are stacked rather than maintaining a global registry.
2170  
2171 I<Since C<4.15>>
2172  
2173 =over 4
2174  
2175 =item handle example 1
2176  
2177 package main;
2178  
2179 use Venus::Space;
2180  
2181 my $space = Venus::Space->new('foo/bar');
2182  
2183 $space->do('init');
2184  
2185 $space->routine('execute', sub {
2186 my ($self, $value) = @_;
2187 return $value;
2188 });
2189  
2190 my $handle = $space->handle('execute', sub {
2191 my ($orig, $self, $value) = @_;
2192 return $orig ? $self->$orig($value * 2) : 0;
2193 });
2194  
2195 # sub { ... }
2196  
2197 =back
2198  
2199 =over 4
2200  
2201 =item handle example 2
2202  
2203 package main;
2204  
2205 use Venus::Space;
2206  
2207 my $space = Venus::Space->new('foo/bar');
2208  
2209 $space->do('init');
2210  
2211 $space->routine('execute', sub {
2212 my ($self, $value) = @_;
2213 return $value;
2214 });
2215  
2216 $space->handle('execute', sub {
2217 my ($orig, $self, $value) = @_;
2218 return $orig ? $self->$orig($value * 2) : 0;
2219 });
2220  
2221 my $object = $space->build({});
2222  
2223 my $result = $object->execute(5);
2224  
2225 # 10
2226  
2227 =back
2228  
2229 =over 4
2230  
2231 =item handle example 3
2232  
2233 package main;
2234  
2235 use Venus::Space;
2236  
2237 my $space = Venus::Space->new('foo/bar');
2238  
2239 $space->do('init');
2240  
2241 $space->handle('missing', sub {
2242 my ($orig, $self) = @_;
2243 return 'method does not exist';
2244 });
2245  
2246 my $object = $space->build({});
2247  
2248 my $result = $object->missing;
2249  
2250 # "method does not exist"
2251  
2252 =back
2253  
2254 =cut
2255  
2256 =head2 hash
2257  
2258 hash(string $name, any @data) (hashref)
2259  
2260 The hash method gets or sets the value for the given package hash variable name.
2261  
2262 I<Since C<0.01>>
2263  
2264 =over 4
2265  
2266 =item hash example 1
2267  
2268 # given: synopsis;
2269  
2270 package Foo::Bar;
2271  
2272 our %settings = (
2273 active => 1
2274 );
2275  
2276 package main;
2277  
2278 my $hash = $space->hash('settings');
2279  
2280 # { active => 1 }
2281  
2282 =back
2283  
2284 =over 4
2285  
2286 =item hash example 2
2287  
2288 # given: synopsis;
2289  
2290 package Foo::Bar;
2291  
2292 our %settings = (
2293 active => 1
2294 );
2295  
2296 package main;
2297  
2298 my $hash = $space->hash('settings', inactive => 1);
2299  
2300 # { inactive => 1 }
2301  
2302 =back
2303  
2304 =cut
2305  
2306 =head2 hashes
2307  
2308 hashes() (arrayref)
2309  
2310 The hashes method searches the package namespace for hashes and returns their
2311 names.
2312  
2313 I<Since C<0.01>>
2314  
2315 =over 4
2316  
2317 =item hashes example 1
2318  
2319 # given: synopsis;
2320  
2321 package Foo::Bar;
2322  
2323 our %defaults = (
2324 active => 0
2325 );
2326  
2327 our %settings = (
2328 active => 1
2329 );
2330  
2331 package main;
2332  
2333 my $hashes = $space->hashes;
2334  
2335 # ["defaults", "settings"]
2336  
2337 =back
2338  
2339 =cut
2340  
2341 =head2 hook
2342  
2343 hook(string $type, string $name, coderef $code) (coderef)
2344  
2345 The hook method is a specialized method modifier helper that applies a modifier
2346 (C<after>, C<around>, C<before>, or C<handle>) to a lifecycle hook method. It
2347 automatically uppercases the hook name, making it convenient for modifying
2348 Venus lifecycle hooks like C<BUILD>, C<BLESS>, C<BUILDARGS>, and C<AUDIT>.
2349  
2350 I<Since C<4.15>>
2351  
2352 =over 4
2353  
2354 =item hook example 1
2355  
2356 package Foo::Bar::Hook;
2357  
2358 use Venus::Class;
2359  
2360 package main;
2361  
2362 use Venus::Space;
2363  
2364 my $space = Venus::Space->new('foo/bar/hook');
2365  
2366 $space->routine('BUILD', sub {
2367 my ($self, $args) = @_;
2368 $self->{started} = 1;
2369 });
2370  
2371 my $hook = $space->hook('before', 'build', sub {
2372 my ($self) = @_;
2373 $self->{initialized} = 1;
2374 });
2375  
2376 # sub { ... }
2377  
2378 =back
2379  
2380 =over 4
2381  
2382 =item hook example 2
2383  
2384 package Foo::Bar::Hook;
2385  
2386 use Venus::Class;
2387  
2388 package main;
2389  
2390 use Venus::Space;
2391  
2392 my $space = Venus::Space->new('foo/bar/hook');
2393  
2394 $space->routine('BUILD', sub {
2395 my ($self, $args) = @_;
2396 $self->{started} = 1;
2397 });
2398  
2399 $space->hook('before', 'build', sub {
2400 my ($self) = @_;
2401 $self->{initialized} = 1;
2402 });
2403  
2404 my $object = $space->build({});
2405  
2406 # bless({initialized => 1, started => 1}, 'Foo::Bar')
2407  
2408 =back
2409  
2410 =cut
2411  
2412 =head2 id
2413  
2414 id() (string)
2415  
2416 The id method returns the fully-qualified package name as a label.
2417  
2418 I<Since C<0.01>>
2419  
2420 =over 4
2421  
2422 =item id example 1
2423  
2424 # given: synopsis;
2425  
2426 my $id = $space->id;
2427  
2428 # "Foo_Bar"
2429  
2430 =back
2431  
2432 =cut
2433  
2434 =head2 included
2435  
2436 included() (string | undef)
2437  
2438 The included method returns the path of the namespace if it exists in C<%INC>.
2439  
2440 I<Since C<0.01>>
2441  
2442 =over 4
2443  
2444 =item included example 1
2445  
2446 package main;
2447  
2448 use Venus::Space;
2449  
2450 my $space = Venus::Space->new('Venus/Space');
2451  
2452 my $included = $space->included;
2453  
2454 # "/path/to/lib/Venus/Space.pm"
2455  
2456 =back
2457  
2458 =cut
2459  
2460 =head2 inherits
2461  
2462 inherits() (arrayref)
2463  
2464 The inherits method returns the list of superclasses the target package is
2465 derived from.
2466  
2467 I<Since C<0.01>>
2468  
2469 =over 4
2470  
2471 =item inherits example 1
2472  
2473 package Bar;
2474  
2475 package main;
2476  
2477 use Venus::Space;
2478  
2479 my $space = Venus::Space->new('bar');
2480  
2481 my $inherits = $space->inherits;
2482  
2483 # []
2484  
2485 =back
2486  
2487 =over 4
2488  
2489 =item inherits example 2
2490  
2491 package Foo;
2492  
2493 sub import;
2494  
2495 package Bar;
2496  
2497 use base 'Foo';
2498  
2499 package main;
2500  
2501 use Venus::Space;
2502  
2503 my $space = Venus::Space->new('bar');
2504  
2505 my $inherits = $space->inherits;
2506  
2507 # ["Foo"]
2508  
2509 =back
2510  
2511 =cut
2512  
2513 =head2 init
2514  
2515 init() (string)
2516  
2517 The init method ensures that the package namespace is loaded and, whether
2518 created in-memory or on-disk, is flagged as being loaded and loadable.
2519  
2520 I<Since C<0.01>>
2521  
2522 =over 4
2523  
2524 =item init example 1
2525  
2526 package main;
2527  
2528 use Venus::Space;
2529  
2530 my $space = Venus::Space->new('kit');
2531  
2532 my $init = $space->init;
2533  
2534 # "Kit"
2535  
2536 =back
2537  
2538 =cut
2539  
2540 =head2 inject
2541  
2542 inject(string $name, maybe[coderef] $coderef) (any)
2543  
2544 The inject method monkey-patches the package namespace, installing a named
2545 subroutine into the package which can then be called normally, returning the
2546 fully-qualified subroutine name.
2547  
2548 I<Since C<0.01>>
2549  
2550 =over 4
2551  
2552 =item inject example 1
2553  
2554 package main;
2555  
2556 use Venus::Space;
2557  
2558 my $space = Venus::Space->new('kit');
2559  
2560 my $inject = $space->inject('build', sub { 'finished' });
2561  
2562 # *Kit::build
2563  
2564 =back
2565  
2566 =cut
2567  
2568 =head2 integrates
2569  
2570 integrates() (arrayref)
2571  
2572 The integrates method returns the list of roles integrated into the target
2573 package.
2574  
2575 I<Since C<1.30>>
2576  
2577 =over 4
2578  
2579 =item integrates example 1
2580  
2581 # given: synopsis
2582  
2583 package main;
2584  
2585 my $integrates = $space->integrates;
2586  
2587 # []
2588  
2589 =back
2590  
2591 =over 4
2592  
2593 =item integrates example 2
2594  
2595 package main;
2596  
2597 use Venus::Space;
2598  
2599 my $space = Venus::Space->new('Venus::Test');
2600  
2601 my $integrates = $space->integrates;
2602  
2603 # [...]
2604  
2605 =back
2606  
2607 =cut
2608  
2609 =head2 lfile
2610  
2611 lfile() (string)
2612  
2613 The lfile method returns a C<.pm> file path for the underlying package.
2614  
2615 I<Since C<1.30>>
2616  
2617 =over 4
2618  
2619 =item lfile example 1
2620  
2621 # given: synopsis
2622  
2623 package main;
2624  
2625 my $lfile = $space->lfile;
2626  
2627 # "Foo/Bar.pm"
2628  
2629 =back
2630  
2631 =cut
2632  
2633 =head2 load
2634  
2635 load() (string)
2636  
2637 The load method checks whether the package namespace is already loaded and if
2638 not attempts to load the package. If the package is not loaded and is not
2639 loadable, this method will throw an exception using confess. If the package is
2640 loadable, this method returns truthy with the package name. As a workaround for
2641 packages that only exist in-memory, if the package contains a C<new>, C<with>,
2642 C<meta>, or C<import> routine it will be recognized as having been loaded.
2643  
2644 I<Since C<0.01>>
2645  
2646 =over 4
2647  
2648 =item load example 1
2649  
2650 package main;
2651  
2652 use Venus::Space;
2653  
2654 my $space = Venus::Space->new('c_p_a_n');
2655  
2656 my $load = $space->load;
2657  
2658 # "CPAN"
2659  
2660 =back
2661  
2662 =over 4
2663  
2664 =item load example 2
2665  
2666 package main;
2667  
2668 use Venus::Space;
2669  
2670 my $space = Venus::Space->new('no/thing');
2671  
2672 my $load = $space->load;
2673  
2674 # Exception! (isa Venus::Space::Error) (see error_on_load)
2675  
2676 =back
2677  
2678 =over 4
2679  
2680 =item B<may raise> L<Venus::Space::Error> C<on.load>
2681  
2682 package main;
2683  
2684 use Venus::Space;
2685  
2686 my $space = Venus::Space->new('Fake::Package::NotReal');
2687  
2688 $space->load;
2689  
2690 # Error! (on.load)
2691  
2692 =back
2693  
2694 =cut
2695  
2696 =head2 loaded
2697  
2698 loaded() (boolean)
2699  
2700 The loaded method checks whether the package namespace is already loaded and
2701 returns truthy or falsy.
2702  
2703 I<Since C<0.01>>
2704  
2705 =over 4
2706  
2707 =item loaded example 1
2708  
2709 package main;
2710  
2711 use Venus::Space;
2712  
2713 my $space = Venus::Space->new('Kit');
2714  
2715 $space->init;
2716  
2717 $space->unload;
2718  
2719 my $loaded = $space->loaded;
2720  
2721 # 0
2722  
2723 =back
2724  
2725 =over 4
2726  
2727 =item loaded example 2
2728  
2729 package main;
2730  
2731 use Venus::Space;
2732  
2733 my $space = Venus::Space->new('Kit');
2734  
2735 $space->init;
2736  
2737 my $loaded = $space->loaded;
2738  
2739 # 1
2740  
2741 =back
2742  
2743 =cut
2744  
2745 =head2 locate
2746  
2747 locate() (string)
2748  
2749 The locate method checks whether the package namespace is available in
2750 C<@INC>, i.e. on disk. This method returns the file if found or an empty
2751 string.
2752  
2753 I<Since C<0.01>>
2754  
2755 =over 4
2756  
2757 =item locate example 1
2758  
2759 package main;
2760  
2761 use Venus::Space;
2762  
2763 my $space = Venus::Space->new('xyz');
2764  
2765 my $locate = $space->locate;
2766  
2767 # ""
2768  
2769 =back
2770  
2771 =over 4
2772  
2773 =item locate example 2
2774  
2775 package main;
2776  
2777 use Venus::Space;
2778  
2779 my $space = Venus::Space->new('data/dumper');
2780  
2781 $space->load;
2782  
2783 my $locate = $space->locate;
2784  
2785 # "/path/to/lib/Data/Dumper.pm"
2786  
2787 =back
2788  
2789 =cut
2790  
2791 =head2 meta
2792  
2793 meta() (Venus::Meta)
2794  
2795 The meta method returns a L<Venus::Meta> object representing the underlying
2796 package namespace. To access the meta object for the instance itself, use the
2797 superclass' L<Venus::Core/META> method.
2798  
2799 I<Since C<1.02>>
2800  
2801 =over 4
2802  
2803 =item meta example 1
2804  
2805 # given: synopsis
2806  
2807 package main;
2808  
2809 my $meta = $space->meta;
2810  
2811 # bless({'name' => 'Foo::Bar'}, 'Venus::Meta')
2812  
2813 =back
2814  
2815 =over 4
2816  
2817 =item meta example 2
2818  
2819 # given: synopsis
2820  
2821 package main;
2822  
2823 my $meta = $space->META;
2824  
2825 # bless({'name' => 'Venus::Space'}, 'Venus::Meta')
2826  
2827 =back
2828  
2829 =cut
2830  
2831 =head2 mock
2832  
2833 mock() (Venus::Space)
2834  
2835 The mock method returns a L<Venus::Space> object representing an anonymous
2836 package that derives from the invoking package.
2837  
2838 I<Since C<1.50>>
2839  
2840 =over 4
2841  
2842 =item mock example 1
2843  
2844 # given: synopsis
2845  
2846 package main;
2847  
2848 my $mock = $space->mock;
2849  
2850 # bless({'name' => 'Venus::Space::Mock::0001::Foo::Bar'}, 'Venus::Space')
2851  
2852 # $mock->isa('Foo::Bar') # true
2853  
2854 =back
2855  
2856 =cut
2857  
2858 =head2 name
2859  
2860 name() (string)
2861  
2862 The name method returns the fully-qualified package name.
2863  
2864 I<Since C<0.01>>
2865  
2866 =over 4
2867  
2868 =item name example 1
2869  
2870 # given: synopsis;
2871  
2872 my $name = $space->name;
2873  
2874 # "Foo::Bar"
2875  
2876 =back
2877  
2878 =cut
2879  
2880 =head2 new
2881  
2882 new(any @args) (Venus::Space)
2883  
2884 The new method constructs an instance of the package.
2885  
2886 I<Since C<4.15>>
2887  
2888 =over 4
2889  
2890 =item new example 1
2891  
2892 package main;
2893  
2894 use Venus::Space;
2895  
2896 my $new = Venus::Space->new('Foo::Bar');
2897  
2898 # bless(..., "Venus::Space")
2899  
2900 =back
2901  
2902 =over 4
2903  
2904 =item new example 2
2905  
2906 package main;
2907  
2908 use Venus::Space;
2909  
2910 my $new = Venus::Space->new(value => 'Foo::Bar');
2911  
2912 # bless(..., "Venus::Space")
2913  
2914 =back
2915  
2916 =cut
2917  
2918 =head2 parent
2919  
2920 parent() (Venus::Space)
2921  
2922 The parent method returns a new L<Venus::Space> object for the parent package
2923 namespace.
2924  
2925 I<Since C<0.01>>
2926  
2927 =over 4
2928  
2929 =item parent example 1
2930  
2931 # given: synopsis;
2932  
2933 my $parent = $space->parent;
2934  
2935 # bless({ value => "Foo" }, "Venus::Space")
2936  
2937 =back
2938  
2939 =cut
2940  
2941 =head2 parse
2942  
2943 parse() (arrayref)
2944  
2945 The parse method parses the string argument and returns an arrayref of package
2946 namespace segments (parts).
2947  
2948 I<Since C<0.01>>
2949  
2950 =over 4
2951  
2952 =item parse example 1
2953  
2954 # given: synopsis;
2955  
2956 my $parse = $space->parse;
2957  
2958 # ["Foo", "Bar"]
2959  
2960 =back
2961  
2962 =over 4
2963  
2964 =item parse example 2
2965  
2966 package main;
2967  
2968 use Venus::Space;
2969  
2970 my $space = Venus::Space->new('Foo/Bar');
2971  
2972 my $parse = $space->parse;
2973  
2974 # ["Foo", "Bar"]
2975  
2976 =back
2977  
2978 =over 4
2979  
2980 =item parse example 3
2981  
2982 package main;
2983  
2984 use Venus::Space;
2985  
2986 my $space = Venus::Space->new('Foo\Bar');
2987  
2988 my $parse = $space->parse;
2989  
2990 # ["Foo", "Bar"]
2991  
2992 =back
2993  
2994 =over 4
2995  
2996 =item parse example 4
2997  
2998 package main;
2999  
3000 use Venus::Space;
3001  
3002 my $space = Venus::Space->new('Foo-Bar');
3003  
3004 my $parse = $space->parse;
3005  
3006 # ["FooBar"]
3007  
3008 =back
3009  
3010 =over 4
3011  
3012 =item parse example 5
3013  
3014 package main;
3015  
3016 use Venus::Space;
3017  
3018 my $space = Venus::Space->new('Foo_Bar');
3019  
3020 my $parse = $space->parse;
3021  
3022 # ["FooBar"]
3023  
3024 =back
3025  
3026 =cut
3027  
3028 =head2 parts
3029  
3030 parts() (arrayref)
3031  
3032 The parts method returns an arrayref of package namespace segments (parts).
3033  
3034 I<Since C<0.01>>
3035  
3036 =over 4
3037  
3038 =item parts example 1
3039  
3040 package main;
3041  
3042 use Venus::Space;
3043  
3044 my $space = Venus::Space->new('Foo');
3045  
3046 my $parts = $space->parts;
3047  
3048 # ["Foo"]
3049  
3050 =back
3051  
3052 =over 4
3053  
3054 =item parts example 2
3055  
3056 package main;
3057  
3058 use Venus::Space;
3059  
3060 my $space = Venus::Space->new('Foo/Bar');
3061  
3062 my $parts = $space->parts;
3063  
3064 # ["Foo", "Bar"]
3065  
3066 =back
3067  
3068 =over 4
3069  
3070 =item parts example 3
3071  
3072 package main;
3073  
3074 use Venus::Space;
3075  
3076 my $space = Venus::Space->new('Foo_Bar');
3077  
3078 my $parts = $space->parts;
3079  
3080 # ["FooBar"]
3081  
3082 =back
3083  
3084 =cut
3085  
3086 =head2 patch
3087  
3088 patch(string $name, coderef $code) (Venus::Space)
3089  
3090 The patch method overwrites the named subroutine in the underlying package
3091 using the L</swap> operation, stashing the original subroutine reference to be
3092 reset later using L</unpatch>.
3093  
3094 I<Since C<0.01>>
3095  
3096 =over 4
3097  
3098 =item patch example 1
3099  
3100 package Foo::Far;
3101  
3102 use Venus::Class;
3103  
3104 sub execute {
3105 1
3106 }
3107  
3108 package main;
3109  
3110 use Venus::Space;
3111  
3112 my $space = Venus::Space->new('foo/far');
3113  
3114 my $patch = $space->patch('execute', sub {
3115 $_[0]->() + 1
3116 });
3117  
3118 # bless(..., "Venus::Space")
3119  
3120 # $patch->patched;
3121  
3122 # true
3123  
3124 # Foo::Far->new->execute;
3125  
3126 # 2
3127  
3128 =back
3129  
3130 =cut
3131  
3132 =head2 patched
3133  
3134 patched(string $name) (boolean)
3135  
3136 The patched method confirms whether a subroutine in the underlying namespace
3137 has been patched using the L</patch> operation. If no name is provided, this
3138 method will return true if any subroutines have been patched. If a name is
3139 provided, this method will return true only if the named subroutine has been
3140 patched, and otherwise returns false.
3141  
3142 I<Since C<3.55>>
3143  
3144 =over 4
3145  
3146 =item patched example 1
3147  
3148 package Foo::Far;
3149  
3150 use Venus::Class;
3151  
3152 sub execute {
3153 1
3154 }
3155  
3156 package main;
3157  
3158 use Venus::Space;
3159  
3160 my $space = Venus::Space->new('foo/far');
3161  
3162 $space->patch('execute', sub {
3163 $_[0]->() + 1
3164 });
3165  
3166 my $patched = $space->patched;
3167  
3168 # true
3169  
3170 =back
3171  
3172 =over 4
3173  
3174 =item patched example 2
3175  
3176 package Foo::Far;
3177  
3178 use Venus::Class;
3179  
3180 sub execute {
3181 1
3182 }
3183  
3184 package main;
3185  
3186 use Venus::Space;
3187  
3188 my $space = Venus::Space->new('foo/far');
3189  
3190 $space->patch('execute', sub {
3191 $_[0]->() + 1
3192 });
3193  
3194 my $patched = $space->patched('execute');
3195  
3196 # true
3197  
3198 =back
3199  
3200 =over 4
3201  
3202 =item patched example 3
3203  
3204 package Foo::Far;
3205  
3206 use Venus::Class;
3207  
3208 sub execute {
3209 1
3210 }
3211  
3212 package main;
3213  
3214 use Venus::Space;
3215  
3216 my $space = Venus::Space->new('foo/far');
3217  
3218 $space->patch('execute', sub {
3219 $_[0]->() + 1
3220 });
3221  
3222 my $patched = $space->patched('prepare');
3223  
3224 # false
3225  
3226 =back
3227  
3228 =cut
3229  
3230 =head2 pfile
3231  
3232 pfile() (string)
3233  
3234 The pfile method returns a C<.pod> file path for the underlying package.
3235  
3236 I<Since C<1.30>>
3237  
3238 =over 4
3239  
3240 =item pfile example 1
3241  
3242 # given: synopsis
3243  
3244 package main;
3245  
3246 my $pfile = $space->pfile;
3247  
3248 # "Foo/Bar.pod"
3249  
3250 =back
3251  
3252 =cut
3253  
3254 =head2 prepend
3255  
3256 prepend(string @path) (Venus::Space)
3257  
3258 The prepend method modifies the object by prepending to the package namespace
3259 parts.
3260  
3261 I<Since C<0.01>>
3262  
3263 =over 4
3264  
3265 =item prepend example 1
3266  
3267 # given: synopsis;
3268  
3269 my $prepend = $space->prepend('etc');
3270  
3271 # bless({ value => "Etc/Foo/Bar" }, "Venus::Space")
3272  
3273 =back
3274  
3275 =over 4
3276  
3277 =item prepend example 2
3278  
3279 # given: synopsis;
3280  
3281 my $prepend = $space->prepend('etc', 'tmp');
3282  
3283 # bless({ value => "Etc/Tmp/Foo/Bar" }, "Venus::Space")
3284  
3285 =back
3286  
3287 =cut
3288  
3289 =head2 purge
3290  
3291 purge() (Venus::Space)
3292  
3293 The purge method purges a package space by expunging its symbol table and
3294 removing it from C<%INC>. B<Warning:> This method deletes symbol table entries
3295 entirely, which may cause issues with code that holds compiled references to
3296 package variables. For safer cleanup that preserves symbol table structure, see
3297 L</scrub>.
3298  
3299 I<Since C<1.02>>
3300  
3301 =over 4
3302  
3303 =item purge example 1
3304  
3305 package main;
3306  
3307 use Venus::Space;
3308  
3309 # Bar::Gen is generated with $VERSION as 0.01
3310  
3311 my $space = Venus::Space->new('Bar/Gen');
3312  
3313 $space->load;
3314  
3315 my $purge = $space->purge;
3316  
3317 # bless({ value => "Bar::Gen" }, "Venus::Space")
3318  
3319 # Bar::Gen->VERSION was 0.01, now undef
3320  
3321 # Symbol table is gone, $space->visible is 0
3322  
3323 =back
3324  
3325 =cut
3326  
3327 =head2 rebase
3328  
3329 rebase(string @path) (Venus::Space)
3330  
3331 The rebase method returns an object by prepending the package namespace
3332 specified to the base of the current object's namespace.
3333  
3334 I<Since C<0.01>>
3335  
3336 =over 4
3337  
3338 =item rebase example 1
3339  
3340 # given: synopsis;
3341  
3342 my $rebase = $space->rebase('zoo');
3343  
3344 # bless({ value => "Zoo/Bar" }, "Venus::Space")
3345  
3346 =back
3347  
3348 =cut
3349  
3350 =head2 reload
3351  
3352 reload() (string)
3353  
3354 The reload method attempts to delete and reload the package namespace using the
3355 L</load> method. B<Note:> Reloading is additive and will overwrite existing
3356 symbols but does not remove symbols.
3357  
3358 I<Since C<0.01>>
3359  
3360 =over 4
3361  
3362 =item reload example 1
3363  
3364 package main;
3365  
3366 use Venus::Space;
3367  
3368 # Foo::Gen is generated with $VERSION as 0.01
3369  
3370 my $space = Venus::Space->new('Foo/Gen');
3371  
3372 my $reload = $space->reload;
3373  
3374 # Foo::Gen
3375 # Foo::Gen->VERSION is 0.01
3376  
3377 =back
3378  
3379 =over 4
3380  
3381 =item reload example 2
3382  
3383 package main;
3384  
3385 use Venus::Space;
3386  
3387 # Foo::Gen is generated with $VERSION as 0.02
3388  
3389 my $space = Venus::Space->new('Foo/Gen');
3390  
3391 my $reload = $space->reload;
3392  
3393 # Foo::Gen
3394 # Foo::Gen->VERSION is 0.02
3395  
3396 =back
3397  
3398 =cut
3399  
3400 =head2 require
3401  
3402 require(string $target) (any)
3403  
3404 The require method executes a C<require> statement within the package namespace
3405 specified.
3406  
3407 I<Since C<0.01>>
3408  
3409 =over 4
3410  
3411 =item require example 1
3412  
3413 # given: synopsis;
3414  
3415 my $require = $space->require('Venus');
3416  
3417 # 1
3418  
3419 =back
3420  
3421 =cut
3422  
3423 =head2 root
3424  
3425 root() (string)
3426  
3427 The root method returns the root package namespace segments (parts). Sometimes
3428 separating the C<root> from the C<parts> helps identify how subsequent child
3429 objects were derived.
3430  
3431 I<Since C<0.01>>
3432  
3433 =over 4
3434  
3435 =item root example 1
3436  
3437 # given: synopsis;
3438  
3439 my $root = $space->root;
3440  
3441 # "Foo"
3442  
3443 =back
3444  
3445 =cut
3446  
3447 =head2 routine
3448  
3449 routine(string $name, coderef $code) (coderef)
3450  
3451 The routine method gets or sets the subroutine reference for the given subroutine
3452 name.
3453  
3454 I<Since C<0.01>>
3455  
3456 =over 4
3457  
3458 =item routine example 1
3459  
3460 package Foo;
3461  
3462 sub cont {
3463 [@_]
3464 }
3465  
3466 sub abort {
3467 [@_]
3468 }
3469  
3470 package main;
3471  
3472 use Venus::Space;
3473  
3474 my $space = Venus::Space->new('foo');
3475  
3476 my $routine = $space->routine('cont');
3477  
3478 # sub { ... }
3479  
3480 =back
3481  
3482 =over 4
3483  
3484 =item routine example 2
3485  
3486 package Foo;
3487  
3488 sub cont {
3489 [@_]
3490 }
3491  
3492 sub abort {
3493 [@_]
3494 }
3495  
3496 package main;
3497  
3498 use Venus::Space;
3499  
3500 my $space = Venus::Space->new('foo');
3501  
3502 my $routine = $space->routine('report', sub{[@_]});
3503  
3504 # sub { ... }
3505  
3506 =back
3507  
3508 =cut
3509  
3510 =head2 routines
3511  
3512 routines() (arrayref)
3513  
3514 The routines method searches the package namespace for routines and returns
3515 their names.
3516  
3517 I<Since C<0.01>>
3518  
3519 =over 4
3520  
3521 =item routines example 1
3522  
3523 package Foo::Subs;
3524  
3525 sub start {
3526 1
3527 }
3528  
3529 sub abort {
3530 1
3531 }
3532  
3533 package main;
3534  
3535 use Venus::Space;
3536  
3537 my $space = Venus::Space->new('foo/subs');
3538  
3539 my $routines = $space->routines;
3540  
3541 # ["abort", "start"]
3542  
3543 =back
3544  
3545 =cut
3546  
3547 =head2 scalar
3548  
3549 scalar(string $name, any @data) (any)
3550  
3551 The scalar method gets or sets the value for the given package scalar variable name.
3552  
3553 I<Since C<0.01>>
3554  
3555 =over 4
3556  
3557 =item scalar example 1
3558  
3559 # given: synopsis;
3560  
3561 package Foo::Bar;
3562  
3563 our $root = '/path/to/file';
3564  
3565 package main;
3566  
3567 my $scalar = $space->scalar('root');
3568  
3569 # "/path/to/file"
3570  
3571 =back
3572  
3573 =over 4
3574  
3575 =item scalar example 2
3576  
3577 # given: synopsis;
3578  
3579 package Foo::Bar;
3580  
3581 our $root = '/path/to/file';
3582  
3583 package main;
3584  
3585 my $scalar = $space->scalar('root', '/tmp/path/to/file');
3586  
3587 # "/tmp/path/to/file"
3588  
3589 =back
3590  
3591 =cut
3592  
3593 =head2 scalars
3594  
3595 scalars() (arrayref)
3596  
3597 The scalars method searches the package namespace for scalars and returns their
3598 names.
3599  
3600 I<Since C<0.01>>
3601  
3602 =over 4
3603  
3604 =item scalars example 1
3605  
3606 # given: synopsis;
3607  
3608 package Foo::Bar;
3609  
3610 our $root = 'root';
3611 our $base = 'path/to';
3612 our $file = 'file';
3613  
3614 package main;
3615  
3616 my $scalars = $space->scalars;
3617  
3618 # ["base", "file", "root"]
3619  
3620 =back
3621  
3622 =cut
3623  
3624 =head2 scrub
3625  
3626 scrub() (Venus::Space)
3627  
3628 The scrub method cleans a package space by nullifying its typeglobs (setting
3629 them to C<undef>) for all symbols except special variables and routines (like
3630 C<@ISA>, C<DESTROY>, etc.), and removes it from C<%INC>. Unlike L</purge>, this
3631 method preserves the stash entries allowing compiled code holding references to
3632 remain valid. Unlike L</unload>, this method preserves special symbols needed
3633 for proper package operation. See also L</purge> and L</unload>.
3634  
3635 I<Since C<4.15>>
3636  
3637 =over 4
3638  
3639 =item scrub example 1
3640  
3641 package main;
3642  
3643 use Venus::Space;
3644  
3645 # Bar::Gen is generated with $VERSION as 0.01
3646  
3647 my $space = Venus::Space->new('Bar/Gen');
3648  
3649 $space->load;
3650  
3651 my $scrub = $space->scrub;
3652  
3653 # bless({ value => "Bar::Gen" }, "Venus::Space")
3654  
3655 # Bar::Gen->VERSION was 0.01, now undef
3656  
3657 # Symbol table persists, $space->visible is 1
3658  
3659 =back
3660  
3661 =cut
3662  
3663 =head2 sibling
3664  
3665 sibling(string $path) (Venus::Space)
3666  
3667 The sibling method returns a new L<Venus::Space> object for the sibling package
3668 namespace.
3669  
3670 I<Since C<0.01>>
3671  
3672 =over 4
3673  
3674 =item sibling example 1
3675  
3676 # given: synopsis;
3677  
3678 my $sibling = $space->sibling('baz');
3679  
3680 # bless({ value => "Foo/Baz" }, "Venus::Space")
3681  
3682 =back
3683  
3684 =cut
3685  
3686 =head2 siblings
3687  
3688 siblings() (within[arrayref, object])
3689  
3690 The siblings method searches C<%INC> and C<@INC> and retuns a list of
3691 L<Venus::Space> objects for each sibling namespace found (one level deep).
3692  
3693 I<Since C<0.01>>
3694  
3695 =over 4
3696  
3697 =item siblings example 1
3698  
3699 package main;
3700  
3701 use Venus::Space;
3702  
3703 my $space = Venus::Space->new('encode/m_i_m_e');
3704  
3705 my $siblings = $space->siblings;
3706  
3707 # [
3708 # bless({ value => "Encode/MIME/Header" }, "Venus::Space"),
3709 # bless({ value => "Encode/MIME/Name" }, "Venus::Space"),
3710 # ...
3711 # ]
3712  
3713 =back
3714  
3715 =cut
3716  
3717 =head2 splice
3718  
3719 splice(number $offset, number $length, any @list) (Venus::Space)
3720  
3721 The splice method perform a Perl L<perlfunc/splice> operation on the package
3722 namespace.
3723  
3724 I<Since C<0.09>>
3725  
3726 =over 4
3727  
3728 =item splice example 1
3729  
3730 package main;
3731  
3732 use Venus::Space;
3733  
3734 my $space = Venus::Space->new('foo/baz');
3735  
3736 my $splice = $space->splice(1, 0, 'bar');
3737  
3738 # bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
3739  
3740 =back
3741  
3742 =over 4
3743  
3744 =item splice example 2
3745  
3746 package main;
3747  
3748 use Venus::Space;
3749  
3750 my $space = Venus::Space->new('foo/baz');
3751  
3752 my $splice = $space->splice(1, 1);
3753  
3754 # bless({ value => "Foo" }, "Venus::Space")
3755  
3756 =back
3757  
3758 =over 4
3759  
3760 =item splice example 3
3761  
3762 package main;
3763  
3764 use Venus::Space;
3765  
3766 my $space = Venus::Space->new('foo/baz');
3767  
3768 my $splice = $space->splice(-2, 1);
3769  
3770 # bless({ value => "Baz" }, "Venus::Space")
3771  
3772 =back
3773  
3774 =over 4
3775  
3776 =item splice example 4
3777  
3778 package main;
3779  
3780 use Venus::Space;
3781  
3782 my $space = Venus::Space->new('foo/baz');
3783  
3784 my $splice = $space->splice(1);
3785  
3786 # bless({ value => "Foo" }, "Venus::Space")
3787  
3788 =back
3789  
3790 =cut
3791  
3792 =head2 swap
3793  
3794 swap(string $name, coderef $code) (coderef)
3795  
3796 The swap method overwrites the named subroutine in the underlying package with
3797 the code reference provided and returns the original subroutine as a code
3798 reference. The code provided will be passed a reference to the original
3799 subroutine as its first argument.
3800  
3801 I<Since C<1.95>>
3802  
3803 =over 4
3804  
3805 =item swap example 1
3806  
3807 package Foo::Swap;
3808  
3809 use Venus::Class;
3810  
3811 package main;
3812  
3813 use Venus::Space;
3814  
3815 my $space = Venus::Space->new('foo/swap');
3816  
3817 my $subroutine = $space->swap('new', sub {
3818 my ($next, @args) = @_;
3819 my $self = $next->(@args);
3820 $self->{swapped} = 1;
3821 return $self;
3822 });
3823  
3824 # sub { ... }
3825  
3826 =back
3827  
3828 =over 4
3829  
3830 =item swap example 2
3831  
3832 package Foo::Swap;
3833  
3834 use Venus::Class;
3835  
3836 package main;
3837  
3838 use Venus::Space;
3839  
3840 my $space = Venus::Space->new('foo/swap');
3841  
3842 my $subroutine = $space->swap('something', sub {
3843 my ($next, @args) = @_;
3844 my $self = $next->(@args);
3845 $self->{swapped} = 1;
3846 return $self;
3847 });
3848  
3849 # Exception! (isa Venus::Space::Error) (see error_on_swap)
3850  
3851 =back
3852  
3853 =cut
3854  
3855 =head2 tfile
3856  
3857 tfile() (string)
3858  
3859 The tfile method returns a C<.t> file path for the underlying package.
3860  
3861 I<Since C<1.30>>
3862  
3863 =over 4
3864  
3865 =item tfile example 1
3866  
3867 # given: synopsis
3868  
3869 package main;
3870  
3871 my $tfile = $space->tfile;
3872  
3873 # "Foo_Bar.t"
3874  
3875 =back
3876  
3877 =cut
3878  
3879 =head2 tryload
3880  
3881 tryload() (boolean)
3882  
3883 The tryload method attempt to C<load> the represented package using the
3884 L</load> method and returns truthy/falsy based on whether the package was
3885 loaded.
3886  
3887 I<Since C<0.01>>
3888  
3889 =over 4
3890  
3891 =item tryload example 1
3892  
3893 package main;
3894  
3895 use Venus::Space;
3896  
3897 my $space = Venus::Space->new('c_p_a_n');
3898  
3899 my $tryload = $space->tryload;
3900  
3901 # 1
3902  
3903 =back
3904  
3905 =over 4
3906  
3907 =item tryload example 2
3908  
3909 package main;
3910  
3911 use Venus::Space;
3912  
3913 my $space = Venus::Space->new('n_a_p_c');
3914  
3915 my $tryload = $space->tryload;
3916  
3917 # 0
3918  
3919 =back
3920  
3921 =cut
3922  
3923 =head2 unload
3924  
3925 unload() (Venus::Space)
3926  
3927 The unload method unloads a package space by nullifying its symbol table
3928 (setting all typeglobs to C<undef>) and removing it from C<%INC>. Unlike
3929 L</purge>, this method preserves symbol table entries, keeping the package
3930 visible. Unlike L</scrub>, this method nullifies entire typeglobs rather than
3931 individual slots.
3932  
3933 I<Since C<1.02>>
3934  
3935 =over 4
3936  
3937 =item unload example 1
3938  
3939 package main;
3940  
3941 use Venus::Space;
3942  
3943 # Bar::Gen is generated with $VERSION as 0.01
3944  
3945 my $space = Venus::Space->new('Bar/Gen');
3946  
3947 $space->load;
3948  
3949 my $unload = $space->unload;
3950  
3951 # bless({ value => "Bar::Gen" }, "Venus::Space")
3952  
3953 # Bar::Gen->VERSION was 0.01, now undef
3954  
3955 # Symbol table remains, $space->visible is 1
3956  
3957 =back
3958  
3959 =cut
3960  
3961 =head2 unloaded
3962  
3963 unloaded() (boolean)
3964  
3965 The unloaded method checks whether the package namespace is not loaded and
3966 returns truthy or falsy.
3967  
3968 I<Since C<1.02>>
3969  
3970 =over 4
3971  
3972 =item unloaded example 1
3973  
3974 package main;
3975  
3976 use Venus::Space;
3977  
3978 my $space = Venus::Space->new('Kit');
3979  
3980 $space->init;
3981  
3982 $space->unload;
3983  
3984 my $unloaded = $space->unloaded;
3985  
3986 # 1
3987  
3988 =back
3989  
3990 =over 4
3991  
3992 =item unloaded example 2
3993  
3994 package main;
3995  
3996 use Venus::Space;
3997  
3998 my $space = Venus::Space->new('Kit');
3999  
4000 $space->init;
4001  
4002 my $unloaded = $space->unloaded;
4003  
4004 # 0
4005  
4006 =back
4007  
4008 =cut
4009  
4010 =head2 unpatch
4011  
4012 unpatch(string @names) (Venus::Space)
4013  
4014 The unpatch method restores a subroutine which has been patched using the
4015 L</patch> operation to its original subroutine reference. If no name is
4016 provided, this method will restore all subroutines have been patched. If a name
4017 is provided, this method will only restore the named subroutine has been
4018 patched.
4019  
4020 I<Since C<3.55>>
4021  
4022 =over 4
4023  
4024 =item unpatch example 1
4025  
4026 package Foo::Far;
4027  
4028 use Venus::Class;
4029  
4030 sub execute {
4031 1
4032 }
4033  
4034 package main;
4035  
4036 use Venus::Space;
4037  
4038 my $space = Venus::Space->new('foo/far');
4039  
4040 $space->patch('execute', sub {
4041 $_[0]->() + 1
4042 });
4043  
4044 my $unpatch = $space->unpatch;
4045  
4046 # bless(..., "Venus::Space")
4047  
4048 =back
4049  
4050 =over 4
4051  
4052 =item unpatch example 2
4053  
4054 package Foo::Far;
4055  
4056 use Venus::Class;
4057  
4058 sub execute {
4059 1
4060 }
4061  
4062 package main;
4063  
4064 use Venus::Space;
4065  
4066 my $space = Venus::Space->new('foo/far');
4067  
4068 $space->patch('execute', sub {
4069 $_[0]->() + 1
4070 });
4071  
4072 my $unpatch = $space->unpatch('execute');
4073  
4074 # bless(..., "Venus::Space")
4075  
4076 =back
4077  
4078 =over 4
4079  
4080 =item unpatch example 3
4081  
4082 package Foo::Far;
4083  
4084 use Venus::Class;
4085  
4086 sub execute {
4087 1
4088 }
4089  
4090 package main;
4091  
4092 use Venus::Space;
4093  
4094 my $space = Venus::Space->new('foo/far');
4095  
4096 $space->patch('execute', sub {
4097 $_[0]->() + 1
4098 });
4099  
4100 my $unpatch = $space->unpatch('prepare');
4101  
4102 # bless(..., "Venus::Space")
4103  
4104 =back
4105  
4106 =cut
4107  
4108 =head2 use
4109  
4110 use(string | tuple[string, string] $target, any @params) (Venus::Space)
4111  
4112 The use method executes a C<use> statement within the package namespace
4113 specified.
4114  
4115 I<Since C<0.01>>
4116  
4117 =over 4
4118  
4119 =item use example 1
4120  
4121 package main;
4122  
4123 use Venus::Space;
4124  
4125 my $space = Venus::Space->new('foo/goo');
4126  
4127 my $use = $space->use('Venus');
4128  
4129 # bless({ value => "foo/goo" }, "Venus::Space")
4130  
4131 =back
4132  
4133 =over 4
4134  
4135 =item use example 2
4136  
4137 package main;
4138  
4139 use Venus::Space;
4140  
4141 my $space = Venus::Space->new('foo/hoo');
4142  
4143 my $use = $space->use('Venus', 'error');
4144  
4145 # bless({ value => "foo/hoo" }, "Venus::Space")
4146  
4147 =back
4148  
4149 =over 4
4150  
4151 =item use example 3
4152  
4153 package main;
4154  
4155 use Venus::Space;
4156  
4157 my $space = Venus::Space->new('foo/foo');
4158  
4159 my $use = $space->use(['Venus', 9.99], 'error');
4160  
4161 =back
4162  
4163 =cut
4164  
4165 =head2 variables
4166  
4167 variables() (within[arrayref, tuple[string, arrayref]])
4168  
4169 The variables method searches the package namespace for variables and returns
4170 their names.
4171  
4172 I<Since C<0.01>>
4173  
4174 =over 4
4175  
4176 =item variables example 1
4177  
4178 package Etc;
4179  
4180 our $init = 0;
4181 our $func = 1;
4182  
4183 our @does = (1..4);
4184 our %sets = (1..4);
4185  
4186 package main;
4187  
4188 use Venus::Space;
4189  
4190 my $space = Venus::Space->new('etc');
4191  
4192 my $variables = $space->variables;
4193  
4194 # [
4195 # ["arrays", ["does"]],
4196 # ["hashes", ["sets"]],
4197 # ["scalars", ["func", "init"]],
4198 # ]
4199  
4200 =back
4201  
4202 =cut
4203  
4204 =head2 version
4205  
4206 version() (maybe[string])
4207  
4208 The version method returns the C<VERSION> declared on the target package, if
4209 any.
4210  
4211 I<Since C<0.01>>
4212  
4213 =over 4
4214  
4215 =item version example 1
4216  
4217 package Foo::Boo;
4218  
4219 sub import;
4220  
4221 package main;
4222  
4223 use Venus::Space;
4224  
4225 my $space = Venus::Space->new('foo/boo');
4226  
4227 my $version = $space->version;
4228  
4229 # undef
4230  
4231 =back
4232  
4233 =over 4
4234  
4235 =item version example 2
4236  
4237 package Foo::Boo;
4238  
4239 our $VERSION = 0.01;
4240  
4241 package main;
4242  
4243 use Venus::Space;
4244  
4245 my $space = Venus::Space->new('foo/boo');
4246  
4247 my $version = $space->version;
4248  
4249 # 0.01
4250  
4251 =back
4252  
4253 =cut
4254  
4255 =head2 visible
4256  
4257 visible() (boolean)
4258  
4259 The visible method returns truthy is the package namespace is visible, i.e. has
4260 symbols defined.
4261  
4262 I<Since C<1.02>>
4263  
4264 =over 4
4265  
4266 =item visible example 1
4267  
4268 # given: synopsis
4269  
4270 package main;
4271  
4272 my $visible = $space->visible;
4273  
4274 # 1
4275  
4276 =back
4277  
4278 =over 4
4279  
4280 =item visible example 2
4281  
4282 package Foo::Fe;
4283  
4284 package main;
4285  
4286 use Venus::Space;
4287  
4288 my $space = Venus::Space->new('foo/fe');
4289  
4290 my $visible = $space->visible;
4291  
4292 # 0
4293  
4294 =back
4295  
4296 =over 4
4297  
4298 =item visible example 3
4299  
4300 package Foo::Fe;
4301  
4302 our $VERSION = 0.01;
4303  
4304 package main;
4305  
4306 use Venus::Space;
4307  
4308 my $space = Venus::Space->new('foo/fe');
4309  
4310 my $visible = $space->visible;
4311  
4312 # 1
4313  
4314 =back
4315  
4316 =over 4
4317  
4318 =item visible example 4
4319  
4320 package Foo::Fi;
4321  
4322 sub import;
4323  
4324 package main;
4325  
4326 use Venus::Space;
4327  
4328 my $space = Venus::Space->new('foo/fi');
4329  
4330 my $visible = $space->visible;
4331  
4332 # 1
4333  
4334 =back
4335  
4336 =cut
4337  
4338 =head1 AUTHORS
4339  
4340 Awncorp, C<awncorp@cpan.org>
4341  
4342 =cut
4343  
4344 =head1 LICENSE
4345  
4346 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
4347  
4348 This program is free software, you can redistribute it and/or modify it under
4349 the terms of the Apache license version 2.0.
4350  
4351 =cut
« blib/lib/Venus/Role/Subscribable.pm ↑ Summary blib/lib/Venus/Coercion.pm »