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() (Venus::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() (string)

The basename method returns the path base name.

Since 0.01

basename example 1

  # given: synopsis;
  my $basename = $path->basename;
  # planets

child

  child(string $path) (Venus::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() (within[arrayref, Venus::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(string $mode) (Venus::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(string @args) (Venus::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")

copy

  copy(string | Venus::Path $path) (Venus::Path)

The copy method uses "copy" in File::Copy to copy the file represented by the invocant to the path provided and returns the invocant.

Since 2.80

copy example 1

  # given: synopsis
  package main;
  my $copy = $path->child('mercury')->copy($path->child('yrucrem'));
  # bless({...}, 'Venus::Path')

default

  default() (string)

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() (within[arrayref, Venus::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() (boolean)

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() (string)

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

extension

  extension(string $name) (string | Venus::Path)

The extension method returns a new path object using the extension name provided. If no argument is provided this method returns the extension for the path represented by the invocant, otherwise returns undefined.

Since 2.55

extension example 1

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('t/Venus_Path.t');
  my $extension = $path->extension;
  # "t"

extension example 2

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('t/data/mercury');
  my $extension = $path->extension('txt');
  # bless({ value => "t/data/mercury.txt"}, "Venus::Path")

extension example 3

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('t/data');
  my $extension = $path->extension;
  # undef

extension example 4

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('t/data');
  my $extension = $path->extension('txt');
  # bless({ value => "t/data.txt"}, "Venus::Path")

files

  files() (within[arrayref, Venus::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(string | regexp $expr) (within[arrayref, Venus::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(string | regexp $expr) (within[arrayref, Venus::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() (boolean)

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() (boolean)

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() (boolean)

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() (boolean)

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() (within[arrayref, Venus::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(string | regexp $separator, string $binmode) (within[arrayref, string])

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');
  # ("", 1)

mkcall example 3

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('.help');
  my $output = $path->mkcall;
  # Exception! (isa Venus::Path::Error) (see error_on_mkcall)

mkdir

  mkdir(maybe[string] $mode) (Venus::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! (isa Venus::Path::Error) (see error_on_mkdir)

mkdirs

  mkdirs(maybe[string] $mode) (within[arrayref, Venus::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() (Venus::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! (isa Venus::Path::Error) (see error_on_mkfile)

mktemp_dir

  mktemp_dir() (Venus::Path)

The mktemp_dir method uses "tempdir" in File::Temp to create a temporary directory which isn't automatically removed and returns a new path object.

Since 2.80

mktemp_dir example 1

  # given: synopsis
  package main;
  my $mktemp_dir = $path->mktemp_dir;
  # bless({value => "/tmp/ZnKTxBpuBE"}, "Venus::Path")

mktemp_file

  mktemp_file() (Venus::Path)

The mktemp_file method uses "tempfile" in File::Temp to create a temporary file which isn't automatically removed and returns a new path object.

Since 2.80

mktemp_file example 1

  # given: synopsis
  package main;
  my $mktemp_file = $path->mktemp_file;
  # bless({value => "/tmp/y5MvliBQ2F"}, "Venus::Path")

move

  move(string | Venus::Path $path) (Venus::Path)

The move method uses "move" in File::Copy to move the file represented by the invocant to the path provided and returns the invocant.

Since 2.80

move example 1

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('t/data');
  my $unknown = $path->child('unknown')->mkfile->move($path->child('titan'));
  # bless({value => 't/data/titan'}, 'Venus::Path')

name

  name() (string)

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! (isa Venus::Path::Error) (see error_on_open)

parent

  parent() (Venus::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() (within[arrayref, Venus::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() (within[arrayref, string])

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(string $binmode) (string)

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! (isa Venus::Path::Error) (see error_on_read_open)

relative

  relative(string $root) (Venus::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")

rename

  rename(string | Venus::Path $path) (Venus::Path)

The rename method performs a "move" unless the path provided is only a file name, in which case it attempts a rename under the directory of the invocant.

Since 2.91

rename example 1

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('t/path/001');
  my $rename = $path->rename('002');
  # bless({value => 't/path/002'}, 'Venus::Path')

rmdir

  rmdir() (Venus::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! (isa Venus::Path::Error) (see error_on_rmdir)

rmdirs

  rmdirs() (within[arrayref, Venus::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() (within[arrayref, Venus::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(string $spec, string $base) (maybe[Venus::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(string $spec, string $base) (maybe[Venus::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;
  $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;
  $path = Venus::Path->new('t');
  my $seek = $path->seek('f', 'europa');
  # undef

sibling

  sibling(string $path) (Venus::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() (within[arrayref, Venus::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(string $expr) (boolean)

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

  unlink() (Venus::Path)

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

Since 0.01

unlink example 1

  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")

unlink example 2

  package main;
  use Venus::Path;
  my $path = Venus::Path->new('/path/to/xyz');
  my $unlink = $path->unlink;
  # Exception! (isa Venus::Path::Error) (see error_on_unlink)

write

  write(string $data, string $binmode) (Venus::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! (isa Venus::Path::Error) (see error_on_write_open)

ERRORS

This package may raise the following errors:

error: "error_on_copy"

This package may raise an error_on_copy exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_copy',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_copy"
  # my $message = $error->render;
  # "Can't copy \"t\/data\/planets\" to \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"
  # my $self = $error->stash('self');
  # bless({...}, 'Venus::Path')

error: "error_on_mkcall"

This package may raise an error_on_mkcall exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_mkcall',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_mkcall"
  # my $message = $error->render;
  # "Can't make system call to \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_mkdir"

This package may raise an error_on_mkdir exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_mkdir',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_mkdir"
  # my $message = $error->render;
  # "Can't make directory \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_mkfile"

This package may raise an error_on_mkfile exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_mkfile',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_mkfile"
  # my $message = $error->render;
  # "Can't make file \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_move"

This package may raise an error_on_move exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_move',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_move"
  # my $message = $error->render;
  # "Can't copy \"t\/data\/planets\" to \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"
  # my $self = $error->stash('self');
  # bless({...}, 'Venus::Path')

error: "error_on_open"

This package may raise an error_on_open exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_open',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_open"
  # my $message = $error->render;
  # "Can't open \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_read_binmode"

This package may raise an error_on_read_binmode exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_read_binmode',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_read_binmode"
  # my $message = $error->render;
  # "Can't binmode \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_read_error"

This package may raise an error_on_read_error exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_read_error',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_read_error"
  # my $message = $error->render;
  # "Can't read from file \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_read_open"

This package may raise an error_on_read_open exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_read_open',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_read_open"
  # my $message = $error->render;
  # "Can't read \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_rmdir"

This package may raise an error_on_rmdir exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_rmdir',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_rmdir"
  # my $message = $error->render;
  # "Can't rmdir \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_unlink"

This package may raise an error_on_unlink exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_unlink',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_unlink"
  # my $message = $error->render;
  # "Can't unlink \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_write_binmode"

This package may raise an error_on_write_binmode exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_write_binmode',
    error => $!,
    path => '/nowhere',
    binmode => ':utf8',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_write_binmode"
  # my $message = $error->render;
  # "Can't binmode \"/nowhere\": $!"
  # my $binmode = $error->stash('binmode');
  # ":utf8"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_write_error"

This package may raise an error_on_write_error exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_write_error',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_write_error"
  # my $message = $error->render;
  # "Can't write to file \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

error: "error_on_write_open"

This package may raise an error_on_write_open exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_write_open',
    error => $!,
    path => '/nowhere',
  };
  my $error = $path->catch('error', $input);
  # my $name = $error->name;
  # "on_write_open"
  # my $message = $error->render;
  # "Can't write \"/nowhere\": $!"
  # my $path = $error->stash('path');
  # "/nowhere"

OPERATORS

This package overloads the following operators:

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 . '/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';
  # 1

AUTHORS

Awncorp, "awncorp@cpan.org"

LICENSE

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