Mojo::File - File system paths

NAME SYNOPSIS DESCRIPTION FUNCTIONS curfile path tempdir tempfile METHODS basename child chmod copy_to dirname extname is_abs list list_tree lstat make_path move_to new open realpath remove remove_tree sibling slurp spew stat tap to_abs to_array to_rel to_string touch with_roles OPERATORS array bool stringify SEE ALSO

use Mojo::File;
# Portably deal with file system paths
my $path = Mojo::File−>new('/home/sri/.vimrc');
say $path−>slurp;
say $path−>dirname;
say $path−>basename;
say $path−>extname;
say $path−>sibling('.bashrc');
# Use the alternative constructor
use Mojo::File qw(path);
my $path = path('/tmp/foo/bar')−>make_path;
$path−>child('test.txt')−>spew('Hello Mojo!');

DESCRIPTION

Mojo::File is a scalar-based container for file system paths that provides a friendly API for dealing with different operating systems.

# Access scalar directly to manipulate path
my $path = Mojo::File−>new('/home/sri/test');
$$path .= '.txt';

FUNCTIONS

Mojo::File implements the following functions, which can be imported individually.

curfile

my $path = curfile;

Construct a new scalar-based Mojo::File object for the absolute path to the current source file.

path

my $path = path;
my $path = path('/home/sri/.vimrc');
my $path = path('/home', 'sri', '.vimrc');
my $path = path(File::Temp−>newdir);

Construct a new scalar-based Mojo::File object, defaults to using the current working directory.

# "foo/bar/baz.txt" (on UNIX)
path('foo', 'bar', 'baz.txt');

tempdir

my $path = tempdir;
my $path = tempdir('tempXXXXX');

Construct a new scalar-based Mojo::File object for a temporary directory with File::Temp.

# Longer version
my $path = path(File::Temp−>newdir('tempXXXXX'));

tempfile

my $path = tempfile;
my $path = tempfile(DIR => '/tmp');

Construct a new scalar-based Mojo::File object for a temporary file with File::Temp.

# Longer version
my $path = path(File::Temp−>new(DIR => '/tmp'));

METHODS

Mojo::File implements the following methods.

basename

my $name = $path−>basename;
my $name = $path−>basename('.txt');

Return the last level of the path with File::Basename.

# ".vimrc" (on UNIX)
path('/home/sri/.vimrc')−>basename;
# "test" (on UNIX)
path('/home/sri/test.txt')−>basename('.txt');

child

my $child = $path−>child('.vimrc');

Return a new Mojo::File object relative to the path.

# "/home/sri/.vimrc" (on UNIX)
path('/home')−>child('sri', '.vimrc');

chmod

$path = $path−>chmod(0644);

Change file permissions.

copy_to

my $destination = $path−>copy_to('/home/sri');
my $destination = $path−>copy_to('/home/sri/.vimrc.backup');

Copy file with File::Copy and return the destination as a Mojo::File object.

dirname

my $name = $path−>dirname;

Return all but the last level of the path with File::Basename as a Mojo::File object.

# "/home/sri" (on UNIX)
path('/home/sri/.vimrc')−>dirname;

extname

my $ext = $path−>extname;

Return file extension of the path.

# "js"
path('/home/sri/test.js')−>extname;

is_abs

my $bool = $path−>is_abs;

Check if the path is absolute.

# True (on UNIX)
path('/home/sri/.vimrc')−>is_abs;
# False (on UNIX)
path('.vimrc')−>is_abs;

list

my $collection = $path−>list;
my $collection = $path−>list({hidden => 1});

List all files in the directory and return a Mojo::Collection object containing the results as Mojo::File objects. The list does not include "." and "..".

# List files
say for path('/home/sri/myapp')−>list−>each;

These options are currently available:
dir

dir => 1

Include directories.

hidden

hidden => 1

Include hidden files.

list_tree

my $collection = $path−>list_tree;
my $collection = $path−>list_tree({hidden => 1});

List all files recursively in the directory and return a Mojo::Collection object containing the results as Mojo::File objects. The list does not include "." and "..".

# List all templates
say for path('/home/sri/myapp/templates')−>list_tree−>each;

These options are currently available:
dir

dir => 1

Include directories.

dont_use_nlink

dont_use_nlink => 1

Force File::Find to always stat directories.

hidden

hidden => 1

Include hidden files and directories.

max_depth

