/ 
Venus-2.40
River stage two • 3 direct dependents • 56 total dependents
/ Venus::Path

NAME

Venus::Path - Path Class

ABSTRACT

Path Class for Perl 5

SYNOPSIS

package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/planets');

# my $planets = $path->files;
# my $mercury = $path->child('mercury');
# my $content = $mercury->read;

DESCRIPTION

This package provides methods for working with file system paths.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Accessible

Venus::Role::Buildable

Venus::Role::Explainable

Venus::Role::Valuable

METHODS

This package provides the following methods:

absolute

absolute() (Path)

The absolute method returns a path object where the value (path) is absolute.

Since 0.01

absolute example 1
# given: synopsis;

$path = $path->absolute;

# bless({ value => "/path/to/t/data/planets" }, "Venus::Path")

basename

basename() (Str)

The basename method returns the path base name.

Since 0.01

basename example 1
# given: synopsis;

my $basename = $path->basename;

# planets

child

child(Str $path) (Path)

The child method returns a path object representing the child path provided.

Since 0.01

child example 1
# given: synopsis;

$path = $path->child('earth');

# bless({ value => "t/data/planets/earth" }, "Venus::Path")

children

children() (ArrayRef[Path])

The children method returns the files and directories under the path. This method can return a list of values in list-context.

Since 0.01

children example 1
# given: synopsis;

my $children = $path->children;

# [
#   bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
#   bless({ value => "t/data/planets/earth" }, "Venus::Path"),
#   bless({ value => "t/data/planets/eris" }, "Venus::Path"),
#   bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
#   bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
#   bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mars" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
#   bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
#   bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
#   bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
#   bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
#   bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
#   bless({ value => "t/data/planets/venus" }, "Venus::Path"),
# ]

chmod

chmod(Str $mode) (Path)

The chmod method changes the file permissions of the file or directory.

Since 0.01

chmod example 1
# given: synopsis;

$path = $path->chmod(0755);

# bless({ value => "t/data/planets" }, "Venus::Path")

chown

chown(Str @args) (Path)

The chown method changes the group and/or owner or the file or directory.

Since 0.01

chown example 1
# given: synopsis;

$path = $path->chown(-1, -1);

# bless({ value => "t/data/planets" }, "Venus::Path")

default

default() (Str)

The default method returns the default value, i.e. $ENV{PWD}.

Since 0.01

default example 1
# given: synopsis;

my $default = $path->default;

# $ENV{PWD}

directories

directories() (ArrayRef[Path])

The directories method returns a list of children under the path which are directories. This method can return a list of values in list-context.

Since 0.01

directories example 1
# given: synopsis;

my $directories = $path->directories;

# []

exists

exists() (Bool)

The exists method returns truthy or falsy if the path exists.

Since 0.01

exists example 1
# given: synopsis;

my $exists = $path->exists;

# 1
exists example 2
# given: synopsis;

my $exists = $path->child('random')->exists;

# 0

explain

explain() (Str)

The explain method returns the path string and is used in stringification operations.

Since 0.01

explain example 1
# given: synopsis;

my $explain = $path->explain;

# t/data/planets

files

files() (ArrayRef[Path])

The files method returns a list of children under the path which are files. This method can return a list of values in list-context.

Since 0.01

files example 1
# given: synopsis;

my $files = $path->files;

# [
#   bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
#   bless({ value => "t/data/planets/earth" }, "Venus::Path"),
#   bless({ value => "t/data/planets/eris" }, "Venus::Path"),
#   bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
#   bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
#   bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mars" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
#   bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
#   bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
#   bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
#   bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
#   bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
#   bless({ value => "t/data/planets/venus" }, "Venus::Path"),
# ]

find

find(Str | Regexp $expr) (ArrayRef[Path])

The find method does a recursive depth-first search and returns a list of paths found, matching the expression provided, which defaults to *. This method can return a list of values in list-context.

Since 0.01

find example 1
# given: synopsis;

my $find = $path->find;

# [
#   bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
#   bless({ value => "t/data/planets/earth" }, "Venus::Path"),
#   bless({ value => "t/data/planets/eris" }, "Venus::Path"),
#   bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
#   bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
#   bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mars" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
#   bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
#   bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
#   bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
#   bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
#   bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
#   bless({ value => "t/data/planets/venus" }, "Venus::Path"),
# ]
find example 2
# given: synopsis;

