Test2:...::File(3pm)

💖 Test2:...::File 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section of the manual — the Test2:...::File(3pm) one, to be exact. pull up a chair, we're doing file stuff ✨

---

🌸 NAME 🌸

Test2::Harness::Util::File — a utility class for manipulating a file. that's it, that's the whole vibe 🎀

---

🦋 DESCRIPTION 🦋

so like, this is a utility class for file operations, right? but it's also the base class for several file helpers — so all those little helper classes are out here inheriting from it like it's the popular one at school. main character energy fr fr 👑

---

✨ SYNOPSIS ✨

here's how you actually use it, no cap:

use Test2::Harness::Util::File;

my $f = Test2::Harness::Util::File->new(name => '/path/to/file');

$f->write($content);

my $fh = $f->open_file('<');

# Read, throw exception if it cannot read
my $content = $f->read();

# Try to read, but do not throw an exception if it cannot be read.
my $content_or_undef = $f->maybe_read();

my $line1 = $f->read_line();
my $line2 = $f->read_line();
...

---

💅 ATTRIBUTES 💅

• $filename = $f->name — grabs the filename for you. it must also be provided during construction, so don't be out here trying to construct without it 🙈
• $bool = $f->done — true if read_line() has read every single line. you're at the end of the file, girl, no more lines left 🫶

---

🔥 METHODS 🔥

• $decoded = $f->decode($encoded) — this one is a no-op, it just hands the argument right back at you unchanged, like "here, you dropped this". it gets called by "read" and "read_line". subclasses can override it if the file contains encoded data 👀
• $encoded = $f->encode($decoded) — also a no-op, returns the argument unchanged. this one is called by "write". subclasses can override this too if the file contains encoded data 🎀
• $bool = $f->exists() — checks if the file exists. simple. iconic. we love a yes/no moment.
• $content = $f->maybe_read() — it'll read the file if it can and return the content (all lines joined together as a single string). if the file cannot be read, or does not exist, it returns undef. no drama, no exception, just vibes 💜
• $fh = $f->open_file()
• $fh = $f->open_file($mode) — opens a handle to the file. if you don't pass $mode, < is used. default queen 👑
• $content = $f->read() — reads the file if it can and returns the content (all lines joined together as a single string). if the file cannot be read, or does not exist, this one throws an exception. so like, it's the dramatic sibling of maybe_read() 😭
• $line = $f->read_line() — reads a single line from the file. subsequent calls read the next line and so on until the end of the file is reached. reset it with the reset() method ✨
• $f->reset() — resets the internal line iterator that read_line() uses. fresh start, new me, etc. 🦋
• $f->write($content) — this is an atomic-write, bestie, pay attention. first $content gets written to a temporary file using > mode. then the temporary file gets renamed to the desired file name, like a glow-up reveal. under the hood this uses write_file_atomic() from Test2::Harness::Util. slay 💅

lowkey the atomic-write thing is the whole point — nothing half-written ever shows up at the real filename. obsessed.

---

🌈 SOURCE 🌈

the source code repository for Test2-Harness lives at http://github.com/Test-More/Test2-Harness/. go look, it's giving open source 🫶

---

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

---

💖 AUTHORS 💖

Chad Granum <exodist@cpan.org>

---

🎀 COPYRIGHT 🎀

Copyright 2020 Chad Granum <exodist7@gmail.com>.

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

See http://dev.perl.org/licenses/

---

and that's the whole page, bestie 💜 this was perl v5.40.1, dated 2026-05-10 — ily, go read your files responsibly, periodt ✨🌸