IO::Handle::Util(3pm)

💖 IO::Handle::Util — the IO::Handle::Util(3pm) era 💖

okay bestie, listen up — this is a page from the User Contributed Perl Documentation, and it's all about making stuff that acts like a filehandle without, like, being one. ✨

---

🌸 NAME 🌸

IO::Handle::Util — Functions for working with IO::Handle like objects. that's it, that's the whole vibe 🫶

---

🎀 SYNOPSIS 🎀

here's the whole plot in three little scenes:

# make something that looks like a filehandle from a random data:
my $io = io_from_any $some_data;

# or from a callback that returns strings:
my $io = io_from_getline sub { return $another_line };

# create a callback that iterates through the handle
my $read_cb = io_to_read_cb $io;

like… the range?? 😭 she does both directions

---

🦋 DESCRIPTION 🦋

This module provides a number of helpful routines to manipulate or create IO::Handle like objects. basically: fake it till you make it, but the faking is extremely well-engineered 💅

---

✨ EXPORTS ✨

💜 Coercions resulting in IO objects

These are available using the <code>":io_from"</code> export group. (iykyk — pull them in and go)

• io_from_any $whatever — Inspects the value of whatever and calls the appropriate coercion function on it, either io_from_ref or io_from_string. she's the bouncer at the door, she decides which function you're meeting tonight 🌈
• io_from_ref $some_ref — Depending on the reference type of $some_ref invokes either io_from_object, io_from_array or io_from_scalar_ref.

Code references are <strong>not</strong> coerced automatically because either io_from_thunk or io_from_getline or io_from_write_cb could all make sense. like girl, we're not gonna guess which one you meant, that's rude 🙈

Globs are returned as is only if they have a valid IO slot.

• io_from_object $obj — Depending on the class of $obj either returns or coerces the object.

Objects that are passed through include anything that subclasses IO::Handle or seems to duck type (supports the print and getline methods, which might be a bit too permissive).

Objects that are coerced currently only include Path::Class::File, which will have the openr method invoked on it.

Anything else is an error. periodt 💀

• io_from_string $str — Instantiates an IO::String object using $str as the buffer.

Note that $str is not passed as an alias, so writing to the IO object will not modify string. For that see io_from_scalar_ref. she's giving copy, not reference 🎀

• io_from_array \@array — Creates an IO::Handle::Iterator that will return the elements of @array one by one.

Note that a copy of @array is made. your original array is safe, she's not touching it 🫶

In order to be able to append more elements to the array or remove the ones that have been returned use IO::Handle::Iterator yourself directly. DIY era, honestly

• io_from_scalar_ref \$str — Creates an IO::String object using $str as the buffer.

Writing to the IO object will modify $str. this one's the real one, the alias, the main character 👑

• io_from_thunk sub { ... } — Invokes the callback once in list context the first time it's needed, and then returns each element of the list like io_from_array would. lazy girl math, but make it correct ✨
• io_from_getline sub { ... } — Creates an IO::Handle::Iterator object using the callback.
• io_from_write_cb sub { ... } — Creates an IO::Handle::Prototype::Fallback using the callback.

The callback will always be invoked with one string argument and with the values of $, and $\ localized to undef. cleaning up after herself, we love to see it 🧚

---

🌈 Coercions utilizing IO objects

These coercions will actually call <code>io_from_any</code> on their argument first. This allows you to do things like:

my $str = '';
my $sub = io_to_write_cb(\$str);

$sub->("foo");

see how the string goes in and a callback comes out?? ate 💅

These are available using the <code>":io_to"</code> export group.

• io_to_write_cb $thing — Creates a code ref that will invoke print on the handle with the arguments to the callback.

$, and $\ will both be localized to undef. no stray separators sneaking in, nope 🙈

• io_to_read_cb $thing — Creates a code ref that will invoke getline on the handle.

$/ will not be localized and should probably be set to a reference to a number if you want efficient iteration. See perlvar for details. do your homework bestie, it's literally one variable 📚

• io_to_string $thing — Slurps a string out of the IO object by reading all the data.

If a string was passed it is returned as is. no extra work, no notes 💅

• io_to_array $thing — Returns an array reference containing all the lines of the IO object.

If an array reference was passed it is returned as is.

• io_to_list $thing — Returns the list of lines from the IO object.

Warns if not invoked in list context. she WILL call you out, respectfully 💀

If an array reference was passed it is dereferenced an its elements are returned.

• io_to_glob $thing — If the filehandle is an unblessed glob returns it as is, otherwise returns a new glob which is tied to delegate to the OO interface.

This lets you use most of the builtins without the method syntax: glorious 🔥

my $fh = io_to_glob($some_kind_of_OO_handle);

while ( defined( my $line = <$fh> ) ) {
    ...
}

---

🍓 Misc functions

• io_prototype %callbacks — Given a key-value pair list of named callbacks, constructs an IO::Handle::Prototype::Fallback object with those callbacks.

For example:

my $io = io_prototype print => sub {
    my $self = shift;

    no warnings 'uninitialized';
    $string .= join($,, @_) . $\;
};

$io->say("Hello"); # $string now has "Hello\n"

See IO::Handle::Prototype::Fallback for more details. go read it, she's iconic too ✨

• is_real_fh $io — Returns true if the IO handle probably could be passed to something like AnyEvent::Handle which would break encapsulation.

Checks for the following conditions:

• The handle has a reftype of either a "GLOB" with an "IO" slot, or is an "IO" itself.
• The handle's "fileno" method returns a positive number, corresponding to a filedescriptor.
• The "fileno" builtin returns the same thing as "fileno" invoked as a method.

If these conditions hold the handle is probably OK to work with using the IO builtins directly, or passing the filedescriptor to C land, instead of by invoking methods on it. vibe check passed, you're a real one 💖

---

🔍 SEE ALSO 🔍

IO::Handle, FileHandle, IO::String, perlio, "open" in perlfunc the whole friend group 🫶

---

🧚 VERSION CONTROL 🧚

<http://github.com/nothingmuch/io-handle-util>

go star it, bestie ⭐

---

👑 AUTHOR 👑

Yuval Kogman

---

📜 COPYRIGHT & LICENSE 📜

Copyright (c) 2009 Yuval Kogman. All rights reserved
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, no cap 🎀

this was <code>perl v5.36.0</code>, dated <code>2023-01-24</code>, and it lives under the manual name <code>IO::Handle::Util(3pm)</code> — slay, drink water, close your filehandles 💅✨💖