NAME<\/a> IO::Wrap \u2212 Wrap raw filehandles in the IO::Handle interface<\/p>\n use strict; You can also do this using a convenience wrapper function<\/p>\n use strict; Let\u2019s say you want to write some code which does I\/O, but you don\u2019t want to force the caller to provide you with a FileHandle or IO::Handle object. You want them to be able to say:<\/p>\n do_stuff(*STDOUT); And even:<\/p>\n do_stuff($any_object_with_a_print_method);<\/p>\n Sure, one way to do it is to force the caller to use “tiehandle()”. But that puts the burden on them. Another way to do it is to use IO::Wrap<\/b>.<\/p>\n Clearly, when wrapping a raw external filehandle (like “*STDOUT”), I didn\u2019t want to close the file descriptor when the wrapper object is destroyed; the user might not appreciate that! Hence, there\u2019s no “DESTROY” method in this class.<\/p>\n 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.<\/p>\n IO::Wrap makes the following functions available.<\/p>\n wraphandle<\/b> This function is simply a wrapper to the “new” in IO::Wrap constructor method.<\/p>\n IO::Wrap implements the following methods.<\/p>\n close<\/b> The “close” method will attempt to close the system file descriptor. For a more complete description, read “close” in perlfunc.<\/p>\n fileno<\/b> The “fileno” method returns the file descriptor for the wrapped filehandle. See “fileno” in perlfunc for more information.<\/p>\n getline<\/b> The “getline” method mimics the function by the same name in IO::Handle. It\u2019s like calling “my $data = <$fh>;” but only in scalar context.<\/p>\n getlines<\/b> The “getlines” method mimics the function by the same name in IO::Handle. It\u2019s like calling “my @data = <$fh>;” but only in list context. Calling this method in scalar context will result in a croak.<\/p>\n new<\/b> The “new” constructor method takes in a single argument and decides to wrap it or not it based on what it seems to be.<\/p>\n A raw scalar file handle name, like “STDOUT” or “Class::HANDLE” can be wrapped, returning an IO::Wrap object instance.<\/p>\n A raw filehandle glob, like “*STDOUT” can also be wrapped, returning an IO::Wrawp object instance.<\/p>\n 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\u2019t support the “read” method.<\/p>\n 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.<\/p>\n In other words, we only wrap it into an IO::Wrap object when what you\u2019ve supplied doesn\u2019t already conform to the IO::Handle interface.<\/p>\n 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<\/b>, not operators<\/b>.<\/p>\n CAVEATS<\/small><\/i><\/p>\n 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<\/small> in package Foo, they must pass it to you either as “*FOO” or as “Foo::FOO”. However, “STDIN” and friends will work just fine.<\/p>\n print<\/b> 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.<\/p>\n read<\/b> The read method attempts to read a number of characters, starting at the filehandle\u2019s current cursor position. It returns the number of characters actually read. See “read” in perlfunc for more information.<\/p>\n seek<\/b> 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.<\/p>\n tell<\/b> 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.<\/p>\n Eryq (eryq@zeegee.com<\/i>). President, ZeeGee Software Inc (http:\/\/www.zeegee.com<\/i>).<\/p>\n
SYNOPSIS<\/a>
DESCRIPTION<\/a>
FUNCTIONS<\/a>
METHODS<\/a>
AUTHOR<\/a>
CONTRIBUTORS<\/a>
COPYRIGHT & LICENSE<\/a> <\/p>\n
\nNAME <\/a> <\/h2>\n
SYNOPSIS <\/a> <\/h2>\n
use warnings;
use IO::Wrap;
# this is a fairly senseless use case as IO::Handle already does this.
my $wrap_fh = IO::Wrap\u2212>new(*STDIN);
my $line = $wrap_fh\u2212>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\u2212>new($some_unknown_thing);
# At this point, we know we have an IO::Handle\u2212like object! YAY
$wrap_fh\u2212>print(“Hey there!”);<\/p>\n
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\u2212>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\u2212like object! YAY
$wrap_fh\u2212>print(“Hey there!”);<\/p>\nDESCRIPTION <\/a> <\/h2>\n
do_stuff(‘STDERR’);
do_stuff($some_FileHandle_object);
do_stuff($some_IO_Handle_object);<\/p>\nFUNCTIONS <\/a> <\/h2>\n
# 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\u2212>new(“\/tmp\/foo.txt”, “r”);
$fh = wraphandle($fho);
# wrap any other blessed object that shares IO::Handle’s interface
$fh = wraphandle($some_object);<\/p>\nMETHODS <\/a> <\/h2>\n
$fh\u2212>close();<\/p>\n
my $int = $fh\u2212>fileno();<\/p>\n
my $data = $fh\u2212>getline();<\/p>\n
my @data = $fh\u2212>getlines();<\/p>\n
# wrap a filehandle glob
my $fh = IO::Wrap\u2212>new(*STDIN);
# wrap a raw filehandle glob by name
$fh = IO::Wrap\u2212>new(‘STDIN’);
# wrap a handle in an object
$fh = IO::Wrap\u2212>new(‘Class::HANDLE’);
# wrap a blessed FileHandle object
use FileHandle;
my $fho = FileHandle\u2212>new(“\/tmp\/foo.txt”, “r”);
$fh = IO::Wrap\u2212>new($fho);
# wrap any other blessed object that shares IO::Handle’s interface
$fh = IO::Wrap\u2212>new($some_object);<\/p>\n
$fh\u2212>print(“Some string”);
$fh\u2212>print(“more”, ” than one”, ” string”);<\/p>\n
my $buffer;
# try to read 30 chars into the buffer starting at the
# current cursor position.
my $num_chars_read = $fh\u2212>read($buffer, 30);<\/p>\n
use Fcntl qw(:seek); # import the SEEK_CUR, SEEK_SET, SEEK_END constants
# seek to the position in bytes
$fh\u2212>seek(0, SEEK_SET);
# seek to the position in bytes from the current position
$fh\u2212>seek(22, SEEK_CUR);
# seek to the EOF plus bytes
$fh\u2212>seek(0, SEEK_END);<\/p>\n
my $bytes = $fh\u2212>tell();<\/p>\nAUTHOR <\/a> <\/h2>\n
CONTRIBUTORS <\/a> <\/h2>\n