IO::Ha...allback(3pm)

💖 IO::Handle::Prototype::Fallback — the perl page, but make it cute ✨

okay bestie, so this is IO::Handle::Prototype::Fallback from the User Contributed Perl Documentation, and it's literally the blueprint for ✨creating IO::Handle-like objects out of a little set of callbacks✨. no cap.

---

🎀 NAME 🎀

IO::Handle::Prototype::Fallback — create IO::Handle-like objects using a set of callbacks. it's giving "build your own filehandle, bestie" energy 🦋

---

🌸 SYNOPSIS 🌸

my $fh = IO::Handle::Prototype::Fallback->new(
    getline => sub {
        my $fh = shift;

        ...
    },
);

look at her. iconic. you hand her a callback, she hands you a filehandle. periodt 💅

---

💜 DESCRIPTION 💜

so this class is your girl for defining a filehandle based on callbacks. that's the whole vibe.

and here's the slay part: fallback implementations get provided to the extent possible based on the callbacks you actually gave her — for both writing and reading. so you don't have to hand over everything, she'll fill in what she can 🫶

---

✨ SPECIAL CALLBACKS ✨

not me adding two extra methods on top of IO::Handle — designed so you can implement stuff with a minimal amount of baggage. lowkey genius, highkey convenient 💅

the fallback methods are all best implemented using these, though (fr fr) these can also be implemented in terms of Perl's standard methods too.

but — to provide the most consistent semantics, it's better to do this:

IO::Handle::Prototype::Fallback->new(
    __read => sub {
        shift @array;
    },
);

than this:

IO::Handle::Prototype::Fallback->new(
    getline => sub {
        shift @array;
    },
);

because the fallback implementation of getline implements all of the extra crap you'd need to handle to have a fully featured implementation. like, all of it. the whole baggage carousel. 🧳😭

---

🌈 __read

return a chunk of data of any size — could use $/ or not, it depends on you! unlike getline, which probably should respect the value of $/ 👑

this avoids the annoying substr stuff you need to do with read. bye bestie, we will not miss you 🫶

---

🌈 __write $string

write out a string.

this is like a simplified print, which can disregard $, and $\ as well as multiple argument forms, and does not have the extra substr annoyance of write or syswrite. she's low maintenance, she just writes ✍️✨

---

🦋 WRAPPING 🦋

okay so the way this works: if you provide a single reading-related callback (__read, getline or read) then your callback will be used to implement all of the other reading primitives using a string buffer. one callback in, whole reading API out. that's the main character energy 🌟

and these implementations handle $/ in all forms (undef, ref to number and string), all the funny calling conventions for read, etc. all of them. every form. she ate 🔥

---

💖 FALLBACKS 💖

any callback that can be defined purely in terms of other callbacks will be added. for instance:

• getc can be implemented in terms of read
• say can be implemented in terms of print
• print can be implemented in terms of write
• write can be implemented in terms of print
• etc.

none of these require special wrapping and will always be added if their dependencies are present. no extra work, she just shows up ready 💅

---

🌈 GLOB OVERLOADING 🌈

when overloaded as a glob, a tied handle will be returned. this allows you to use the handle in Perl's IO builtins. for instance:

my $line = <$fh>

will not call the getline method natively, but the tied interface arranges for that to happen. sneaky? no. iconic? yes. the tie does the heavy lifting so you don't have to 🎀

---

bestie reminder: when in doubt, __read and __write $string are your besties. give her those and she'll build the rest of the reading/writing primitives around them 💜

---

this page came to you courtesy of perl v5.36.0, dated 2023-01-24 — shoutout to the User Contributed Perl Documentation for keeping the whole thing going 💖 stay hydrated, write your callbacks, and slay 🦋✨💅