Dancer2::FileUtils(3)

💖 Dancer2::FileUtils(3) — the perl manual, but make it cute ✨

okay bestie, welcome to Dancer2::FileUtils(3), aka the User Contributed Perl Documentation entry for the little toolbox of file helpers that Dancer2 keeps in its backpack 🎀. she's not flashy, she's not loud, she's just here to do your file stuff so you don't have to write your own subroutines, periodt.

---

✨ NAME ✨

Dancer2::FileUtils — file utility helpers 💅

🌸 VERSION 🌸

version 2.2.1 — yeah she's got a version number, she's official 🫶

🦋 SYNOPSIS 🦋

here's the vibe check — literally just copy-paste energy:

use Dancer2::FileUtils qw/dirname path path_or_empty/;

# for 'path/to/file'
my $dir  = dirname($path); # returns 'path/to'
my $path = path($path);    # returns '/abs/path/to/file'
my $path = path_or_empty($path);    # returns '' if file doesn't exist

use Dancer2::FileUtils qw/path read_file_content/;

my $content = read_file_content( path( 'folder', 'folder', 'file' ) );
my @content = read_file_content( path( 'folder', 'folder', 'file' ) );

use Dancer2::FileUtils qw/read_glob_content set_file_mode/;

open my $fh, '<', $file or die "$!\n";
set_file_mode($fh);
my @content = read_glob_content($fh);
my $content = read_glob_content($fh);

use Dancer2::FileUtils qw/open_file/;

my $fh = open_file('<', $file) or die $message;

use Dancer2::FileUtils 'set_file_mode';

set_file_mode($fh);

look at that. immaculate. no notes 💖

---

🌈 DESCRIPTION 🌈

so Dancer2::FileUtils is a lil grab-bag of file-related utilities that Dancer2 uses internally. but here's the tea — developers can totally use it themselves instead of hand-rolling their own file-reading subroutines or dragging in a whole extra module. it's giving "why re-invent the wheel when the wheel is right here and it's cute" 💅✨

---

👑 FUNCTIONS 👑

🍓 my $path = path( 'folder', 'folder', 'filename');

this one calls Path::Tiny's path(...)->stringify on the path parts you hand it. but lowkey, the docs are like: honestly bestie, just use Path::Tiny::path(@parts) directly instead 🙈

and if you wanna normalize the path (for a path that already exists), do this:

Path::Tiny::path(@parts)->realpath->stringify;

🧚 my $path = path_or_empty('folder, 'folder','filename');

same energy as path, but she returns '' if the path doesn't exist. no drama, just an empty string 💀

🎀 dirname

use Dancer2::FileUtils 'dirname';
my $dir = dirname($path);

# Same thing:
use Path::Tiny qw< path >;
my $dir       = path($path)->parent;
my $as_string = $dir->stringify;

fetches the directory name of a path. on most OSes it returns everything but the last level of the file path. see Path::Tiny for the deets, iykyk ✨

💜 set_file_mode($fh, $charset);

use Dancer2::FileUtils 'set_file_mode';

set_file_mode($fh);

applies the charset you specified. defaults to utf-8 if you don't pass one. and heads up — an empty charset disables encoding layers, so don't be surprised when that happens, bestie 🫶

🌸 my $fh = open_file('<', $file, $charset) or die $message;

use Dancer2::FileUtils 'open_file';
my $fh = open_file('<', $file) or die $message;

calls open and hands you back a filehandle. if you pass a charset, it opens the file in that encoding; otherwise it defaults to utf-8. and again — an empty charset disables encoding layers. same rule, no cap 💅

⭐ my $content = read_file_content($file, $charset);

use Dancer2::FileUtils 'read_file_content';

my @content = read_file_content($file);
my $content = read_file_content($file);

returns either the content of a file (filename goes in, content comes out) or undef if the file could not be opened. 😭

in array context it returns each line (as defined by $/) as a separate element; in scalar context it returns the entire contents of the file. choose your fighter, both are valid 🎀

🦋 my $content = read_glob_content($fh);

use Dancer2::FileUtils 'read_glob_content';

open my $fh, '<', $file or die "$!\n";
binmode $fh, ':encoding(utf-8)';
my @content = read_glob_content($fh);
my $content = read_glob_content($fh);

similar to read_file_content, only this one takes a file handle instead of a filename. it's assumed that the appropriate PerlIO layers are already applied to the file handle. returns the content and closes the file handle. so like, she's done with it, she's closing the door behind her 🚪✨

💖 my $escaped_filename = escape_filename( $filename );

escapes characters in a filename that could alter a path when concatenated. safety first, bestie 🛡️

use Dancer2::FileUtils 'escape_filename';

my $safe = escape_filename( "a/../b.txt" ); # a+2f+2e+2e+2fb+2etxt

look at that transformation. she ate 💅

---

🫶 EXPORT 🫶

nothing by default. you can provide a list of subroutines to import, and that's it, that's the whole rule 🌸

---

💜 AUTHOR 💜

Dancer Core Developers — kings and queens, honestly 👑

🎀 COPYRIGHT AND LICENSE 🎀

this software is copyright (c) 2026 by Alexis Sukrieh.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, legally speaking 💅

---

and that's the whole page, bestie! generated by perl v5.42.3 on 2026-09-20 — thanks for reading the Dancer2::FileUtils(3) manual with me, you're literally the main character 🌟💖 bye mwah! 🫶✨