max_depth => 3

Maximum number of levels to descend when searching for files.

lstat

my $stat = $path−>lstat;

Return a File::stat object for the symlink.

# Get symlink size
say path('/usr/sbin/sendmail')−>lstat−>size;
# Get symlink modification time
say path('/usr/sbin/sendmail')−>lstat−>mtime;

make_path

$path = $path−>make_path;
$path = $path−>make_path({mode => 0711});

Create the directories if they don’t already exist, any additional arguments are passed through to File::Path.

move_to

my $destination = $path−>move_to('/home/sri');
my $destination = $path−>move_to('/home/sri/.vimrc.backup');

Move file with File::Copy and return the destination as a Mojo::File object.

new

my $path = Mojo::File−>new;
my $path = Mojo::File−>new('/home/sri/.vimrc');
my $path = Mojo::File−>new('/home', 'sri', '.vimrc');
my $path = Mojo::File−>new(File::Temp−>new);
my $path = Mojo::File−>new(File::Temp−>newdir);

Construct a new Mojo::File object, defaults to using the current working directory.

# "foo/bar/baz.txt" (on UNIX)
Mojo::File−>new('foo', 'bar', 'baz.txt');

open

my $handle = $path−>open('+<');
my $handle = $path−>open('r+');
my $handle = $path−>open(O_RDWR);
my $handle = $path−>open('<:encoding(UTF−8)');

Open file with IO::File.

# Combine "fcntl.h" constants
use Fcntl qw(O_CREAT O_EXCL O_RDWR);
my $handle = path('/home/sri/test.pl')−>open(O_RDWR | O_CREAT | O_EXCL);

realpath

my $realpath = $path−>realpath;

Resolve the path with Cwd and return the result as a Mojo::File object.

remove

$path = $path−>remove;

Delete file.

remove_tree

$path = $path−>remove_tree;
$path = $path−>remove_tree({keep_root => 1});

Delete this directory and any files and subdirectories it may contain, any additional arguments are passed through to File::Path.

sibling

my $sibling = $path−>sibling('.vimrc');

Return a new Mojo::File object relative to the directory part of the path.

# "/home/sri/.vimrc" (on UNIX)
path('/home/sri/.bashrc')−>sibling('.vimrc');
# "/home/sri/.ssh/known_hosts" (on UNIX)
path('/home/sri/.bashrc')−>sibling('.ssh', 'known_hosts');

slurp

my $bytes = $path−>slurp;
my $chars = $path−>slurp('UTF−8');

Read all data at once from the file. If an encoding is provided, an attempt will be made to decode the content.

spew

$path = $path−>spew($bytes);
$path = $path−>spew($chars, 'UTF−8');

Write all data at once to the file. If an encoding is provided, an attempt to encode the content will be made prior to writing.

stat

my $stat = $path−>stat;

Return a File::stat object for the path.

# Get file size
say path('/home/sri/.bashrc')−>stat−>size;
# Get file modification time
say path('/home/sri/.bashrc')−>stat−>mtime;

tap

$path = $path−>tap(sub {...});

Alias for "tap" in Mojo::Base.

to_abs

my $absolute = $path−>to_abs;

Return absolute path as a Mojo::File object, the path does not need to exist on the file system.

to_array

my $parts = $path−>to_array;

Split the path on directory separators.

# "home:sri:.vimrc" (on UNIX)
join ':', @{path('/home/sri/.vimrc')−>to_array};

to_rel

my $relative = $path−>to_rel('/some/base/path');

Return a relative path from the original path to the destination path as a Mojo::File object.

# "sri/.vimrc" (on UNIX)
path('/home/sri/.vimrc')−>to_rel('/home');

to_string

my $str = $path−>to_string;

Stringify the path.

touch

$path = $path−>touch;

Create file if it does not exist or change the modification and access time to the current time.

# Safely read file
say path('.bashrc')−>touch−>slurp;

with_roles

my $new_class = Mojo::File−>with_roles('Mojo::File::Role::One');
my $new_class = Mojo::File−>with_roles('+One', '+Two');
$path = $path−>with_roles('+One', '+Two');

Alias for "with_roles" in Mojo::Base.

OPERATORS

Mojo::File overloads the following operators.

array

my @parts = @$path;

Alias for "to_array".

bool

my $bool = !!$path;

Always true.

stringify

my $str = "$path";

Alias for "to_string".