blib/lib/Venus/Path.pm

filter: Statementstmt 96.2% 330 / 343 Branchbran 82.4% 89 / 108 Conditioncond 66.6% 22 / 33 MC/DCmcdc 44.4% 8 / 18 Subroutinesub 98.4% 65 / 66 Podpod 82.1% 46 / 56 totaltotal 89.7% 560 / 624 CC 73 SCAR 11.0
CC
73
Cov
91%
read
5.3
write
5.3
find
5.2
CRAP 3.0
« blib/lib/Venus/Role/Fromable.pm ↑ Summary blib/lib/Venus/Constraint.pm »
1 package Venus::Path;
2  
3 119 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 119 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 119 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 119 ▶use Venus::Class 'base', 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 119 base 'Venus::Kind::Utility';
15  
16 # INTEGRATES
17  
18 119 with 'Venus::Role::Valuable';
19 119 with 'Venus::Role::Buildable';
20 119 with 'Venus::Role::Accessible';
21 119 with 'Venus::Role::Explainable';
22  
23 # OVERLOADS
24  
25 119 ▶use overload (
Subroutine BEGIN: called CC=1 SCAR=0.0
26 '""' => 'explain',
27 22 ▶ 'eq' => sub{$_[0]->value eq "$_[1]"},
Subroutine __ANON__: called CC=1 SCAR=0.0
28 1 ▶ 'ne' => sub{$_[0]->value ne "$_[1]"},
Subroutine __ANON__: called CC=1 SCAR=0.0
29 1 ▶ 'qr' => sub{qr/@{[quotemeta($_[0]->value)]}/},
Subroutine __ANON__: called CC=1 SCAR=0.0
30 119 '~~' => 'explain',
31 fallback => 1,
32 119 );
33  
34 # HOOKS
35  
36 6 ▶sub _exitcode {
Subroutine _exitcode: called CC=1 SCAR=0.0
37 6 $? >> 8;
38 }
39  
40 # METHODS
41  
42 469 ▶sub absolute {
Subroutine absolute: called CC=1 SCAR=0.0
Pod documented
43 469 my ($self) = @_;
44  
45 469 require File::Spec;
46  
47 469 return $self->class->new(File::Spec->rel2abs($self->get));
48 }
49  
50 13 ▶sub basename {
Subroutine basename: called CC=1 SCAR=0.0
Pod documented
51 13 my ($self) = @_;
52  
53 13 require File::Basename;
54  
55 13 return File::Basename::basename($self->get);
56 }
57  
58 617 ▶sub child {
Subroutine child: called CC=1 SCAR=0.0
Pod documented
59 617 my ($self, $path) = @_;
60  
61 617 require File::Spec;
62  
63 617 my @parts = File::Spec->splitdir($path);
64  
65 617 return $self->class->new(File::Spec->catfile($self->get, @parts));
66 }
67  
68 1 ▶sub chmod {
Subroutine chmod: called CC=1 SCAR=0.0
Pod documented
69 1 my ($self, $mode) = @_;
70  
71 1 my $path = $self->get;
72  
73 1 CORE::chmod($mode, $path);
74  
75 1 return $self;
76 }
77  
78 1 ▶sub chown {
Subroutine chown: called CC=2 SCAR=7.0
Pod documented
79 1 my ($self, @args) = @_;
80  
81 1 my $path = $self->get;
82  
83 1 ▶ CORE::chown((map $_||-1, @args[0,1]), $path);
Condition50%1/2
$_ || -1
l!l
20
MC/DC0%0/1
$_ || -1
$_
Truth table50%1/2
A
A= $_
Aresult
11
00
84  
85 1 return $self;
86 }
87  
88 106 ▶sub children {
Subroutine children: called CC=2 SCAR=6.9
Pod documented
89 106 my ($self) = @_;
90  
91 106 require File::Spec;
92  
93 106 my @paths = map $self->glob($_), '.??*', '*';
94  
95 106 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 105 1 106
96 }
97  
98 4 ▶sub copy {
Subroutine copy: called CC=3 SCAR=11.0
Pod documented
99 4 my ($self, $path) = @_;
100  
101 4 require File::Copy;
102  
103 4 ▶ File::Copy::copy("$self", "$path") or my $error = $!;
Branch: 1 branch
BranchTrueFalseTotal
File::Copy::copy("$self", "$path") or my $error = $! 3 1 4
104 4 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 1 3 4
105 1 $self->error_on_copy({error => $error, path => $path})
106 ->input($self, $path)
107 ->output($error)
108 ->throw;
109 }
110  
111 3 return $self;
112 }
113  
114 11 ▶sub default {
Subroutine default: called CC=1 SCAR=0.0
Pod documented
115 11 require Cwd;
116  
117 11 return Cwd::getcwd();
118 }
119  
120 22 ▶sub directories {
Subroutine directories: called CC=2 SCAR=6.9
Pod documented
121 22 my ($self) = @_;
122  
123 22 my @paths = grep -d, $self->children;
124  
125 22 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 21 1 22
126 }
127  
128 602 ▶sub exists {
Subroutine exists: called CC=1 SCAR=0.0
Pod documented
129 602 my ($self) = @_;
130  
131 602 return int!!-e $self->get;
132 }
133  
134 1796 ▶sub explain {
Subroutine explain: called CC=1 SCAR=0.0
Pod documented
135 1796 my ($self) = @_;
136  
137 1796 return $self->get;
138 }
139  
140 12 ▶sub extension {
Subroutine extension: called CC=4 SCAR=13.9
Pod documented
141 12 my ($self, $value) = @_;
142  
143 12 my $basename = $self->basename;
144  
145 12 my ($filename, $suffix);
146  
147 12 ▶ if ($basename =~ /^(.+)\.([^.]+)$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($basename =~ /^(.+)\.([^.]+)$/u) { } 9 3 12
148 9 $filename = $1;
149 9 $suffix = $2;
150 } else {
151 3 $filename = $basename;
152 3 $suffix = '';
153 }
154  
155 12 ▶ return $suffix || undef if !$value;
Branch: 1 branch
BranchTrueFalseTotal
unless $value 10 2 12
Condition100%2/2
$suffix || undef
l!l
91
MC/DC100%1/1
$suffix || undef
$suffix
Truth table100%2/2
A
A= $suffix
Aresult
11
00
156  
157 2 return $self->sibling(join '.', $filename, $value);
158 }
159  
160 3 ▶sub find {
Subroutine find: called CC=5 SCAR=16.4
Pod documented
161 3 my ($self, $expr) = @_;
162  
163 3 ▶ $expr = '.*' if !$expr;
Branch: 1 branch
BranchTrueFalseTotal
unless $expr 1 2 3
164  
165 3 ▶ $expr = qr/$expr/ if ref($expr) ne 'Regexp';
Branch: 1 branch
BranchTrueFalseTotal
if ref $expr ne "Regexp" 3 0 3
166  
167 3 my @paths;
168  
169 push @paths, grep {
170 42 $_ =~ $expr
171 } map {
172 3 ▶ $_->is_directory ? $_->find($expr) : $_
Branch: 1 branch
BranchTrueFalseTotal
$_->is_directory ? : 0 42 42
173 }
174 $self->children;
175  
176 3 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 3 3
177 }
178  
179 1 ▶sub files {
Subroutine files: called CC=2 SCAR=7.1
Pod documented
180 1 my ($self) = @_;
181  
182 1 my @paths = grep -f, $self->children;
183  
184 1 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
185 }
186  
187 215 ▶sub glob {
Subroutine glob: called CC=3 SCAR=11.0
Pod documented
188 215 my ($self, $expr) = @_;
189  
190 215 require File::Spec;
191  
192 215 ▶ $expr ||= '*';
Condition100%2/2
$expr ||= "*"
l!l
2141
MC/DC100%1/1
$expr ||= "*"
$expr
Truth table100%2/2
A
A= $expr
Aresult
11
00
193  
194 215 my @paths = map $self->class->new($_),
195 112 ▶ CORE::glob +File::Spec->catfile($self->absolute, $expr);
Subroutine BEGIN: called CC=1 SCAR=0.0
196  
197 215 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 214 1 215
198 }
199  
200 4 ▶sub is_absolute {
Subroutine is_absolute: called CC=1 SCAR=0.0
Pod documented
201 4 my ($self) = @_;
202  
203 4 require File::Spec;
204  
205 4 return int!!(File::Spec->file_name_is_absolute($self->get));
206 }
207  
208 44 ▶sub is_directory {
Subroutine is_directory: called CC=2 SCAR=7.0
Pod documented
209 44 my ($self) = @_;
210  
211 44 my $path = $self->get;
212  
213 44 ▶ return int!!(-e $path && -d $path);
Condition66%2/3
-e $path && -d $path
!ll&&!rl&&r
0422
MC/DC50%1/2
-e $path && -d $path
-e $path -d $path
Truth table66%2/3
A && B
A= -e $pathB= -d $path
ABresult
0X0
100
111
214 }
215  
216 118 ▶sub is_file {
Subroutine is_file: called CC=2 SCAR=6.9
Pod documented
217 118 my ($self) = @_;
218  
219 118 my $path = $self->get;
220  
221 118 ▶ return int!!(-e $path && !-d $path);
Condition100%3/3
-e $path && !(-d $path)
!ll&&!rl&&r
911611
MC/DC100%2/2
-e $path && !(-d $path)
-e $path !(-d $path)
Truth table100%3/3
A && not(B)
A= -e $pathB= !(-d $path)
ABresult
0X0
100
111
222 }
223  
224 3 ▶sub is_relative {
Subroutine is_relative: called CC=1 SCAR=0.0
Pod documented
225 3 my ($self) = @_;
226  
227 3 return int!$self->is_absolute;
228 }
229  
230 2 ▶sub lines {
Subroutine lines: called CC=3 SCAR=11.7
Pod documented
231 2 my ($self, $separator, $binmode) = @_;
232  
233 2 ▶ $separator //= "\n";
Condition50%1/2
$separator //= "\n"
l!l
02
MC/DC0%0/1
$separator //= "\n"
$separator
Truth table50%1/2
A
A= $separator
Aresult
11
00
234  
235 2 ▶ return [split /$separator/, $binmode ? $self->read($binmode) : $self->read];
Branch: 1 branch
BranchTrueFalseTotal
$binmode ? : 0 2 2
236 }
237  
238 96 ▶sub lineage {
Subroutine lineage: called CC=2 SCAR=6.9
Pod documented
239 96 my ($self) = @_;
240  
241 96 require File::Spec;
242  
243 96 my @parts = File::Spec->splitdir($self->get);
244  
245 96 my @paths = ((
246 reverse map $self->class->new(File::Spec->catfile(@parts[0..$_])), 1..$#parts
247 ), $self->class->new($parts[0]));
248  
249 96 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 95 1 96
250 }
251  
252 14 ▶sub open {
Subroutine open: called CC=3 SCAR=11.0
Pod documented
253 14 my ($self, @args) = @_;
254  
255 14 my $path = $self->get;
256  
257 14 require IO::File;
258  
259 14 my $handle = IO::File->new;
260  
261 14 ▶ $handle->open($path, @args) or my $error = $!;
Branch: 1 branch
BranchTrueFalseTotal
$handle->open($path, @args) or my $error = $! 10 4 14
262 14 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 4 10 14
263 4 $self->error_on_open({path => $path, error => $error})
264 ->input($self, @args)
265 ->output($error)
266 ->throw;
267 }
268  
269 10 return $handle;
270 }
271  
272 7 ▶sub mkcall {
Subroutine mkcall: called CC=5 SCAR=16.1
Pod documented
273 7 my ($self, @args) = @_;
274  
275 7 require File::Spec;
276  
277 7 my $path = File::Spec->catfile(File::Spec->splitdir($self->get));
278  
279 7 my $result;
280  
281 7 require Venus::Os;
282  
283 7 my $args = join ' ', map Venus::Os->quote($_), grep defined, @args;
284  
285 7 ▶ (defined($result = ($args ? qx($path $args) : qx($path)))) or my $error = $!;
Branch: 2 branches
BranchTrueFalseTotal
defined($result = $args ? `$path $args` : `$path`) or my $error = $! 6 1 7
$args ? : 6 1 7
286 7 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 1 6 7
287 1 $self->error_on_mkcall({error => $error, exit_code => _exitcode(), path => $path})
288 ->input($self, @args)
289 ->output($error)
290 ->throw;
291 }
292  
293 6 chomp $result;
294  
295 6 ▶ return wantarray ? ($result, _exitcode()) : $result;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 5 1 6
296 }
297  
298 100 ▶sub mkdir {
Subroutine mkdir: called CC=4 SCAR=13.9
Pod documented
299 100 my ($self, $mode) = @_;
300  
301 100 my $path = $self->get;
302  
303 100 ▶ ($mode ? CORE::mkdir($path, $mode) : CORE::mkdir($path)) or my $error = $!;
Branch: 2 branches
BranchTrueFalseTotal
$mode ? CORE::mkdir($path, $mode) : CORE::mkdir($path) or my $error = $! 97 3 100
$mode ? : 0 100 100
304 100 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 3 97 100
305 3 $self->error_on_mkdir({error => $error, path => $path})
306 ->input($self, $mode)
307 ->output($error)
308 ->throw;
309 }
310  
311 97 return $self;
312 }
313  
314 92 ▶sub mkdirs {
Subroutine mkdirs: called CC=5 SCAR=16.1
Pod documented
315 92 my ($self, $mode) = @_;
316  
317 92 my @paths;
318  
319 92 ▶ for my $path (
Branch: 1 branch
BranchTrueFalseTotal
$self->is_file ? : 0 92 92
320 grep !!$_, reverse($self->parents), ($self->is_file ? () : $self)
321 )
322 {
323 287 ▶ if ($path->exists) {
Branch: 1 branch
BranchTrueFalseTotal
if ($path->exists) { } 193 94 287
324 193 next;
325 }
326 else {
327 94 push @paths, $path->mkdir($mode);
328 }
329 }
330  
331 92 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 88 4 92
332 }
333  
334 20 ▶sub mktemp_dir {
Subroutine mktemp_dir: called CC=1 SCAR=0.0
Pod documented
335 20 my ($self) = @_;
336  
337 20 require File::Temp;
338  
339 20 return $self->class->new(File::Temp::tempdir());
340 }
341  
342 2 ▶sub mktemp_file {
Subroutine mktemp_file: called CC=1 SCAR=0.0
Pod documented
343 2 my ($self) = @_;
344  
345 2 require File::Temp;
346  
347 2 return $self->class->new((File::Temp::tempfile())[1]);
348 }
349  
350 10 ▶sub mkfile {
Subroutine mkfile: called CC=4 SCAR=14.2
Pod documented
351 10 my ($self) = @_;
352  
353 10 my $path = $self->get;
354  
355 10 ▶ return $self if $self->exists;
Branch: 1 branch
BranchTrueFalseTotal
if $self->exists 1 9 10
356  
357 9 $self->open('>');
358  
359 7 ▶ CORE::utime(undef, undef, $path) or my $error = $!;
Branch: 1 branch
BranchTrueFalseTotal
utime undef, undef, $path or my $error = $! 7 0 7
360 7 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 0 7 7
361 0 $self->error_on_mkfile({path => $path, error => $error})
362 ->input($self)
363 ->output($error)
364 ->throw;
365 }
366  
367 7 return $self;
368 }
369  
370 4 ▶sub move {
Subroutine move: called CC=3 SCAR=11.0
Pod documented
371 4 my ($self, $path) = @_;
372  
373 4 require File::Copy;
374  
375 4 ▶ File::Copy::move("$self", "$path") or my $error = $!;
Branch: 1 branch
BranchTrueFalseTotal
File::Copy::move("$self", "$path") or my $error = $! 3 1 4
376 4 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 1 3 4
377 1 $self->error_on_move({path => $path, error => $error})
378 ->input($self, $path)
379 ->output($error)
380 ->throw;
381 }
382  
383 3 return $self->class->new($path)->absolute;
384 }
385  
386 1 ▶sub name {
Subroutine name: called CC=1 SCAR=0.0
Pod documented
387 1 my ($self) = @_;
388  
389 1 return $self->absolute->get;
390 }
391  
392 11 ▶sub parent {
Subroutine parent: called CC=2 SCAR=7.0
Pod documented
393 11 my ($self) = @_;
394  
395 11 require File::Spec;
396  
397 11 my @parts = File::Spec->splitdir($self->get);
398  
399 11 my $path = File::Spec->catfile(@parts[0..$#parts-1]);
400  
401 11 ▶ return defined $path ? $self->class->new($path) : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $path ? : 11 0 11
402 }
403  
404 93 ▶sub parents {
Subroutine parents: called CC=3 SCAR=11.0
Pod documented
405 93 my ($self) = @_;
406  
407 93 my @paths = $self->lineage;
408  
409 93 ▶ @paths = @paths[1..$#paths] if @paths;
Branch: 1 branch
BranchTrueFalseTotal
if @paths 93 0 93
410  
411 93 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 92 1 93
412 }
413  
414 1 ▶sub parts {
Subroutine parts: called CC=1 SCAR=0.0
Pod documented
415 1 my ($self) = @_;
416  
417 1 require File::Spec;
418  
419 1 return [File::Spec->splitdir($self->get)];
420 }
421  
422 12337 ▶sub read {
Subroutine read: called CC=5 SCAR=16.6
Pod documented
423 12337 my ($self) = @_;
424  
425 12337 my $path = $self->get;
426  
427 12337 require Venus::Os;
428  
429 12337 my ($catch, $data) = Venus::Os->new->catch('read', $path);
430  
431 12337 ▶ if ($catch && $catch->isa('Venus::Os::Error') && $catch->of('on.read')) {
Branch: 2 branches
BranchTrueFalseTotal
if ($catch and $catch->isa('Venus::Os::Error') and $catch->of('on.read')) { } 3 12334 12337
elsif ($catch) { } 0 12334 12334
Condition66%4/6
$catch and $catch->isa("Venus::Os::Error") and $catch->of("on.read")
!ll&&!rl&&r
1233403
$catch and $catch->isa("Venus::Os::Error")
!ll&&!rl&&r
1233403
MC/DC33%1/3
$catch and $catch->isa("Venus::Os::Error") and $catch->of("on.read")
$catch $catch->isa("Venus::Os::Error") $catch->of("on.read")
Truth table50%2/4
A and B and C
A= $catchB= $catch->isa("Venus::Os::Error")C= $catch->of("on.read")
ABCresult
0XX0
10X0
1100
1111
432 3 $self->error_on_read({path => $path, error => $catch->stash('error')})
433 ->input($self)
434 ->output($catch->stash('error'))
435 ->set('cause', $catch)
436 ->throw;
437 }
438 elsif ($catch) {
439 0 die $catch;
440 }
441  
442 12334 return $data;
443 }
444  
445 2 ▶sub relative {
Subroutine relative: called CC=2 SCAR=7.4
Pod documented
446 2 my ($self, $path) = @_;
447  
448 2 require File::Spec;
449  
450 2 ▶ $path ||= $self->default;
Condition33%1/3
$path ||= $self->default
l!l&&r!l&&!r
200
MC/DC0%0/2
$path ||= $self->default
$path $self->default
Truth table33%1/3
A ||= B
A= $pathB= $self->default
ABresult
1X1
011
000
451  
452 2 return $self->class->new(File::Spec->abs2rel($self->get, $path));
453 }
454  
455 2 ▶sub rename {
Subroutine rename: called CC=2 SCAR=7.0
Pod documented
456 2 my ($self, $path) = @_;
457  
458 2 $path = $self->class->new($path);
459  
460 2 ▶ $path = $self->sibling("$path") if $path->is_relative;
Branch: 1 branch
BranchTrueFalseTotal
if $path->is_relative 2 0 2
461  
462 2 return $self->move($path);
463 }
464  
465 81 ▶sub rmdir {
Subroutine rmdir: called CC=3 SCAR=11.0
Pod documented
466 81 my ($self) = @_;
467  
468 81 my $path = $self->get;
469  
470 81 ▶ CORE::rmdir($path) or my $error = $!;
Branch: 1 branch
BranchTrueFalseTotal
CORE::rmdir $path or my $error = $! 80 1 81
471 81 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 1 80 81
472 1 $self->error_on_rmdir({path => $path, error => $error})
473 ->input($self)
474 ->output($error)
475 ->throw;
476 }
477  
478 80 return $self;
479 }
480  
481 78 ▶sub rmdirs {
Subroutine rmdirs: called CC=4 SCAR=13.9
Pod documented
482 78 my ($self) = @_;
483  
484 78 my @paths;
485  
486 78 for my $path ($self->children) {
487 19 ▶ if ($path->is_file) {
Branch: 1 branch
BranchTrueFalseTotal
if ($path->is_file) { } 5 14 19
488 5 push @paths, $path->unlink;
489 }
490 else {
491 14 push @paths, $path->rmdirs;
492 }
493 }
494  
495 78 push @paths, $self->rmdir;
496  
497 78 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 14 64 78
498 }
499  
500 1 ▶sub rmfiles {
Subroutine rmfiles: called CC=4 SCAR=14.6
Pod documented
501 1 my ($self) = @_;
502  
503 1 my @paths;
504  
505 1 for my $path ($self->children) {
506 5 ▶ if ($path->is_file) {
Branch: 1 branch
BranchTrueFalseTotal
if ($path->is_file) { } 5 0 5
507 5 push @paths, $path->unlink;
508 }
509 else {
510 0 push @paths, $path->rmfiles;
511 }
512 }
513  
514 1 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
515 }
516  
517 2 ▶sub root {
Subroutine root: called CC=5 SCAR=16.1
Pod documented
518 2 my ($self, $spec, $base) = @_;
519  
520 2 my @paths;
521  
522 2 for my $path ($self->absolute->lineage) {
523 13 ▶ if ($path->child($base)->test($spec)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($path->child($base)->test($spec)) 1 12 13
524 1 push @paths, $path;
525 1 last;
526 }
527 }
528  
529 2 ▶ return @paths ? (-f $paths[0] ? $paths[0]->parent : $paths[0]) : undef;
Branch: 2 branches
BranchTrueFalseTotal
@paths ? : 1 1 2
-f $paths[0] ? : 0 1 1
530 }
531  
532 22 ▶sub seek {
Subroutine seek: called CC=4 SCAR=13.9
Pod documented
533 22 my ($self, $spec, $base) = @_;
534  
535 22 ▶ if ((my $path = $self->child($base))->test($spec)) {
Branch: 1 branch
BranchTrueFalseTotal
if ((my $path = $self->child($base))->test($spec)) { } 1 21 22
536 1 return $path;
537 }
538 else {
539 21 for my $path ($self->directories) {
540 20 my $sought = $path->seek($spec, $base);
541 20 ▶ return $sought if $sought;
Branch: 1 branch
BranchTrueFalseTotal
if $sought 2 18 20
542 }
543 19 return undef;
544 }
545 }
546  
547 5 ▶sub sibling {
Subroutine sibling: called CC=1 SCAR=0.0
Pod documented
548 5 my ($self, $path) = @_;
549  
550 5 require File::Basename;
551 5 require File::Spec;
552  
553 5 return $self->class->new(File::Spec->catfile(
554 File::Basename::dirname($self->get), $path));
555 }
556  
557 1 ▶sub siblings {
Subroutine siblings: called CC=2 SCAR=7.0
Pod documented
558 1 my ($self) = @_;
559  
560 1 my @paths = map $self->parent->glob($_), '.??*', '*';
561  
562 1 my %seen = ($self->absolute, 1);
563  
564 1 @paths = grep !$seen{$_}++, @paths;
565  
566 1 ▶ return wantarray ? (@paths) : \@paths;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
567 }
568  
569 41 ▶sub test {
Subroutine test: called CC=2 SCAR=6.9
Pod documented
570 41 my ($self, $spec) = @_;
571  
572 return eval(
573 41 ▶ join(' ', map("-$_", grep(/^[a-zA-Z]$/, split(//, $spec || 'e'))), '$self')
Condition100%2/2
$spec || 'e'
l!l
401
MC/DC100%1/1
$spec || 'e'
$spec
Truth table100%2/2
A
A= $spec
Aresult
11
00
574 );
575 }
576  
577 63 ▶sub unlink {
Subroutine unlink: called CC=3 SCAR=11.0
Pod documented
578 63 my ($self) = @_;
579  
580 63 my $path = $self->get;
581  
582 63 ▶ CORE::unlink($path) or my $error = $!;
Branch: 1 branch
BranchTrueFalseTotal
CORE::unlink $path or my $error = $! 61 2 63
583 63 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 2 61 63
584 2 $self->error_on_unlink({path => $path, error => $error})
585 ->input($self)
586 ->output($error)
587 ->throw;
588 }
589  
590 61 return $self;
591 }
592  
593 72 ▶sub write {
Subroutine write: called CC=5 SCAR=16.6
Pod documented
594 72 my ($self, $data) = @_;
595  
596 72 my $path = $self->get;
597  
598 72 require Venus::Os;
599  
600 72 my $catch = Venus::Os->new->catch('write', $path, $data);
601  
602 72 ▶ if ($catch && $catch->isa('Venus::Os::Error') && $catch->of('on.write')) {
Branch: 2 branches
BranchTrueFalseTotal
if ($catch and $catch->isa('Venus::Os::Error') and $catch->of('on.write')) { } 2 70 72
elsif ($catch) { } 0 70 70
Condition66%4/6
$catch and $catch->isa("Venus::Os::Error") and $catch->of("on.write")
!ll&&!rl&&r
7002
$catch and $catch->isa("Venus::Os::Error")
!ll&&!rl&&r
7002
MC/DC33%1/3
$catch and $catch->isa("Venus::Os::Error") and $catch->of("on.write")
$catch $catch->isa("Venus::Os::Error") $catch->of("on.write")
Truth table50%2/4
A and B and C
A= $catchB= $catch->isa("Venus::Os::Error")C= $catch->of("on.write")
ABCresult
0XX0
10X0
1100
1111
603 2 $self->error_on_write({path => $path, error => $catch->stash('error')})
604 ->input($self, $data)
605 ->output($catch->stash('error'))
606 ->set('cause', $catch)
607 ->throw;
608 }
609 elsif ($catch) {
610 0 die $catch;
611 }
612  
613 70 return $self;
614 }
615  
616 # ERRORS
617  
618 1 ▶sub error_on_copy {
Subroutine error_on_copy: called CC=1 SCAR=0.0
Pod undocumented
619 1 my ($self, $data) = @_;
620  
621 1 my $error = $self->error->sysinfo;
622  
623 1 my $message = 'Can\'t copy "{{self}}" to "{{path}}": {{error}}';
624  
625 1 $error->name('on.copy');
626 1 $error->message($message);
627 1 $error->offset(1);
628 1 $error->stash($data);
629 1 $error->reset;
630  
631 1 return $error;
632 }
633  
634 1 ▶sub error_on_mkcall {
Subroutine error_on_mkcall: called CC=3 SCAR=11.3
Pod undocumented
635 1 my ($self, $data) = @_;
636  
637 1 my $error = $self->error->sysinfo;
638  
639 my $message = ("Can't make system call to \"{{path}}\": "
640 1 ▶ . ($data->{error} ? "@{[$data->{error}]}" : sprintf("exit code (%s)", $data->{exit_code} || 0)));
Branch: 1 branch
BranchTrueFalseTotal
$data->{'error'} ? : 1 0 1
Condition0%0/2
$data->{'exit_code'} || 0
l!l
00
MC/DC0%0/1
$data->{'exit_code'} || 0
$data->{'exit_code'}
Truth table0%0/2
A
A= $data->{'exit_code'}
Aresult
11
00
641  
642 1 $error->name('on.mkcall');
643 1 $error->message($message);
644 1 $error->offset(1);
645 1 $error->stash($data);
646 1 $error->reset;
647  
648 1 return $error;
649 }
650  
651 3 ▶sub error_on_mkdir {
Subroutine error_on_mkdir: called CC=1 SCAR=0.0
Pod undocumented
652 3 my ($self, $data) = @_;
653  
654 3 my $error = $self->error->sysinfo;
655  
656 3 my $message = 'Can\'t make directory "{{path}}": {{error}}';
657  
658 3 $error->name('on.mkdir');
659 3 $error->message($message);
660 3 $error->offset(1);
661 3 $error->stash($data);
662 3 $error->reset;
663  
664 3 return $error;
665 }
666  
667 0 ▶sub error_on_mkfile {
Subroutine error_on_mkfile: not called CC=1 SCAR=6.9
Pod undocumented
668 0 my ($self, $data) = @_;
669  
670 0 my $error = $self->error->sysinfo;
671  
672 0 my $message = 'Can\'t make file "{{path}}": {{error}}';
673  
674 0 $error->name('on.mkfile');
675 0 $error->message($message);
676 0 $error->offset(1);
677 0 $error->stash($data);
678 0 $error->reset;
679  
680 0 return $error;
681 }
682  
683 1 ▶sub error_on_move {
Subroutine error_on_move: called CC=1 SCAR=0.0
Pod undocumented
684 1 my ($self, $data) = @_;
685  
686 1 my $error = $self->error->sysinfo;
687  
688 1 my $message = 'Can\'t move "{{self}}" to "{{path}}": {{error}}';
689  
690 1 $error->name('on.move');
691 1 $error->message($message);
692 1 $error->offset(1);
693 1 $error->stash($data);
694 1 $error->reset;
695  
696 1 return $error;
697 }
698  
699 4 ▶sub error_on_open {
Subroutine error_on_open: called CC=1 SCAR=0.0
Pod undocumented
700 4 my ($self, $data) = @_;
701  
702 4 my $error = $self->error->sysinfo;
703  
704 4 my $message = 'Can\'t open "{{path}}": {{error}}';
705  
706 4 $error->name('on.open');
707 4 $error->message($message);
708 4 $error->offset(1);
709 4 $error->stash($data);
710 4 $error->reset;
711  
712 4 return $error;
713 }
714  
715 3 ▶sub error_on_read {
Subroutine error_on_read: called CC=1 SCAR=0.0
Pod undocumented
716 3 my ($self, $data) = @_;
717  
718 3 my $error = $self->error->sysinfo;
719  
720 3 my $message = 'Can\'t read "{{path}}": {{error}}';
721  
722 3 $error->name('on.read');
723 3 $error->message($message);
724 3 $error->offset(1);
725 3 $error->stash($data);
726 3 $error->reset;
727  
728 3 return $error;
729 }
730  
731 1 ▶sub error_on_rmdir {
Subroutine error_on_rmdir: called CC=1 SCAR=0.0
Pod undocumented
732 1 my ($self, $data) = @_;
733  
734 1 my $error = $self->error->sysinfo;
735  
736 1 my $message = 'Can\'t rmdir "{{path}}": {{error}}';
737  
738 1 $error->name('on.rmdir');
739 1 $error->message($message);
740 1 $error->offset(1);
741 1 $error->stash($data);
742 1 $error->reset;
743  
744 1 return $error;
745 }
746  
747 2 ▶sub error_on_write {
Subroutine error_on_write: called CC=1 SCAR=0.0
Pod undocumented
748 2 my ($self, $data) = @_;
749  
750 2 my $error = $self->error->sysinfo;
751  
752 2 my $message = 'Can\'t write "{{path}}": {{error}}';
753  
754 2 $error->name('on.write');
755 2 $error->message($message);
756 2 $error->offset(1);
757 2 $error->stash($data);
758 2 $error->reset;
759  
760 2 return $error;
761 }
762  
763 2 ▶sub error_on_unlink {
Subroutine error_on_unlink: called CC=1 SCAR=0.0
Pod undocumented
764 2 my ($self, $data) = @_;
765  
766 2 my $error = $self->error->sysinfo;
767  
768 2 my $message = 'Can\'t unlink "{{path}}": {{error}}';
769  
770 2 $error->name('on.unlink');
771 2 $error->message($message);
772 2 $error->offset(1);
773 2 $error->stash($data);
774 2 $error->reset;
775  
776 2 return $error;
777 }
778  
779 119 1;
780  
781  
782  
783 =head1 NAME
784  
785 Venus::Path - Path Class
786  
787 =cut
788  
789 =head1 ABSTRACT
790  
791 Path Class for Perl 5
792  
793 =cut
794  
795 =head1 SYNOPSIS
796  
797 package main;
798  
799 use Venus::Path;
800  
801 my $path = Venus::Path->new('t/data/planets');
802  
803 # my $planets = $path->files;
804 # my $mercury = $path->child('mercury');
805 # my $content = $mercury->read;
806  
807 =cut
808  
809 =head1 DESCRIPTION
810  
811 This package provides methods for working with file system paths.
812  
813 =cut
814  
815 =head1 INHERITS
816  
817 This package inherits behaviors from:
818  
819 L<Venus::Kind::Utility>
820  
821 =cut
822  
823 =head1 INTEGRATES
824  
825 This package integrates behaviors from:
826  
827 L<Venus::Role::Accessible>
828  
829 L<Venus::Role::Buildable>
830  
831 L<Venus::Role::Explainable>
832  
833 L<Venus::Role::Valuable>
834  
835 =cut
836  
837 =head1 METHODS
838  
839 This package provides the following methods:
840  
841 =cut
842  
843 =head2 absolute
844  
845 absolute() (Venus::Path)
846  
847 The absolute method returns a path object where the value (path) is absolute.
848  
849 I<Since C<0.01>>
850  
851 =over 4
852  
853 =item absolute example 1
854  
855 # given: synopsis;
856  
857 $path = $path->absolute;
858  
859 # bless({ value => "/path/to/t/data/planets" }, "Venus::Path")
860  
861 =back
862  
863 =cut
864  
865 =head2 basename
866  
867 basename() (string)
868  
869 The basename method returns the path base name.
870  
871 I<Since C<0.01>>
872  
873 =over 4
874  
875 =item basename example 1
876  
877 # given: synopsis;
878  
879 my $basename = $path->basename;
880  
881 # planets
882  
883 =back
884  
885 =cut
886  
887 =head2 child
888  
889 child(string $path) (Venus::Path)
890  
891 The child method returns a path object representing the child path provided.
892  
893 I<Since C<0.01>>
894  
895 =over 4
896  
897 =item child example 1
898  
899 # given: synopsis;
900  
901 $path = $path->child('earth');
902  
903 # bless({ value => "t/data/planets/earth" }, "Venus::Path")
904  
905 =back
906  
907 =cut
908  
909 =head2 children
910  
911 children() (within[arrayref, Venus::Path])
912  
913 The children method returns the files and directories under the path. This
914 method can return a list of values in list-context.
915  
916 I<Since C<0.01>>
917  
918 =over 4
919  
920 =item children example 1
921  
922 # given: synopsis;
923  
924 my $children = $path->children;
925  
926 # [
927 # bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
928 # bless({ value => "t/data/planets/earth" }, "Venus::Path"),
929 # bless({ value => "t/data/planets/eris" }, "Venus::Path"),
930 # bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
931 # bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
932 # bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
933 # bless({ value => "t/data/planets/mars" }, "Venus::Path"),
934 # bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
935 # bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
936 # bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
937 # bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
938 # bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
939 # bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
940 # bless({ value => "t/data/planets/venus" }, "Venus::Path"),
941 # ]
942  
943 =back
944  
945 =cut
946  
947 =head2 chmod
948  
949 chmod(string $mode) (Venus::Path)
950  
951 The chmod method changes the file permissions of the file or directory.
952  
953 I<Since C<0.01>>
954  
955 =over 4
956  
957 =item chmod example 1
958  
959 # given: synopsis;
960  
961 $path = $path->chmod(0755);
962  
963 # bless({ value => "t/data/planets" }, "Venus::Path")
964  
965 =back
966  
967 =cut
968  
969 =head2 chown
970  
971 chown(string @args) (Venus::Path)
972  
973 The chown method changes the group and/or owner or the file or directory.
974  
975 I<Since C<0.01>>
976  
977 =over 4
978  
979 =item chown example 1
980  
981 # given: synopsis;
982  
983 $path = $path->chown(-1, -1);
984  
985 # bless({ value => "t/data/planets" }, "Venus::Path")
986  
987 =back
988  
989 =cut
990  
991 =head2 copy
992  
993 copy(string | Venus::Path $path) (Venus::Path)
994  
995 The copy method uses L<File::Copy/copy> to copy the file represented by the
996 invocant to the path provided and returns the invocant.
997  
998 I<Since C<2.80>>
999  
1000 =over 4
1001  
1002 =item copy example 1
1003  
1004 # given: synopsis
1005  
1006 package main;
1007  
1008 my $copy = $path->child('mercury')->copy($path->child('yrucrem'));
1009  
1010 # bless({...}, 'Venus::Path')
1011  
1012 =back
1013  
1014 =over 4
1015  
1016 =item B<may raise> L<Venus::Path::Error> C<on.copy>
1017  
1018 package main;
1019  
1020 use Venus::Path;
1021  
1022 my $path = Venus::Path->new('t/data/planets');
1023  
1024 $path->copy('/path/to/nowhere');
1025  
1026 # Error! (on.copy)
1027  
1028 =back
1029  
1030 =cut
1031  
1032 =head2 default
1033  
1034 default() (string)
1035  
1036 The default method returns the default value, i.e. C<$ENV{PWD}>.
1037  
1038 I<Since C<0.01>>
1039  
1040 =over 4
1041  
1042 =item default example 1
1043  
1044 # given: synopsis;
1045  
1046 my $default = $path->default;
1047  
1048 # $ENV{PWD}
1049  
1050 =back
1051  
1052 =cut
1053  
1054 =head2 directories
1055  
1056 directories() (within[arrayref, Venus::Path])
1057  
1058 The directories method returns a list of children under the path which are
1059 directories. This method can return a list of values in list-context.
1060  
1061 I<Since C<0.01>>
1062  
1063 =over 4
1064  
1065 =item directories example 1
1066  
1067 # given: synopsis;
1068  
1069 my $directories = $path->directories;
1070  
1071 # []
1072  
1073 =back
1074  
1075 =cut
1076  
1077 =head2 exists
1078  
1079 exists() (boolean)
1080  
1081 The exists method returns truthy or falsy if the path exists.
1082  
1083 I<Since C<0.01>>
1084  
1085 =over 4
1086  
1087 =item exists example 1
1088  
1089 # given: synopsis;
1090  
1091 my $exists = $path->exists;
1092  
1093 # 1
1094  
1095 =back
1096  
1097 =over 4
1098  
1099 =item exists example 2
1100  
1101 # given: synopsis;
1102  
1103 my $exists = $path->child('random')->exists;
1104  
1105 # 0
1106  
1107 =back
1108  
1109 =cut
1110  
1111 =head2 explain
1112  
1113 explain() (string)
1114  
1115 The explain method returns the path string and is used in stringification
1116 operations.
1117  
1118 I<Since C<0.01>>
1119  
1120 =over 4
1121  
1122 =item explain example 1
1123  
1124 # given: synopsis;
1125  
1126 my $explain = $path->explain;
1127  
1128 # t/data/planets
1129  
1130 =back
1131  
1132 =cut
1133  
1134 =head2 extension
1135  
1136 extension(string $name) (string | Venus::Path)
1137  
1138 The extension method returns a new path object using the extension name
1139 provided. If no argument is provided this method returns the extension for the
1140 path represented by the invocant, otherwise returns undefined.
1141  
1142 I<Since C<2.55>>
1143  
1144 =over 4
1145  
1146 =item extension example 1
1147  
1148 package main;
1149  
1150 use Venus::Path;
1151  
1152 my $path = Venus::Path->new('t/Venus_Path.t');
1153  
1154 my $extension = $path->extension;
1155  
1156 # "t"
1157  
1158 =back
1159  
1160 =over 4
1161  
1162 =item extension example 2
1163  
1164 package main;
1165  
1166 use Venus::Path;
1167  
1168 my $path = Venus::Path->new('t/data/mercury');
1169  
1170 my $extension = $path->extension('txt');
1171  
1172 # bless({ value => "t/data/mercury.txt"}, "Venus::Path")
1173  
1174 =back
1175  
1176 =over 4
1177  
1178 =item extension example 3
1179  
1180 package main;
1181  
1182 use Venus::Path;
1183  
1184 my $path = Venus::Path->new('t/data');
1185  
1186 my $extension = $path->extension;
1187  
1188 # undef
1189  
1190 =back
1191  
1192 =over 4
1193  
1194 =item extension example 4
1195  
1196 package main;
1197  
1198 use Venus::Path;
1199  
1200 my $path = Venus::Path->new('t/data');
1201  
1202 my $extension = $path->extension('txt');
1203  
1204 # bless({ value => "t/data.txt"}, "Venus::Path")
1205  
1206 =back
1207  
1208 =cut
1209  
1210 =head2 files
1211  
1212 files() (within[arrayref, Venus::Path])
1213  
1214 The files method returns a list of children under the path which are files.
1215 This method can return a list of values in list-context.
1216  
1217 I<Since C<0.01>>
1218  
1219 =over 4
1220  
1221 =item files example 1
1222  
1223 # given: synopsis;
1224  
1225 my $files = $path->files;
1226  
1227 # [
1228 # bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
1229 # bless({ value => "t/data/planets/earth" }, "Venus::Path"),
1230 # bless({ value => "t/data/planets/eris" }, "Venus::Path"),
1231 # bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
1232 # bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
1233 # bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
1234 # bless({ value => "t/data/planets/mars" }, "Venus::Path"),
1235 # bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
1236 # bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
1237 # bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
1238 # bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
1239 # bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
1240 # bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
1241 # bless({ value => "t/data/planets/venus" }, "Venus::Path"),
1242 # ]
1243  
1244 =back
1245  
1246 =cut
1247  
1248 =head2 find
1249  
1250 find(string | regexp $expr) (within[arrayref, Venus::Path])
1251  
1252 The find method does a recursive depth-first search and returns a list of paths
1253 found, matching the expression provided, which defaults to C<*>. This method
1254 can return a list of values in list-context.
1255  
1256 I<Since C<0.01>>
1257  
1258 =over 4
1259  
1260 =item find example 1
1261  
1262 # given: synopsis;
1263  
1264 my $find = $path->find;
1265  
1266 # [
1267 # bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
1268 # bless({ value => "t/data/planets/earth" }, "Venus::Path"),
1269 # bless({ value => "t/data/planets/eris" }, "Venus::Path"),
1270 # bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
1271 # bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
1272 # bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
1273 # bless({ value => "t/data/planets/mars" }, "Venus::Path"),
1274 # bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
1275 # bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
1276 # bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
1277 # bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
1278 # bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
1279 # bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
1280 # bless({ value => "t/data/planets/venus" }, "Venus::Path"),
1281 # ]
1282  
1283 =back
1284  
1285 =over 4
1286  
1287 =item find example 2
1288  
1289 # given: synopsis;
1290  
1291 my $find = $path->find('[:\/\\\.]+m[^:\/\\\.]*$');
1292  
1293 # [
1294 # bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
1295 # bless({ value => "t/data/planets/mars" }, "Venus::Path"),
1296 # bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
1297 # ]
1298  
1299 =back
1300  
1301 =over 4
1302  
1303 =item find example 3
1304  
1305 # given: synopsis;
1306  
1307 my $find = $path->find('earth');
1308  
1309 # [
1310 # bless({ value => "t/data/planets/earth" }, "Venus::Path"),
1311 # ]
1312  
1313 =back
1314  
1315 =cut
1316  
1317 =head2 glob
1318  
1319 glob(string | regexp $expr) (within[arrayref, Venus::Path])
1320  
1321 The glob method returns the files and directories under the path matching the
1322 expression provided, which defaults to C<*>. This method can return a list of
1323 values in list-context.
1324  
1325 I<Since C<0.01>>
1326  
1327 =over 4
1328  
1329 =item glob example 1
1330  
1331 # given: synopsis;
1332  
1333 my $glob = $path->glob;
1334  
1335 # [
1336 # bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
1337 # bless({ value => "t/data/planets/earth" }, "Venus::Path"),
1338 # bless({ value => "t/data/planets/eris" }, "Venus::Path"),
1339 # bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
1340 # bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
1341 # bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
1342 # bless({ value => "t/data/planets/mars" }, "Venus::Path"),
1343 # bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
1344 # bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
1345 # bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
1346 # bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
1347 # bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
1348 # bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
1349 # bless({ value => "t/data/planets/venus" }, "Venus::Path"),
1350 # ]
1351  
1352 =back
1353  
1354 =cut
1355  
1356 =head2 is_absolute
1357  
1358 is_absolute() (boolean)
1359  
1360 The is_absolute method returns truthy or falsy is the path is absolute.
1361  
1362 I<Since C<0.01>>
1363  
1364 =over 4
1365  
1366 =item is_absolute example 1
1367  
1368 # given: synopsis;
1369  
1370 my $is_absolute = $path->is_absolute;
1371  
1372 # 0
1373  
1374 =back
1375  
1376 =cut
1377  
1378 =head2 is_directory
1379  
1380 is_directory() (boolean)
1381  
1382 The is_directory method returns truthy or falsy is the path is a directory.
1383  
1384 I<Since C<0.01>>
1385  
1386 =over 4
1387  
1388 =item is_directory example 1
1389  
1390 # given: synopsis;
1391  
1392 my $is_directory = $path->is_directory;
1393  
1394 # 1
1395  
1396 =back
1397  
1398 =cut
1399  
1400 =head2 is_file
1401  
1402 is_file() (boolean)
1403  
1404 The is_file method returns truthy or falsy is the path is a file.
1405  
1406 I<Since C<0.01>>
1407  
1408 =over 4
1409  
1410 =item is_file example 1
1411  
1412 # given: synopsis;
1413  
1414 my $is_file = $path->is_file;
1415  
1416 # 0
1417  
1418 =back
1419  
1420 =cut
1421  
1422 =head2 is_relative
1423  
1424 is_relative() (boolean)
1425  
1426 The is_relative method returns truthy or falsy is the path is relative.
1427  
1428 I<Since C<0.01>>
1429  
1430 =over 4
1431  
1432 =item is_relative example 1
1433  
1434 # given: synopsis;
1435  
1436 my $is_relative = $path->is_relative;
1437  
1438 # 1
1439  
1440 =back
1441  
1442 =cut
1443  
1444 =head2 lineage
1445  
1446 lineage() (within[arrayref, Venus::Path])
1447  
1448 The lineage method returns the list of parent paths up to the root path. This
1449 method can return a list of values in list-context.
1450  
1451 I<Since C<0.01>>
1452  
1453 =over 4
1454  
1455 =item lineage example 1
1456  
1457 # given: synopsis;
1458  
1459 my $lineage = $path->lineage;
1460  
1461 # [
1462 # bless({ value => "t/data/planets" }, "Venus::Path"),
1463 # bless({ value => "t/data" }, "Venus::Path"),
1464 # bless({ value => "t" }, "Venus::Path"),
1465 # ]
1466  
1467 =back
1468  
1469 =cut
1470  
1471 =head2 lines
1472  
1473 lines(string | regexp $separator, string $binmode) (within[arrayref, string])
1474  
1475 The lines method returns the list of lines from the underlying file. By default
1476 the file contents are separated by newline.
1477  
1478 I<Since C<1.23>>
1479  
1480 =over 4
1481  
1482 =item lines example 1
1483  
1484 # given: synopsis;
1485  
1486 my $lines = $path->child('mercury')->lines;
1487  
1488 # ['mercury']
1489  
1490 =back
1491  
1492 =over 4
1493  
1494 =item lines example 2
1495  
1496 # given: synopsis;
1497  
1498 my $lines = $path->child('planet9')->lines;
1499  
1500 # ['planet', 'nine']
1501  
1502 =back
1503  
1504 =cut
1505  
1506 =head2 mkcall
1507  
1508 mkcall(any @data) (any)
1509  
1510 The mkcall method returns the result of executing the path as an executable. In
1511 list context returns the call output and exit code.
1512  
1513 I<Since C<0.01>>
1514  
1515 =over 4
1516  
1517 =item mkcall example 1
1518  
1519 package main;
1520  
1521 use Venus::Path;
1522  
1523 my $path = Venus::Path->new($^X);
1524  
1525 my $output = $path->mkcall('--help');
1526  
1527 # Usage: perl ...
1528  
1529 =back
1530  
1531 =over 4
1532  
1533 =item mkcall example 2
1534  
1535 package main;
1536  
1537 use Venus::Path;
1538  
1539 my $path = Venus::Path->new($^X);
1540  
1541 my ($call_output, $exit_code) = $path->mkcall('t/data/sun', '--heat-death');
1542  
1543 # ("", 1)
1544  
1545 =back
1546  
1547 =over 4
1548  
1549 =item mkcall example 3
1550  
1551 package main;
1552  
1553 use Venus::Path;
1554  
1555 my $path = Venus::Path->new('.help');
1556  
1557 my $output = $path->mkcall;
1558  
1559 # Exception! (isa Venus::Path::Error) (see error_on_mkcall)
1560  
1561 =back
1562  
1563 =cut
1564  
1565 =head2 mkdir
1566  
1567 mkdir(maybe[string] $mode) (Venus::Path)
1568  
1569 The mkdir method makes the path as a directory.
1570  
1571 I<Since C<0.01>>
1572  
1573 =over 4
1574  
1575 =item mkdir example 1
1576  
1577 package main;
1578  
1579 use Venus::Path;
1580  
1581 my $path = Venus::Path->new('t/data/systems');
1582  
1583 $path = $path->mkdir;
1584  
1585 # bless({ value => "t/data/systems" }, "Venus::Path")
1586  
1587 =back
1588  
1589 =over 4
1590  
1591 =item mkdir example 2
1592  
1593 package main;
1594  
1595 use Venus::Path;
1596  
1597 my $path = Venus::Path->new('/path/to/xyz');
1598  
1599 $path = $path->mkdir;
1600  
1601 # Exception! (isa Venus::Path::Error) (see error_on_mkdir)
1602  
1603 =back
1604  
1605 =over 4
1606  
1607 =item B<may raise> L<Venus::Path::Error> C<on.mkdir>
1608  
1609 package main;
1610  
1611 use Venus::Path;
1612  
1613 my $path = Venus::Path->new('/path/to/nowhere');
1614  
1615 $path->mkdir;
1616  
1617 # Error! (on.mkdir)
1618  
1619 =back
1620  
1621 =cut
1622  
1623 =head2 mkdirs
1624  
1625 mkdirs(maybe[string] $mode) (within[arrayref, Venus::Path])
1626  
1627 The mkdirs method creates parent directories and returns the list of created
1628 directories. This method can return a list of values in list-context.
1629  
1630 I<Since C<0.01>>
1631  
1632 =over 4
1633  
1634 =item mkdirs example 1
1635  
1636 package main;
1637  
1638 use Venus::Path;
1639  
1640 my $path = Venus::Path->new('t/data/systems');
1641  
1642 my $mkdirs = $path->mkdirs;
1643  
1644 # [
1645 # bless({ value => "t/data/systems" }, "Venus::Path")
1646 # ]
1647  
1648 =back
1649  
1650 =over 4
1651  
1652 =item mkdirs example 2
1653  
1654 package main;
1655  
1656 use Venus::Path;
1657  
1658 my $path = Venus::Path->new('t/data/systems/solar');
1659  
1660 my $mkdirs = $path->mkdirs;
1661  
1662 # [
1663 # bless({ value => "t/data/systems" }, "Venus::Path"),
1664 # bless({ value => "t/data/systems/solar" }, "Venus::Path"),
1665 # ]
1666  
1667 =back
1668  
1669 =cut
1670  
1671 =head2 mkfile
1672  
1673 mkfile() (Venus::Path)
1674  
1675 The mkfile method makes the path as an empty file.
1676  
1677 I<Since C<0.01>>
1678  
1679 =over 4
1680  
1681 =item mkfile example 1
1682  
1683 package main;
1684  
1685 use Venus::Path;
1686  
1687 my $path = Venus::Path->new('t/data/moon');
1688  
1689 $path = $path->mkfile;
1690  
1691 # bless({ value => "t/data/moon" }, "Venus::Path")
1692  
1693 =back
1694  
1695 =over 4
1696  
1697 =item mkfile example 2
1698  
1699 package main;
1700  
1701 use Venus::Path;
1702  
1703 my $path = Venus::Path->new('/path/to/xyz');
1704  
1705 $path = $path->mkfile;
1706  
1707 # Exception! (isa Venus::Path::Error) (see error_on_mkfile)
1708  
1709 =back
1710  
1711 =over 4
1712  
1713 =item B<may raise> L<Venus::Path::Error> C<on.mkfile>
1714  
1715 package main;
1716  
1717 use Venus::Path;
1718  
1719 my $path = Venus::Path->new('/path/to/nowhere/file.txt');
1720  
1721 $path->mkfile;
1722  
1723 # Error! (on.mkfile)
1724  
1725 =back
1726  
1727 =cut
1728  
1729 =head2 mktemp_dir
1730  
1731 mktemp_dir() (Venus::Path)
1732  
1733 The mktemp_dir method uses L<File::Temp/tempdir> to create a temporary
1734 directory which isn't automatically removed and returns a new path object.
1735  
1736 I<Since C<2.80>>
1737  
1738 =over 4
1739  
1740 =item mktemp_dir example 1
1741  
1742 # given: synopsis
1743  
1744 package main;
1745  
1746 my $mktemp_dir = $path->mktemp_dir;
1747  
1748 # bless({value => "/tmp/ZnKTxBpuBE"}, "Venus::Path")
1749  
1750 =back
1751  
1752 =cut
1753  
1754 =head2 mktemp_file
1755  
1756 mktemp_file() (Venus::Path)
1757  
1758 The mktemp_file method uses L<File::Temp/tempfile> to create a temporary file
1759 which isn't automatically removed and returns a new path object.
1760  
1761 I<Since C<2.80>>
1762  
1763 =over 4
1764  
1765 =item mktemp_file example 1
1766  
1767 # given: synopsis
1768  
1769 package main;
1770  
1771 my $mktemp_file = $path->mktemp_file;
1772  
1773 # bless({value => "/tmp/y5MvliBQ2F"}, "Venus::Path")
1774  
1775 =back
1776  
1777 =cut
1778  
1779 =head2 move
1780  
1781 move(string | Venus::Path $path) (Venus::Path)
1782  
1783 The move method uses L<File::Copy/move> to move the file represented by the
1784 invocant to the path provided and returns the invocant.
1785  
1786 I<Since C<2.80>>
1787  
1788 =over 4
1789  
1790 =item move example 1
1791  
1792 package main;
1793  
1794 use Venus::Path;
1795  
1796 my $path = Venus::Path->new('t/data');
1797  
1798 my $unknown = $path->child('unknown')->mkfile->move($path->child('titan'));
1799  
1800 # bless({value => 't/data/titan'}, 'Venus::Path')
1801  
1802 =back
1803  
1804 =over 4
1805  
1806 =item B<may raise> L<Venus::Path::Error> C<on.move>
1807  
1808 package main;
1809  
1810 use Venus::Path;
1811  
1812 my $path = Venus::Path->new('t/data/planets');
1813  
1814 $path->move('/path/to/nowhere');
1815  
1816 # Error! (on.move)
1817  
1818 =back
1819  
1820 =cut
1821  
1822 =head2 name
1823  
1824 name() (string)
1825  
1826 The name method returns the path as an absolute path.
1827  
1828 I<Since C<0.01>>
1829  
1830 =over 4
1831  
1832 =item name example 1
1833  
1834 # given: synopsis;
1835  
1836 my $name = $path->name;
1837  
1838 # /path/to/t/data/planets
1839  
1840 =back
1841  
1842 =cut
1843  
1844 =head2 new
1845  
1846 new(any @args) (Venus::Path)
1847  
1848 The new method constructs an instance of the package.
1849  
1850 I<Since C<4.15>>
1851  
1852 =over 4
1853  
1854 =item new example 1
1855  
1856 package main;
1857  
1858 use Venus::Path;
1859  
1860 my $new = Venus::Path->new;
1861  
1862 # bless(..., "Venus::Path")
1863  
1864 =back
1865  
1866 =over 4
1867  
1868 =item new example 2
1869  
1870 package main;
1871  
1872 use Venus::Path;
1873  
1874 my $new = Venus::Path->new('t/data/planets');
1875  
1876 # bless(..., "Venus::Path")
1877  
1878 =back
1879  
1880 =over 4
1881  
1882 =item new example 3
1883  
1884 package main;
1885  
1886 use Venus::Path;
1887  
1888 my $new = Venus::Path->new(value => 't/data/planets');
1889  
1890 # bless(..., "Venus::Path")
1891  
1892 =back
1893  
1894 =cut
1895  
1896 =head2 open
1897  
1898 open(any @data) (FileHandle)
1899  
1900 The open method creates and returns an open filehandle.
1901  
1902 I<Since C<0.01>>
1903  
1904 =over 4
1905  
1906 =item open example 1
1907  
1908 package main;
1909  
1910 use Venus::Path;
1911  
1912 my $path = Venus::Path->new('t/data/planets/earth');
1913  
1914 my $fh = $path->open;
1915  
1916 # bless(..., "IO::File");
1917  
1918 =back
1919  
1920 =over 4
1921  
1922 =item open example 2
1923  
1924 package main;
1925  
1926 use Venus::Path;
1927  
1928 my $path = Venus::Path->new('t/data/planets/earth');
1929  
1930 my $fh = $path->open('<');
1931  
1932 # bless(..., "IO::File");
1933  
1934 =back
1935  
1936 =over 4
1937  
1938 =item open example 3
1939  
1940 package main;
1941  
1942 use Venus::Path;
1943  
1944 my $path = Venus::Path->new('t/data/planets/earth');
1945  
1946 my $fh = $path->open('>');
1947  
1948 # bless(..., "IO::File");
1949  
1950 =back
1951  
1952 =over 4
1953  
1954 =item open example 4
1955  
1956 package main;
1957  
1958 use Venus::Path;
1959  
1960 my $path = Venus::Path->new('/path/to/xyz');
1961  
1962 my $fh = $path->open('>');
1963  
1964 # Exception! (isa Venus::Path::Error) (see error_on_open)
1965  
1966 =back
1967  
1968 =over 4
1969  
1970 =item B<may raise> L<Venus::Path::Error> C<on.open>
1971  
1972 package main;
1973  
1974 use Venus::Path;
1975  
1976 my $path = Venus::Path->new('/path/to/nowhere');
1977  
1978 $path->open;
1979  
1980 # Error! (on.open)
1981  
1982 =back
1983  
1984 =cut
1985  
1986 =head2 parent
1987  
1988 parent() (Venus::Path)
1989  
1990 The parent method returns a path object representing the parent directory.
1991  
1992 I<Since C<0.01>>
1993  
1994 =over 4
1995  
1996 =item parent example 1
1997  
1998 # given: synopsis;
1999  
2000 my $parent = $path->parent;
2001  
2002 # bless({ value => "t/data" }, "Venus::Path")
2003  
2004 =back
2005  
2006 =cut
2007  
2008 =head2 parents
2009  
2010 parents() (within[arrayref, Venus::Path])
2011  
2012 The parents method returns is a list of parent directories. This method can
2013 return a list of values in list-context.
2014  
2015 I<Since C<0.01>>
2016  
2017 =over 4
2018  
2019 =item parents example 1
2020  
2021 # given: synopsis;
2022  
2023 my $parents = $path->parents;
2024  
2025 # [
2026 # bless({ value => "t/data" }, "Venus::Path"),
2027 # bless({ value => "t" }, "Venus::Path"),
2028 # ]
2029  
2030 =back
2031  
2032 =cut
2033  
2034 =head2 parts
2035  
2036 parts() (within[arrayref, string])
2037  
2038 The parts method returns an arrayref of path parts.
2039  
2040 I<Since C<0.01>>
2041  
2042 =over 4
2043  
2044 =item parts example 1
2045  
2046 # given: synopsis;
2047  
2048 my $parts = $path->parts;
2049  
2050 # ["t", "data", "planets"]
2051  
2052 =back
2053  
2054 =cut
2055  
2056 =head2 read
2057  
2058 read() (string)
2059  
2060 The read method reads the file and returns its contents.
2061  
2062 I<Since C<0.01>>
2063  
2064 =over 4
2065  
2066 =item read example 1
2067  
2068 package main;
2069  
2070 use Venus::Path;
2071  
2072 my $path = Venus::Path->new('t/data/planets/mars');
2073  
2074 my $content = $path->read;
2075  
2076 =back
2077  
2078 =over 4
2079  
2080 =item read example 2
2081  
2082 package main;
2083  
2084 use Venus::Path;
2085  
2086 my $path = Venus::Path->new('/path/to/xyz');
2087  
2088 my $content = $path->read;
2089  
2090 # Exception! (isa Venus::Path::Error) (see error_on_read_open)
2091  
2092 =back
2093  
2094 =over 4
2095  
2096 =item B<may raise> L<Venus::Path::Error> C<on.read>
2097  
2098 package main;
2099  
2100 use Venus::Path;
2101  
2102 my $path = Venus::Path->new('/path/to/nowhere');
2103  
2104 $path->read;
2105  
2106 # Error! (on.read)
2107  
2108 =back
2109  
2110 =cut
2111  
2112 =head2 relative
2113  
2114 relative(string $root) (Venus::Path)
2115  
2116 The relative method returns a path object representing a relative path
2117 (relative to the path provided).
2118  
2119 I<Since C<0.01>>
2120  
2121 =over 4
2122  
2123 =item relative example 1
2124  
2125 package main;
2126  
2127 use Venus::Path;
2128  
2129 my $path = Venus::Path->new('/path/to/t/data/planets/mars');
2130  
2131 my $relative = $path->relative('/path');
2132  
2133 # bless({ value => "to/t/data/planets/mars" }, "Venus::Path")
2134  
2135 =back
2136  
2137 =over 4
2138  
2139 =item relative example 2
2140  
2141 package main;
2142  
2143 use Venus::Path;
2144  
2145 my $path = Venus::Path->new('/path/to/t/data/planets/mars');
2146  
2147 my $relative = $path->relative('/path/to/t');
2148  
2149 # bless({ value => "data/planets/mars" }, "Venus::Path")
2150  
2151 =back
2152  
2153 =cut
2154  
2155 =head2 rename
2156  
2157 rename(string | Venus::Path $path) (Venus::Path)
2158  
2159 The rename method performs a L</move> unless the path provided is only a file
2160 name, in which case it attempts a rename under the directory of the invocant.
2161  
2162 I<Since C<2.91>>
2163  
2164 =over 4
2165  
2166 =item rename example 1
2167  
2168 package main;
2169  
2170 use Venus::Path;
2171  
2172 my $path = Venus::Path->new('t/path/001');
2173  
2174 my $rename = $path->rename('002');
2175  
2176 # bless({value => 't/path/002'}, 'Venus::Path')
2177  
2178 =back
2179  
2180 =cut
2181  
2182 =head2 rmdir
2183  
2184 rmdir() (Venus::Path)
2185  
2186 The rmdir method removes the directory and returns a path object representing
2187 the deleted directory.
2188  
2189 I<Since C<0.01>>
2190  
2191 =over 4
2192  
2193 =item rmdir example 1
2194  
2195 package main;
2196  
2197 use Venus::Path;
2198  
2199 my $path = Venus::Path->new('t/data/stars');
2200  
2201 my $rmdir = $path->mkdir->rmdir;
2202  
2203 # bless({ value => "t/data/stars" }, "Venus::Path")
2204  
2205 =back
2206  
2207 =over 4
2208  
2209 =item rmdir example 2
2210  
2211 package main;
2212  
2213 use Venus::Path;
2214  
2215 my $path = Venus::Path->new('/path/to/xyz');
2216  
2217 my $rmdir = $path->mkdir->rmdir;
2218  
2219 # Exception! (isa Venus::Path::Error) (see error_on_rmdir)
2220  
2221 =back
2222  
2223 =over 4
2224  
2225 =item B<may raise> L<Venus::Path::Error> C<on.rmdir>
2226  
2227 package main;
2228  
2229 use Venus::Path;
2230  
2231 my $path = Venus::Path->new('/path/to/nowhere');
2232  
2233 $path->rmdir;
2234  
2235 # Error! (on.rmdir)
2236  
2237 =back
2238  
2239 =cut
2240  
2241 =head2 rmdirs
2242  
2243 rmdirs() (within[arrayref, Venus::Path])
2244  
2245 The rmdirs method removes that path and its child files and directories and
2246 returns all paths removed. This method can return a list of values in
2247 list-context.
2248  
2249 I<Since C<0.01>>
2250  
2251 =over 4
2252  
2253 =item rmdirs example 1
2254  
2255 package main;
2256  
2257 use Venus::Path;
2258  
2259 my $path = Venus::Path->new('t/data/stars');
2260  
2261 $path->child('dwarfs')->mkdirs;
2262  
2263 my $rmdirs = $path->rmdirs;
2264  
2265 # [
2266 # bless({ value => "t/data/stars/dwarfs" }, "Venus::Path"),
2267 # bless({ value => "t/data/stars" }, "Venus::Path"),
2268 # ]
2269  
2270 =back
2271  
2272 =cut
2273  
2274 =head2 rmfiles
2275  
2276 rmfiles() (within[arrayref, Venus::Path])
2277  
2278 The rmfiles method recursively removes files under the path and returns the
2279 paths removed. This method does not remove the directories found. This method
2280 can return a list of values in list-context.
2281  
2282 I<Since C<0.01>>
2283  
2284 =over 4
2285  
2286 =item rmfiles example 1
2287  
2288 package main;
2289  
2290 use Venus::Path;
2291  
2292 my $path = Venus::Path->new('t/data/stars')->mkdir;
2293  
2294 $path->child('sirius')->mkfile;
2295 $path->child('canopus')->mkfile;
2296 $path->child('arcturus')->mkfile;
2297 $path->child('vega')->mkfile;
2298 $path->child('capella')->mkfile;
2299  
2300 my $rmfiles = $path->rmfiles;
2301  
2302 # [
2303 # bless({ value => "t/data/stars/arcturus" }, "Venus::Path"),
2304 # bless({ value => "t/data/stars/canopus" }, "Venus::Path"),
2305 # bless({ value => "t/data/stars/capella" }, "Venus::Path"),
2306 # bless({ value => "t/data/stars/sirius" }, "Venus::Path"),
2307 # bless({ value => "t/data/stars/vega" }, "Venus::Path"),
2308 # ]
2309  
2310 =back
2311  
2312 =cut
2313  
2314 =head2 root
2315  
2316 root(string $spec, string $base) (maybe[Venus::Path])
2317  
2318 The root method performs a search up the file system heirarchy returns the
2319 first path (i.e. absolute path) matching the file test specification and base
2320 path expression provided. The file test specification is the same passed to
2321 L</test>. If no path matches are found this method returns underfined.
2322  
2323 I<Since C<2.32>>
2324  
2325 =over 4
2326  
2327 =item root example 1
2328  
2329 # given: synopsis;
2330  
2331 my $root = $path->root('d', 't');
2332  
2333 # bless({ value => "/path/to/t/../" }, "Venus::Path")
2334  
2335 =back
2336  
2337 =over 4
2338  
2339 =item root example 2
2340  
2341 # given: synopsis;
2342  
2343 my $root = $path->root('f', 't');
2344  
2345 # undef
2346  
2347 =back
2348  
2349 =cut
2350  
2351 =head2 seek
2352  
2353 seek(string $spec, string $base) (maybe[Venus::Path])
2354  
2355 The seek method performs a search down the file system heirarchy returns the
2356 first path (i.e. absolute path) matching the file test specification and base
2357 path expression provided. The file test specification is the same passed to
2358 L</test>. If no path matches are found this method returns underfined.
2359  
2360 I<Since C<2.32>>
2361  
2362 =over 4
2363  
2364 =item seek example 1
2365  
2366 # given: synopsis;
2367  
2368 $path = Venus::Path->new('t');
2369  
2370 my $seek = $path->seek('f', 'earth');
2371  
2372 # bless({ value => "/path/to/t/data/planets/earth" }, "Venus::Path")
2373  
2374 =back
2375  
2376 =over 4
2377  
2378 =item seek example 2
2379  
2380 # given: synopsis;
2381  
2382 $path = Venus::Path->new('t');
2383  
2384 my $seek = $path->seek('f', 'europa');
2385  
2386 # undef
2387  
2388 =back
2389  
2390 =cut
2391  
2392 =head2 sibling
2393  
2394 sibling(string $path) (Venus::Path)
2395  
2396 The sibling method returns a path object representing the sibling path provided.
2397  
2398 I<Since C<0.01>>
2399  
2400 =over 4
2401  
2402 =item sibling example 1
2403  
2404 # given: synopsis;
2405  
2406 my $sibling = $path->sibling('galaxies');
2407  
2408 # bless({ value => "t/data/galaxies" }, "Venus::Path")
2409  
2410 =back
2411  
2412 =cut
2413  
2414 =head2 siblings
2415  
2416 siblings() (within[arrayref, Venus::Path])
2417  
2418 The siblings method returns all sibling files and directories for the current
2419 path. This method can return a list of values in list-context.
2420  
2421 I<Since C<0.01>>
2422  
2423 =over 4
2424  
2425 =item siblings example 1
2426  
2427 # given: synopsis;
2428  
2429 my $siblings = $path->siblings;
2430  
2431 # [
2432 # bless({ value => "t/data/moon" }, "Venus::Path"),
2433 # bless({ value => "t/data/sections" }, "Venus::Path"),
2434 # bless({ value => "t/data/sun" }, "Venus::Path"),
2435 # bless({ value => "t/data/texts" }, "Venus::Path"),
2436 # ]
2437  
2438 =back
2439  
2440 =cut
2441  
2442 =head2 test
2443  
2444 test(string $expr) (boolean)
2445  
2446 The test method evaluates the current path against the stackable file test
2447 operators provided.
2448  
2449 I<Since C<0.01>>
2450  
2451 =over 4
2452  
2453 =item test example 1
2454  
2455 # given: synopsis;
2456  
2457 my $test = $path->test;
2458  
2459 # -e $path
2460  
2461 # 1
2462  
2463 =back
2464  
2465 =over 4
2466  
2467 =item test example 2
2468  
2469 package main;
2470  
2471 use Venus::Path;
2472  
2473 my $path = Venus::Path->new('t/data/sun');
2474  
2475 my $test = $path->test('efs');
2476  
2477 # -e -f -s $path
2478  
2479 # 1
2480  
2481 =back
2482  
2483 =cut
2484  
2485 =head2 unlink
2486  
2487 unlink() (Venus::Path)
2488  
2489 The unlink method removes the file and returns a path object representing the
2490 removed file.
2491  
2492 I<Since C<0.01>>
2493  
2494 =over 4
2495  
2496 =item unlink example 1
2497  
2498 package main;
2499  
2500 use Venus::Path;
2501  
2502 my $path = Venus::Path->new('t/data/asteroid')->mkfile;
2503  
2504 my $unlink = $path->unlink;
2505  
2506 # bless({ value => "t/data/asteroid" }, "Venus::Path")
2507  
2508 =back
2509  
2510 =over 4
2511  
2512 =item unlink example 2
2513  
2514 package main;
2515  
2516 use Venus::Path;
2517  
2518 my $path = Venus::Path->new('/path/to/xyz');
2519  
2520 my $unlink = $path->unlink;
2521  
2522 # Exception! (isa Venus::Path::Error) (see error_on_unlink)
2523  
2524 =back
2525  
2526 =over 4
2527  
2528 =item B<may raise> L<Venus::Path::Error> C<on.unlink>
2529  
2530 package main;
2531  
2532 use Venus::Path;
2533  
2534 my $path = Venus::Path->new('/path/to/nowhere');
2535  
2536 $path->unlink;
2537  
2538 # Error! (on.unlink)
2539  
2540 =back
2541  
2542 =cut
2543  
2544 =head2 write
2545  
2546 write(string $data, string $encoding) (Venus::Path)
2547  
2548 The write method write the data provided to the file.
2549  
2550 I<Since C<0.01>>
2551  
2552 =over 4
2553  
2554 =item write example 1
2555  
2556 package main;
2557  
2558 use Venus::Path;
2559  
2560 my $path = Venus::Path->new('t/data/asteroid');
2561  
2562 my $write = $path->write('asteroid');
2563  
2564 =back
2565  
2566 =over 4
2567  
2568 =item write example 2
2569  
2570 package main;
2571  
2572 use Venus::Path;
2573  
2574 my $path = Venus::Path->new('/path/to/xyz');
2575  
2576 my $write = $path->write('nothing');
2577  
2578 # Exception! (isa Venus::Path::Error) (see error_on_write_open)
2579  
2580 =back
2581  
2582 =over 4
2583  
2584 =item B<may raise> L<Venus::Path::Error> C<on.write>
2585  
2586 package main;
2587  
2588 use Venus::Path;
2589  
2590 my $path = Venus::Path->new('/path/to/nowhere/file.txt');
2591  
2592 $path->write('content');
2593  
2594 # Error! (on.write)
2595  
2596 =back
2597  
2598 =cut
2599  
2600 =head1 OPERATORS
2601  
2602 This package overloads the following operators:
2603  
2604 =cut
2605  
2606 =over 4
2607  
2608 =item operation: C<("")>
2609  
2610 This package overloads the C<""> operator.
2611  
2612 B<example 1>
2613  
2614 # given: synopsis;
2615  
2616 my $result = "$path";
2617  
2618 # "t/data/planets"
2619  
2620 B<example 2>
2621  
2622 # given: synopsis;
2623  
2624 my $mercury = $path->child('mercury');
2625  
2626 my $result = "$path, $path";
2627  
2628 # "t/data/planets, t/data/planets"
2629  
2630 =back
2631  
2632 =over 4
2633  
2634 =item operation: C<(.)>
2635  
2636 This package overloads the C<.> operator.
2637  
2638 B<example 1>
2639  
2640 # given: synopsis;
2641  
2642 my $result = $path . '/earth';
2643  
2644 # "t/data/planets/earth"
2645  
2646 =back
2647  
2648 =over 4
2649  
2650 =item operation: C<(eq)>
2651  
2652 This package overloads the C<eq> operator.
2653  
2654 B<example 1>
2655  
2656 # given: synopsis;
2657  
2658 my $result = $path eq 't/data/planets';
2659  
2660 # 1
2661  
2662 =back
2663  
2664 =over 4
2665  
2666 =item operation: C<(ne)>
2667  
2668 This package overloads the C<ne> operator.
2669  
2670 B<example 1>
2671  
2672 # given: synopsis;
2673  
2674 my $result = $path ne 't/data/planets/';
2675  
2676 # 1
2677  
2678 =back
2679  
2680 =over 4
2681  
2682 =item operation: C<(qr)>
2683  
2684 This package overloads the C<qr> operator.
2685  
2686 B<example 1>
2687  
2688 # given: synopsis;
2689  
2690 my $result = 't/data/planets' =~ $path;
2691  
2692 # 1
2693  
2694 =back
2695  
2696 =over 4
2697  
2698 =item operation: C<(~~)>
2699  
2700 This package overloads the C<~~> operator.
2701  
2702 B<example 1>
2703  
2704 # given: synopsis;
2705  
2706 my $result = $path ~~ 't/data/planets';
2707  
2708 # 1
2709  
2710 =back
2711  
2712 =head1 AUTHORS
2713  
2714 Awncorp, C<awncorp@cpan.org>
2715  
2716 =cut
2717  
2718 =head1 LICENSE
2719  
2720 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
2721  
2722 This program is free software, you can redistribute it and/or modify it under
2723 the terms of the Apache license version 2.0.
2724  
2725 =cut
« blib/lib/Venus/Role/Fromable.pm ↑ Summary blib/lib/Venus/Constraint.pm »