IO::Handle::Util(3) User Contributed Perl Documentation IO::Handle::Util(3)NAMEIO::Handle::Util - Functions for working with IO::Handle like objects.
SYNOPSIS
# 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;
DESCRIPTION
This module provides a number of helpful routines to manipulate or
create IO::Handle like objects.
EXPORTS
Coercions resulting in IO objects
These are available using the ":io_from" export group.
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".
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 not coerced automatically because either
"io_from_thunk" or "io_from_getline" or "io_from_write_cb" could
all make sense.
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.
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".
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.
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.
io_from_scalar_ref \$str
Creates an IO::String object using $str as the buffer.
Writing to the IO object will modify $str.
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.
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".
Coercions utilizing IO objects
These coercions will actually call "io_from_any" on their argument
first. This allows you to do things like:
my $str = '';
my $sub = io_to_write_cb(\$str);
$sub->("foo");
These are available using the ":io_to" 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".
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.
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.
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.
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:
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.
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 filedesctiptor to C
land, instead of by invoking methods on it.
SEE ALSO
IO::Handle, FileHandle, IO::String, perlio, "open" in perlfunc
VERSION CONTROL
http://github.com/nothingmuch/io-handle-util
<http://github.com/nothingmuch/io-handle-util>
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.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 425:
You forgot a '=back' before '=head2'
perl v5.14.1 2009-10-01 IO::Handle::Util(3)