my $find = $path->find('[:\/\\\.]+m[^:\/\\\.]*$');

# [
#   bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mars" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
# ]
find example 3
# given: synopsis;

my $find = $path->find('earth');

# [
#   bless({ value => "t/data/planets/earth" }, "Venus::Path"),
# ]

glob

glob(Str | Regexp $expr) (ArrayRef[Path])

The glob method returns the files and directories under the path matching the expression provided, which defaults to *. This method can return a list of values in list-context.

Since 0.01

glob example 1
# given: synopsis;

my $glob = $path->glob;

# [
#   bless({ value => "t/data/planets/ceres" }, "Venus::Path"),
#   bless({ value => "t/data/planets/earth" }, "Venus::Path"),
#   bless({ value => "t/data/planets/eris" }, "Venus::Path"),
#   bless({ value => "t/data/planets/haumea" }, "Venus::Path"),
#   bless({ value => "t/data/planets/jupiter" }, "Venus::Path"),
#   bless({ value => "t/data/planets/makemake" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mars" }, "Venus::Path"),
#   bless({ value => "t/data/planets/mercury" }, "Venus::Path"),
#   bless({ value => "t/data/planets/neptune" }, "Venus::Path"),
#   bless({ value => "t/data/planets/planet9" }, "Venus::Path"),
#   bless({ value => "t/data/planets/pluto" }, "Venus::Path"),
#   bless({ value => "t/data/planets/saturn" }, "Venus::Path"),
#   bless({ value => "t/data/planets/uranus" }, "Venus::Path"),
#   bless({ value => "t/data/planets/venus" }, "Venus::Path"),
# ]

is_absolute

is_absolute() (Bool)

The is_absolute method returns truthy or falsy is the path is absolute.

Since 0.01

is_absolute example 1
# given: synopsis;

my $is_absolute = $path->is_absolute;

# 0

is_directory

is_directory() (Bool)

The is_directory method returns truthy or falsy is the path is a directory.

Since 0.01

is_directory example 1
# given: synopsis;

my $is_directory = $path->is_directory;

# 1

is_file

is_file() (Bool)

The is_file method returns truthy or falsy is the path is a file.

Since 0.01

is_file example 1
# given: synopsis;

my $is_file = $path->is_file;

# 0

is_relative

is_relative() (Bool)

The is_relative method returns truthy or falsy is the path is relative.

Since 0.01

is_relative example 1
# given: synopsis;

my $is_relative = $path->is_relative;

# 1

lineage

lineage() (ArrayRef[Path])

The lineage method returns the list of parent paths up to the root path. This method can return a list of values in list-context.

Since 0.01

lineage example 1
# given: synopsis;

my $lineage = $path->lineage;

# [
#   bless({ value => "t/data/planets" }, "Venus::Path"),
#   bless({ value => "t/data" }, "Venus::Path"),
#   bless({ value => "t" }, "Venus::Path"),
# ]

lines

lines(Str|Regexp $separator, Str $binmode) (ArrayRef[Str])

The lines method returns the list of lines from the underlying file. By default the file contents are separated by newline.

Since 1.23

lines example 1
# given: synopsis;

my $lines = $path->child('mercury')->lines;

# ['mercury']
lines example 2
# given: synopsis;

my $lines = $path->child('planet9')->lines($^O =~ /win32/i ? "\n" : "\r\n");

# ['planet', 'nine']

mkcall

mkcall(Any @data) (Any)

The mkcall method returns the result of executing the path as an executable. In list context returns the call output and exit code.

Since 0.01

mkcall example 1
package main;

use Venus::Path;

my $path = Venus::Path->new($^X);

my $output = $path->mkcall('--help');

# Usage: perl ...
mkcall example 2
package main;

use Venus::Path;

my $path = Venus::Path->new($^X);

my ($call_output, $exit_code) = $path->mkcall('t/data/sun --heat-death');

# ("", 256)
mkcall example 3
package main;

use Venus::Path;

my $path = Venus::Path->new('.help');

my $output = $path->mkcall;

# Exception! Venus::Path::Error (isa Venus::Error)

mkdir

mkdir(Maybe[Str] $mode) (Path)

The mkdir method makes the path as a directory.

Since 0.01

mkdir example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/systems');

$path = $path->mkdir;

# bless({ value => "t/data/systems" }, "Venus::Path")
mkdir example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/xyz');

$path = $path->mkdir;

# Exception! Venus::Path::Error (isa Venus::Error)

