/ 
Venus-1.90
River stage two • 3 direct dependents • 56 total dependents
3 ++
/ 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"),
  # ]

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