Test::...Handle(3pm)

📦
version 0.039 · 4 versions
, in ubuntu stonking

💖 Test::MockFile::FileHandle — the glow-up class edition ✨

okay so bestie, picture this: Test::MockFile</p> needs a whole class to tie its filehandles to, and this is her 👑. She's a helper class, lives in her own package, and she's documented in the User Contributed Perl Documentation corner of the manual, filed under Test::...Handle(3pm). She's basically the backstage crew for the main character — no cap. 🎀

✨ VERSION ✨

Version 0.039 — that's the vibe check, she's on 0.039. 🦋

🌸 SYNOPSIS 🌸

So this is a helper class for Test::MockFile, right? It's fully borrowing data from the Test::MockFile namespace, but it lives in its own lil package, because she's literally the class that filehandles get tied to when you make them inside Test::MockFile. iykyk 💅

use Test::MockFile::FileHandle;
tie *{ $_[0] }, 'Test::MockFile::FileHandle', $abs_path, $rw;

🫶 EXPORT 🫶

No exports are provided by this module. Not one. Zero. She gives nothing away, she's not that kind of girl 🙈.

⭐ SUBROUTINES/METHODS ⭐

💜 TIEHANDLE

Args: ($class, $file, $mode)

Returns a blessed object for Test::MockFile to tie against. There are no error conditions handled here — she's not stressing about edge cases in this one, that's just the deal.

One of the object variables she's keeping track of here is a pointer to the file contents in %Test::MockFile::files_being_mocked. And the way that she has to weaken that pointer is so that the MockFiles can get DESTROYED when they go out of scope 🫠. Like, you gotta let them go, bestie.

See Test::MockFile for more info.

🎀 PRINT

This method gets triggered every single time the tied handle gets printed to via the print() or say() functions 📣. Beyond her own self-reference, she also expects the list that was passed to the print function.

In append mode (">>" or "+>>"), output is always written at the end of the file contents. In other write modes, output is written at the current tell position, overwriting existing bytes. The tell position advances by the number of bytes written. Slay, but precisely 💅

If the filehandle wasn't opened in a write mode, this call will set $! to EBADF and return. Rude, but that's the rules.

🌈 PRINTF

This method gets triggered every time the tied handle is printed to with the printf() function. Beyond her self reference she also expects the format and list that were passed to the printf function.

Per "printf" in perlfunc, "printf" does not append "$\" (the output record separator), unlike "print". So she writes directly via "_write_bytes" instead of delegating to "PRINT". Different function, different needs, periodt ✨

🦋 WRITE

This method gets called when the handle is written to via the syswrite function.

Arguments passed are: "( $self, $buf, $len, $offset )"

ngl this is one of the more complicated functions to mimic properly, because $len and $offset have to be taken into account 😭. Reviewing how syswrite works reveals there are all sorts of weird corner cases. Absolutely feral behaviour from syswrite, but she handles it.

🍓 READLINE

This method gets called when the handle is read via <HANDLE> or readline HANDLE.

Based on the numeric location we're at in the file (tell), she reads until the EOF separator ($/) is seen. The tell gets updated after the line is read ✨. undef is returned if tell is already at EOF.

🧚 GETC

This method gets called when the getc function is called. She reads 1 character out of contents and adds 1 to tell. The character is returned. Returns undef at EOF. Tiny but mighty 💫

💫 READ

Arguments passed are: "( $self, $file_handle, $len, $offset )"

This method gets called when the handle is read from via the read or sysread functions. Based on $offset and $len, it's possible to end up with some really weird strings with null bytes in them 👀. Like, truly cursed strings. Don't say she didn't warn you.

🔥 CLOSE

This method gets called when the handle is closed via the close function. The object gets untied and the file contents (weak reference) get removed. Further calls to this object should fail 🫣. She's gone, she's not coming back, don't @ her.

🌸 UNTIE

As with the other types of ties, this method gets called when untie happens. It may be appropriate to "auto CLOSE" when this occurs. See The untie Gotcha below.

okay so what's genuinely strange about developing this class is that we were unable to determine how to trigger this call 💀. At the moment, the call is just redirected to CLOSE. She's mysterious like that.

👑 DESTROY

As with the other types of ties, this method gets called when the tied handle is about to be destroyed. This is useful for debugging and possibly cleaning up 🧹.

At the moment, the call is just redirected to CLOSE.

🌟 EOF

This method gets called when the eof function is called. Based on "$self->{'tell'}", she determines if we're at EOF. Simple, clean, iconic.

🎀 BINMODE

binmode does nothing, because whatever format you put the data into the file as is exactly how it will come out 💅. In theory she could decode the SV if this was done, but then she'd have to do it every single time contents are altered 😮💨. Please open a ticket if you want this to do something.

No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists on this method.

🙈 OPEN

UNIMPLEMENTED: Open a ticket in github <https://github.com/cpanel/Test-MockFile/issues> if you need this feature.

No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists on this method.

🙈 FILENO

UNIMPLEMENTED: Open a ticket in github <https://github.com/cpanel/Test-MockFile/issues> if you need this feature.

No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists on this method.

⭐ SEEK

Arguments passed are: "( $self, $pos, $whence )"

Moves the location of our current tell location. Glow-up for your file position ✨

$whence controls the seek origin:

  • 0 (SEEK_SET) — seek to $pos from start of file
  • 1 (SEEK_CUR) — seek to $pos relative to current position
  • 2 (SEEK_END) — seek to $pos relative to end of file
No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists on this method.

💖 TELL

Returns the numeric location we're at in the file. The "TELL" tells us where we are in the file contents 🗺️.

No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists on this method.

💌 oh and before you go — this whole page was served up by perl v5.40.1 on 2026-03-27, courtesy of the User Contributed Perl Documentation girlys. mwah, go write some tests bestie 🫶🌈

📦 where this page comes from