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/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/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/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/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"),
  # ]

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

  unlink() (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! 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"

operation: (~~)

This package overloads the ~~ operator.

example 1

  # given: synopsis;

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

  # 1

To install Venus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Venus

CPAN shell

perl -MCPAN -e shell
install Venus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

ABSTRACT

SYNOPSIS

DESCRIPTION

INHERITS

INTEGRATES

METHODS

absolute

basename

child

children

chmod

chown

default

directories

exists

explain

files

find

glob

is_absolute

is_directory

is_file

is_relative

lineage

mkcall

mkdir

mkdirs

mkfile

name

open

parent

parents

parts

read

relative

rmdir

rmdirs

rmfiles

sibling

siblings

test

unlink

write

OPERATORS

Module Install Instructions