mkdirs

mkdirs(Maybe[Str] $mode) (ArrayRef[Path])

The mkdirs method creates parent directories and returns the list of created directories. This method can return a list of values in list-context.

Since 0.01

mkdirs example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/systems');

my $mkdirs = $path->mkdirs;

# [
#   bless({ value => "t/data/systems" }, "Venus::Path")
# ]
mkdirs example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/systems/solar');

my $mkdirs = $path->mkdirs;

# [
#   bless({ value => "t/data/systems" }, "Venus::Path"),
#   bless({ value => "t/data/systems/solar" }, "Venus::Path"),
# ]

mkfile

mkfile() (Path)

The mkfile method makes the path as an empty file.

Since 0.01

mkfile example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/moon');

$path = $path->mkfile;

# bless({ value => "t/data/moon" }, "Venus::Path")
mkfile example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/xyz');

$path = $path->mkfile;

# Exception! Venus::Path::Error (isa Venus::Error)

name

name() (Str)

The name method returns the path as an absolute path.

Since 0.01

name example 1
# given: synopsis;

my $name = $path->name;

# /path/to/t/data/planets

open

open(Any @data) (FileHandle)

The open method creates and returns an open filehandle.

Since 0.01

open example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/planets/earth');

my $fh = $path->open;

# bless(..., "IO::File");
open example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/planets/earth');

my $fh = $path->open('<');

# bless(..., "IO::File");
open example 3
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/planets/earth');

my $fh = $path->open('>');

# bless(..., "IO::File");
open example 4
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/xyz');

my $fh = $path->open('>');

# Exception! Venus::Path::Error (isa Venus::Error)

parent

parent() (Path)

The parent method returns a path object representing the parent directory.

Since 0.01

parent example 1
# given: synopsis;

my $parent = $path->parent;

# bless({ value => "t/data" }, "Venus::Path")

parents

parents() (ArrayRef[Path])

The parents method returns is a list of parent directories. This method can return a list of values in list-context.

Since 0.01

parents example 1
# given: synopsis;

my $parents = $path->parents;

# [
#   bless({ value => "t/data" }, "Venus::Path"),
#   bless({ value => "t" }, "Venus::Path"),
# ]

parts

parts() (ArrayRef[Str])

The parts method returns an arrayref of path parts.

Since 0.01

parts example 1
# given: synopsis;

my $parts = $path->parts;

# ["t", "data", "planets"]

read

read(Str $binmode) (Str)

The read method reads the file and returns its contents.

Since 0.01

read example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/planets/mars');

my $content = $path->read;
read example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/xyz');

my $content = $path->read;

# Exception! Venus::Path::Error (isa Venus::Error)

relative

relative(Str $root) (Path)

The relative method returns a path object representing a relative path (relative to the path provided).

Since 0.01

relative example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/t/data/planets/mars');

my $relative = $path->relative('/path');

# bless({ value => "to/t/data/planets/mars" }, "Venus::Path")
relative example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/t/data/planets/mars');

my $relative = $path->relative('/path/to/t');

# bless({ value => "data/planets/mars" }, "Venus::Path")

rmdir

rmdir() (Path)

The rmdir method removes the directory and returns a path object representing the deleted directory.

Since 0.01

rmdir example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/stars');

my $rmdir = $path->mkdir->rmdir;

# bless({ value => "t/data/stars" }, "Venus::Path")
rmdir example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/xyz');

my $rmdir = $path->mkdir->rmdir;

# Exception! Venus::Path::Error (isa Venus::Error)

rmdirs

rmdirs() (ArrayRef[Path])

The rmdirs method removes that path and its child files and directories and returns all paths removed. This method can return a list of values in list-context.

Since 0.01

rmdirs example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/stars');

$path->child('dwarfs')->mkdirs;

my $rmdirs = $path->rmdirs;

# [
#   bless({ value => "t/data/stars/dwarfs" }, "Venus::Path"),
#   bless({ value => "t/data/stars" }, "Venus::Path"),
# ]

rmfiles

rmfiles() (ArrayRef[Path])

The rmfiles method recursively removes files under the path and returns the paths removed. This method does not remove the directories found. This method can return a list of values in list-context.

Since 0.01

rmfiles example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/stars')->mkdir;

$path->child('sirius')->mkfile;
$path->child('canopus')->mkfile;
$path->child('arcturus')->mkfile;
$path->child('vega')->mkfile;
$path->child('capella')->mkfile;

