The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Venus-2.50
River stage two • 3 direct dependents • 56 total dependents
6 ++
/ 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"),
  # ]

root

  root(Str $spec, Str $base) (Maybe[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(Str $spec, Str $base) (Maybe[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(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.