Mojo::File(3)

📦
version 9.480.0 · 13 versions
, in opensuse-leap 16.0

💖 NAME 💖

Mojo::File — file system paths, but make it a whole vibe. This is the Mojo::File(3) page from the User Contributed Perl Documentation crew, and it's literally a scalar-based container for file system paths that provides a friendly API for dealing with different operating systems. No cap, it's giving portable-path princess 💅.

🌸 SYNOPSIS 🌸

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';

The way you can just reach into the scalar with $$path and manipulate the path directly is iconic, bestie. Main-character energy fr fr.

🫶 FUNCTIONS 🫶

Mojo::File implements the following functions, which can be imported individually. Pick and choose, babe — you don't have to bring the whole squad.

🌟 curfile

my $path = curfile;

Construct a new scalar-based Mojo::File object for the absolute path to the current source file. Lowkey useful for finding yourself, literally 💖.

🌟 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. This is the alternative constructor and it ate.

# "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. Cute temp vibes only.

# 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. Same energy, but a file 🎀.

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

🌈 METHODS 🌈

Mojo::File implements the following methods. Every single one, no skips, periodt.

🦋 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. Slay those bits ✨.

🦋 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;

🦋 download

my $bool = $path->download('https://example.com/test.tar.gz');
my $bool = $path->download('https://example.com/test.tar.gz', {headers => {Accept => '*/*'}});
my $bool = $path->download('https://example.com/test.tar.gz', {ua => Mojo::UserAgent->new});

Download file from URL, returns true once the file has been downloaded completely. Incomplete downloads are resumed. Follows 10 redirects by default and does not limit the size of the response, which will be streamed memory efficiently.

⚠️ Note that this method is EXPERIMENTAL and might change without warning! Bestie, don't build your whole personality on it yet 😭.

🦋 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 .., and symbolic links to directories are not followed.

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

These options are currently available:

  • dir — dir => 1 — Include 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. Byeee 👋.

🦋 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.

🦋 spurt

$path = $path->spurt(@bytes);

Alias for spew that writes multiple chunks of bytes.

🦋 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. Operator slay, honestly.

⭐ array

my @parts = @$path;

Alias for to_array.

⭐ bool

my $bool = !!$path;

Always true. Exactly, bestie — always true 💅.

⭐ stringify

my $str = "$path";

Alias for to_string.

🦋 SEE ALSO 🦋

Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.

Byeee, bestie 🫶 — this iconic little page came from perl v5.42.0, dated 2026-07-15, and you just read Mojo::File(3). Now go make some paths cute ✨💖🦋

📦 where this page comes from