my $rmfiles = $path->rmfiles;

# [
#   bless({ value => "t/data/stars/arcturus" }, "Venus::Path"),
#   bless({ value => "t/data/stars/canopus" }, "Venus::Path"),
#   bless({ value => "t/data/stars/capella" }, "Venus::Path"),
#   bless({ value => "t/data/stars/sirius" }, "Venus::Path"),
#   bless({ value => "t/data/stars/vega" }, "Venus::Path"),
# ]

root

root(Str $spec, Str $base) (Maybe[Path])

The root method performs a search up the file system heirarchy returns the first path (i.e. absolute path) matching the file test specification and base path expression provided. The file test specification is the same passed to "test". If no path matches are found this method returns underfined.

Since 2.32

root example 1
# given: synopsis;

my $root = $path->root('d', 't');

# bless({ value => "/path/to/t/../" }, "Venus::Path")
root example 2
# given: synopsis;

my $root = $path->root('f', 't');

# undef

seek

seek(Str $spec, Str $base) (Maybe[Path])

The seek method performs a search down the file system heirarchy returns the first path (i.e. absolute path) matching the file test specification and base path expression provided. The file test specification is the same passed to "test". If no path matches are found this method returns underfined.

Since 2.32

seek example 1
# given: synopsis;

my $path = Venus::Path->new('t');

my $seek = $path->seek('f', 'earth');

# bless({ value => "/path/to/t/data/planets/earth" }, "Venus::Path")
seek example 2
# given: synopsis;

my $path = Venus::Path->new('t');

my $seek = $path->seek('f', 'europa');

# undef

sibling

sibling(Str $path) (Path)

The sibling method returns a path object representing the sibling path provided.

Since 0.01

sibling example 1
# given: synopsis;

my $sibling = $path->sibling('galaxies');

# bless({ value => "t/data/galaxies" }, "Venus::Path")

siblings

siblings() (ArrayRef[Path])

The siblings method returns all sibling files and directories for the current path. This method can return a list of values in list-context.

Since 0.01

siblings example 1
# given: synopsis;

my $siblings = $path->siblings;

# [
#   bless({ value => "t/data/moon" }, "Venus::Path"),
#   bless({ value => "t/data/sun" }, "Venus::Path"),
# ]

test

test(Str $expr) (Bool)

The test method evaluates the current path against the stackable file test operators provided.

Since 0.01

test example 1
# given: synopsis;

my $test = $path->test;

# -e $path

# 1
test example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/sun');

my $test = $path->test('efs');

# -e -f -s $path

# 1
unlink() (Path)

The unlink method removes the file and returns a path object representing the removed file.

Since 0.01

package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/asteroid')->mkfile;

my $unlink = $path->unlink;

# bless({ value => "t/data/asteroid" }, "Venus::Path")
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/xyz');

my $unlink = $path->unlink;

# Exception! Venus::Path::Error (isa Venus::Error)

write

write(Str $data, Str $binmode) (Path)

The write method write the data provided to the file.

Since 0.01

write example 1
package main;

use Venus::Path;

my $path = Venus::Path->new('t/data/asteroid');

my $write = $path->write('asteroid');
write example 2
package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/xyz');

my $write = $path->write('nothing');

# Exception! Venus::Path::Error (isa Venus::Error)

OPERATORS

This package overloads the following operators:

operation: (.)

This package overloads the . operator.

example 1

# given: synopsis;

my $result = $path . '/earth';

# "t/data/planets/earth"
operation: (eq)

This package overloads the eq operator.

example 1

# given: synopsis;

my $result = $path eq 't/data/planets';

# 1
operation: (ne)

This package overloads the ne operator.

example 1

# given: synopsis;

my $result = $path ne 't/data/planets/';

# 1
operation: (qr)

This package overloads the qr operator.

example 1

# given: synopsis;

my $result = 't/data/planets' =~ $path;

# 1
operation: ("")

This package overloads the "" operator.

example 1

# given: synopsis;

my $result = "$path";

# "t/data/planets"

example 2

# given: synopsis;

my $mercury = $path->child('mercury');

my $result = "$path, $path";

# "t/data/planets, t/data/planets"
operation: (~~)

This package overloads the ~~ operator.

example 1

# given: synopsis;

my $result = $path ~~ 't/data/planets';

# 1

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2000, Al Newkirk.

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.