Venus::Path

Path Class

Path Class for Perl 5

method: absolute method: basename method: child method: chmod method: chown method: children method: copy method: default method: directories method: exists method: explain method: extension 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: mktemp_dir method: mktemp_file method: move method: name method: new method: parent method: parents method: parts method: read method: relative method: rename method: rmdir method: rmdirs method: rmfiles method: root method: seek 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() (Venus::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() (string)

{ 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(string $path) (Venus::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(string $mode) (Venus::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(string @args) (Venus::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() (within[arrayref, Venus::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 copy method uses "copy" in File::Copy to copy the file represented by the invocant to the path provided and returns the invocant.

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

{ since => '2.80', }

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

default() (string)

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

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

{ since => '0.01', }

=example-1 explain

# given: synopsis;

my $explain = $path->explain;

# t/data/planets

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.

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

{ since => '2.55', }

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

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

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

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

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

{ 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() (within[arrayref, Venus::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[string] $mode) (Venus::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[string] $mode) (within[arrayref, Venus::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() (Venus::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 mktemp_dir method uses "tempdir" in File::Temp to create a temporary directory which isn't automatically removed and returns a new path object.

mktemp_dir() (Venus::Path)

{ since => '2.80', }

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.

mktemp_file() (Venus::Path)

{ since => '2.80', }

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

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

{ since => '2.80', }

The name method returns the path as an absolute path.

name() (string)

{ since => '0.01', }

=example-1 name

# given: synopsis;

my $name = $path->name;

# /path/to/t/data/planets

The new method constructs an instance of the package.

new(any @args) (Venus::Path)

{ since => '4.15', }

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

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

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

{ 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(string $root) (Venus::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 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.

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

{ since => '2.91', }

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

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

root(string $spec, string $base) (maybe[Venus::Path])

{ since => '2.32', }

=example-1 root

# given: synopsis;

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

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

seek(string $spec, string $base) (maybe[Venus::Path])

{ since => '2.32', }

=example-1 seek

# given: synopsis;

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

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

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

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

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

{ since => '0.01', }

=example-1 siblings

# given: synopsis;

my $siblings = $path->siblings;

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

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

test(string $expr) (boolean)

{ 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() (Venus::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(string $data, string $encoding) (Venus::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');

package main;

use Venus::Path;

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

$path->copy('/path/to/nowhere');

# Error! (on.copy)

package main;

use Venus::Path;

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

$path->mkdir;

# Error! (on.mkdir)

package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/nowhere/file.txt');

$path->mkfile;

# Error! (on.mkfile)

package main;

use Venus::Path;

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

$path->move('/path/to/nowhere');

# Error! (on.move)

package main;

use Venus::Path;

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

$path->open;

# Error! (on.open)

package main;

use Venus::Path;

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

$path->read;

# Error! (on.read)

package main;

use Venus::Path;

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

$path->rmdir;

# Error! (on.rmdir)

package main;

use Venus::Path;

my $path = Venus::Path->new('/path/to/nowhere/file.txt');

$path->write('content');

# Error! (on.write)

package main;

use Venus::Path;

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

$path->unlink;

# Error! (on.unlink)

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: present: authors t/Venus.t: present: license

cpanm Venus

perl -MCPAN -e shell
install Venus