IO::Handle::Util - Functions for working with IO::Handle like objects.
# 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;
This module provides a number of helpful routines to manipulate or create IO::Handle like objects.
These are available using the :io_from export group.
:io_from
Inspects the value of whatever and calls the appropriate coercion function on it, either io_from_ref or io_from_string.
whatever
io_from_ref
io_from_string
Depending on the reference type of $some_ref invokes either io_from_object, io_from_array or io_from_scalar_ref.
$some_ref
io_from_object
io_from_array
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.
io_from_thunk
io_from_getline
io_from_write_cb
Globs are returned as is only if they have a valid IO slot.
IO
Depending on the class of $obj either returns or coerces the object.
$obj
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).
print
getline
Objects that are coerced currently only include Path::Class::File, which will have the openr method invoked on it.
openr
Anything else is an error.
Instantiates an IO::String object using $str as the buffer.
$str
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.
Creates an IO::Handle::Iterator that will return the elements of @array one by one.
@array
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.
Creates an IO::String object using $str as the buffer.
Writing to the IO object will modify $str.
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.
Creates an IO::Handle::Iterator object using the callback.
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.
$,
$\
undef
These coercions will actually call io_from_any on their argument first. This allows you to do things like:
io_from_any
my $str = ''; my $sub = io_to_write_cb(\$str); $sub->("foo");
These are available using the :io_to export group.
:io_to
Creates a code ref that will invoke print on the handle with the arguments to the callback.
$, and $\ will both be localized to undef.
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.
$/
Slurps a string out of the IO object by reading all the data.
If a string was passed it is returned as is.
Returns an array reference containing all the lines of the IO object.
If an array reference was passed it is returned as is.
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.
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> ) ) { ... }
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.
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.
GLOB
The handle's fileno method returns a positive number, corresponding to a filedescriptor.
fileno
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.
IO::Handle, FileHandle, IO::String, perlio, "open" in perlfunc
http://github.com/nothingmuch/io-handle-util
Yuval Kogman
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.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install IO::Handle::Util, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Handle::Util
CPAN shell
perl -MCPAN -e shell install IO::Handle::Util
For more information on module installation, please visit the detailed CPAN module installation guide.