File::Slurper(3)

💖 NAME 💖

File::Slurper — a simple, sane and efficient module to slurp a file. This is the File::Slurper(3) page, and yes bestie, it's User Contributed Perl Documentation. We're gonna read and write files correctly and fast, no cap. 🫶

🌸 VERSION 🌸

version 0.014 — tiny number, big slay. ✨

🦋 SYNOPSIS 🦋

use File::Slurper 'read_text';
my $content = read_text($filename);

✨ DESCRIPTION ✨

okay so File::Slurper provides functions for fast and correct slurping and spewing. All functions are optionally exported — import just the ones you need. All functions throw exceptions on errors. The write functions don't return any meaningful value, so don't go looking for a cute little return, bestie. 💀

💅 FUNCTIONS 💅

Every function here has main character energy, but the signatures are exact. 🎀

read_text($filename, $encoding, $crlf)

Reads file $filename into a scalar and decodes it from $encoding (which defaults to UTF-8). If $crlf is true, crlf translation is performed. The default for this argument is off. The special value 'auto' will set it to a platform specific default value. So yes, you can let it auto-pick the platform vibe. ✨

read_binary($filename)

Reads file $filename into a scalar with zero decoding and zero transformation. Pure bytes, no thoughts, just data. 🫶

read_lines($filename, $encoding, $crlf, $skip_chomp)

Reads file $filename into a list/array line-by-line, after decoding from $encoding, optional crlf translation and chomping. It will always use newline as separator. The signature also has $skip_chomp, and yes it is exactly that name. 🎀

write_text($filename, $content, $encoding, $crlf)

Writes $content to file $filename, encoding it to $encoding (which defaults to UTF-8). It can also take a "crlf" argument that works exactly as in read_text. Same crlf rules, no surprise plot twist. 💅

write_binary($filename, $content)

Writes $content to file $filename as binary data. No decoding, no extra drama. 🔥

read_dir($dirname)

Open $dirname and return all entries except "." and "..". That's it, that's the function. ✨

👑 RATIONALE 👑

okay so the whole point: this module tries to make it as easy as possible to read and write files correctly and fast. The most correct way of doing this is not always obvious — e.g. #83126 and the bug at https://rt.cpan.org/Public/Bug/Display.html?id=83126 — and just as often the most obvious correct way is not the fastest correct way. This module hides away all such complications behind an easy intuitive interface. It's giving "let the module handle the messy bits so you can go be iconic." 👑

🌈 DEPENDENCIES 🌈

File::Slurper has an optional dependency on PerlIO::utf8_strict. Installing this will make UTF-8 encoded IO significantly faster, but should not otherwise affect the operation of this module. This may change into a dependency on the related Unicode::UTF8 in the future. So optional now, maybe mandatory later, we'll see. 🌈

🦋 SEE ALSO 🦋

• Path::Tiny — A minimalistic abstraction handling not only IO but also paths.
• IO::All — An attempt to expose as many IO related features as possible via a single API.
• File::Slurp — This is a previous generation file slurping module. It has a number of issues, as described here at http://blogs.perl.org/users/leon_timmermans/2015/08/fileslurp-is-broken-and-wrong.html.
• File::Slurp::Tiny — This was my previous attempt at a better file slurping module. It's mostly (but not entirely) a drop-in replacement for File::Slurp, which is both a feature (easy conversion) and a bug (interface issues).

🎀 TODO 🎀

These are the maybe-someday ideas, no promises bestie:

• "open_text"/"open_binary"?
• "drain_handle"?

💜 AUTHOR 💜

Leon Timmermans <leont@cpan.org> — the icon behind this. 💜

🌸 COPYRIGHT AND LICENSE 🌸

This software is copyright (c) 2014 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay bestie, that's the page. This was File::Slurper(3) from perl v5.42.0, dated 2022-12-17 — go slurp something correctly and fast. 💖✨