Venus::Path

Path Class

Path Class for Perl 5

method: absolute method: basename method: child method: chmod method: chown method: children method: default method: directories method: exists method: explain method: find method: files method: glob method: is_absolute method: is_directory method: is_file method: is_relative method: lines method: lineage method: open method: mkcall method: mkdir method: mkdirs method: mkfile method: name method: parent method: parents method: parts method: read method: relative method: rmdir method: rmdirs method: rmfiles method: sibling method: siblings method: test method: unlink method: write

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;

This package provides methods for working with file system paths.

Venus::Kind::Utility

Venus::Role::Accessible Venus::Role::Buildable Venus::Role::Explainable Venus::Role::Valuable

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

absolute() (Path)

{ since => '0.01', }

=example-1 absolute

# given: synopsis;

$path = $path->absolute;

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

The basename method returns the path base name.

basename() (Str)

{ since => '0.01', }

=example-1 basename

# given: synopsis;

my $basename = $path->basename;

# planets

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

child(Str $path) (Path)

{ since => '0.01', }

=example-1 child

# given: synopsis;

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

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

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

chmod(Str $mode) (Path)

{ since => '0.01', }

=example-1 chmod

# given: synopsis;

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

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

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

chown(Str @args) (Path)

{ since => '0.01', }

=example-1 chown

# given: synopsis;

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

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

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

children() (ArrayRef[Path])

{ since => '0.01', }

=example-1 children

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

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

default() (Str)

{ since => '0.01', }

=example-1 default

# given: synopsis;

my $default = $path->default;

# $ENV{PWD}

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.

directories() (ArrayRef[Path])

{ since => '0.01', }

=example-1 directories

# given: synopsis;

my $directories = $path->directories;

# []

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

exists() (Bool)

{ since => '0.01', }

=example-1 exists

# given: synopsis;

my $exists = $path->exists;

# 1

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

explain() (Str)

{ since => '0.01', }

=example-1 explain

# given: synopsis;

my $explain = $path->explain;

# t/data/planets

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.

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

{ since => '0.01', }

=example-1 find

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

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.

files() (ArrayRef[Path])

{ since => '0.01', }

=example-1 files

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

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.

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

{ since => '0.01', }

=example-1 glob

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

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

is_absolute() (Bool)

{ since => '0.01', }

=example-1 is_absolute

# given: synopsis;

my $is_absolute = $path->is_absolute;

# 0

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

is_directory() (Bool)

{ since => '0.01', }

=example-1 is_directory

# given: synopsis;

my $is_directory = $path->is_directory;

# 1

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

is_file() (Bool)

{ since => '0.01', }

=example-1 is_file

# given: synopsis;

my $is_file = $path->is_file;

# 0

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

is_relative() (Bool)

{ since => '0.01', }

=example-1 is_relative

# given: synopsis;

my $is_relative = $path->is_relative;

# 1

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

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

{ since => '1.23', }

=example-1 lines

# given: synopsis;

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

# ['mercury']

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.

lineage() (ArrayRef[Path])

{ since => '0.01', }

=example-1 lineage

# given: synopsis;

my $lineage = $path->lineage;

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

The open method creates and returns an open filehandle.

open(Any @data) (FileHandle)

{ since => '0.01', }

=example-1 open

package main;

use Venus::Path;

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

my $fh = $path->open;

# bless(..., "IO::File");

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

mkcall(Any @data) (Any)

{ since => '0.01', }

=example-1 mkcall

package main;

use Venus::Path;

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

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

# Usage: perl ...

The mkdir method makes the path as a directory.

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

{ since => '0.01', }

=example-1 mkdir

package main;

use Venus::Path;

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

$path = $path->mkdir;

# bless({ value => "t/data/systems" }, "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.

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

{ since => '0.01', }

=example-1 mkdirs

package main;

use Venus::Path;

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

my $mkdirs = $path->mkdirs;

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

The mkfile method makes the path as an empty file.

mkfile() (Path)

{ since => '0.01', }

=example-1 mkfile

package main;

use Venus::Path;

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

$path = $path->mkfile;

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

The name method returns the path as an absolute path.

name() (Str)

{ since => '0.01', }

=example-1 name

# given: synopsis;

my $name = $path->name;

# /path/to/t/data/planets

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

parent() (Path)

{ since => '0.01', }

=example-1 parent

# given: synopsis;

my $parent = $path->parent;

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

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

parents() (ArrayRef[Path])

{ since => '0.01', }

=example-1 parents

# given: synopsis;

my $parents = $path->parents;

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

The parts method returns an arrayref of path parts.

parts() (ArrayRef[Str])

{ since => '0.01', }

=example-1 parts

# given: synopsis;

my $parts = $path->parts;

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

The read method reads the file and returns its contents.

read(Str $binmode) (Str)

{ since => '0.01', }

=example-1 read

package main;

use Venus::Path;

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

my $content = $path->read;

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

relative(Str $root) (Path)

{ since => '0.01', }

=example-1 relative

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

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

rmdir() (Path)

{ since => '0.01', }

=example-1 rmdir

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

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.

rmdirs() (ArrayRef[Path])

{ since => '0.01', }

=example-1 rmdirs

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

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.

rmfiles() (ArrayRef[Path])

{ since => '0.01', }

=example-1 rmfiles

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

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

sibling(Str $path) (Path)

{ since => '0.01', }

=example-1 sibling

# given: synopsis;

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

# bless({ value => "t/data/galaxies" }, "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.

siblings() (ArrayRef[Path])

{ since => '0.01', }

=example-1 siblings

# given: synopsis;

my $siblings = $path->siblings;

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

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

test(Str $expr) (Bool)

{ since => '0.01', }

=example-1 test

# given: synopsis;

my $test = $path->test;

# -e $path

# 1

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

unlink() (Path)

{ since => '0.01', }

=example-1 unlink

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

The write method write the data provided to the file.

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

{ since => '0.01', }

=example-1 write

package main;

use Venus::Path;

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

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

This package overloads the . operator.

This package overloads the eq operator.

This package overloads the ne operator.

This package overloads the qr operator.

This package overloads the "" operator.

This package overloads the ~~ operator.

t/Venus.t: pdml: authors t/Venus.t: pdml: license

cpanm Venus

perl -MCPAN -e shell
install Venus