NAME¶
IO::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>
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.