/ 
Venus-2.01
River stage two • 3 direct dependents • 56 total dependents
/ 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

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2000, Al Newkirk.

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