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.
-
VERSION CONTROL
<http://github.com/nothingmuch/io-handle-util>AUTHOR
Yuval KogmanCOPYRIGHT & 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.