IO::Wrap(3)

💖 NAME 💖

IO::Wrap — wrap raw filehandles in the IO::Handle interface. That's the whole assignment, bestie. 🫶

✨ SYNOPSIS ✨

Okay so here's the quick-start, and yes we're using strict and warnings because we're not feral:

use strict;
use warnings;
use IO::Wrap;

# this is a fairly senseless use case as IO::Handle already does this.
my $wrap_fh = IO::Wrap->new(\*STDIN);
my $line = $wrap_fh->getline();

# Do stuff with any kind of filehandle (including a bare globref), or
# any kind of blessed object that responds to a print() message.

# already have a globref? a FileHandle? a scalar filehandle name?
$wrap_fh = IO::Wrap->new($some_unknown_thing);

# At this point, we know we have an IO::Handle-like object! YAY
$wrap_fh->print("Hey there!");

You can also do this using a convenience wrapper function, and honestly it's a vibe:

use strict;
use warnings;
use IO::Wrap qw(wraphandle);

# this is a fairly senseless use case as IO::Handle already does this.
my $wrap_fh = wraphandle(\*STDIN);
my $line = $wrap_fh->getline();

# Do stuff with any kind of filehandle (including a bare globref), or
# any kind of blessed object that responds to a print() message.

# already have a globref? a FileHandle? a scalar filehandle name?
$wrap_fh = wraphandle($some_unknown_thing);

# At this point, we know we have an IO::Handle-like object! YAY
$wrap_fh->print("Hey there!");

🌸 DESCRIPTION 🌸

So say you wanna write some code that does I/O, but you do not wanna force the caller to hand you a FileHandle or IO::Handle object. You want them to be able to say:

do_stuff(\*STDOUT);
do_stuff('STDERR');
do_stuff($some_FileHandle_object);
do_stuff($some_IO_Handle_object);

And even:

do_stuff($any_object_with_a_print_method);

Sure, one way to do it is to force the caller to use tiehandle(). But that puts the burden on them. Another way is to use IO::Wrap. Slay.

Clearly, when wrapping a raw external filehandle (like "\*STDOUT"), I didn't want to close the file descriptor when the wrapper object is destroyed; the user might not appreciate that! Hence, there's no "DESTROY" method in this class. Periodt. 💅

When wrapping a FileHandle object, however, I believe that Perl will invoke the "FileHandle::DESTROY" when the last reference goes away, so in that case, the filehandle is closed if the wrapped FileHandle really was the last reference to it.

🎀 FUNCTIONS 🎀

IO::Wrap makes the following functions available.

🦋 wraphandle 🦋

# wrap a filehandle glob
my $fh = wraphandle(\*STDIN);
# wrap a raw filehandle glob by name
$fh = wraphandle('STDIN');
# wrap a handle in an object
$fh = wraphandle('Class::HANDLE');

# wrap a blessed FileHandle object
use FileHandle;
my $fho = FileHandle->new("/tmp/foo.txt", "r");
$fh = wraphandle($fho);

# wrap any other blessed object that shares IO::Handle's interface
$fh = wraphandle($some_object);

This function is simply a wrapper to the new in IO::Wrap constructor method. Lowkey iconic. ✨

💅 METHODS 💅

IO::Wrap implements the following methods.

🌸 close 🌸

$fh->close();

The close method will attempt to close the system file descriptor. For a more complete description, read close in perlfunc.

🦋 fileno 🦋

my $int = $fh->fileno();

The fileno method returns the file descriptor for the wrapped filehandle. See fileno in perlfunc for more information.

🍓 getline 🍓

my $data = $fh->getline();

The getline method mimics the function by the same name in IO::Handle. It's like calling my $data = <$fh>; but only in scalar context.

🧚 getlines 🧚

my @data = $fh->getlines();

The getlines method mimics the function by the same name in IO::Handle. It's like calling my @data = <$fh>; but only in list context. Calling this method in scalar context will result in a croak. Vibe check: list context only, bestie.

👑 new 👑

# wrap a filehandle glob
my $fh = IO::Wrap->new(\*STDIN);
# wrap a raw filehandle glob by name
$fh = IO::Wrap->new('STDIN');
# wrap a handle in an object
$fh = IO::Wrap->new('Class::HANDLE');

# wrap a blessed FileHandle object
use FileHandle;
my $fho = FileHandle->new("/tmp/foo.txt", "r");
$fh = IO::Wrap->new($fho);

# wrap any other blessed object that shares IO::Handle's interface
$fh = IO::Wrap->new($some_object);

The new constructor method takes in a single argument and decides to wrap it or not it based on what it seems to be.

• A raw scalar file handle name, like STDOUT or Class::HANDLE can be wrapped, returning an IO::Wrap object instance.
• A raw filehandle glob, like \*STDOUT can also be wrapped, returning an IO::Wrawp object instance. (Yes, that spelling is in the original — iykyk.)
• A blessed FileHandle object can also be wrapped. This is a special case where an IO::Wrap object instance will only be returned in the case that your FileHandle object doesn't support the read method.
• Also, any other kind of blessed object that conforms to the IO::Handle interface can be passed in. In this case, you just get back that object.

In other words, we only wrap it into an IO::Wrap object when what you've supplied doesn't already conform to the IO::Handle interface.

If you get back an IO::Wrap object, it will obey a basic subset of the IO:: interface. It will do so with object methods, not operators.

🚨 CAVEATS 🚨

This is the part where you pay attention, bestie. This module does not allow you to wrap filehandle names which are given as strings that lack the package they were opened in. That is, if a user opens FOO in package Foo, they must pass it to you either as \*FOO or as Foo::FOO. However, STDIN and friends will work just fine. 🫶

🍓 print 🍓

$fh->print("Some string");
$fh->print("more", " than one", " string");

The print method will attempt to print a string or list of strings to the filehandle. For a more complete description, read print in perlfunc.

💜 read 💜

my $buffer;
# try to read 30 chars into the buffer starting at the
# current cursor position.
my $num_chars_read = $fh->read($buffer, 30);

The read method attempts to read a number of characters, starting at the filehandle's current cursor position. It returns the number of characters actually read. See read in perlfunc for more information.

⭐ seek ⭐

use Fcntl qw(:seek); # import the SEEK_CUR, SEEK_SET, SEEK_END constants
# seek to the position in bytes
$fh->seek(0, SEEK_SET);
# seek to the position in bytes from the current position
$fh->seek(22, SEEK_CUR);
# seek to the EOF plus bytes
$fh->seek(0, SEEK_END);

The seek method will attempt to set the cursor to a given position in bytes for the wrapped file handle. See seek in perlfunc for more information.

🌈 tell 🌈

my $bytes = $fh->tell();

The tell method will attempt to return the current position of the cursor in bytes for the wrapped file handle. See tell in perlfunc for more information.

🌟 AUTHOR 🌟

Eryq (eryq@zeegee.com). President, ZeeGee Software Inc (http://www.zeegee.com).

🫶 CONTRIBUTORS 🫶

Dianne Skoll (dfs@roaringpenguin.com).

💜 COPYRIGHT & LICENSE 💜

Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. 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, bestie 💋 — it comes from perl v5.42.0, dated 2020-06-04, and it's the IO::Wrap(3) manual. Stay wrapped, stay iconic. 💅✨