.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "IO::Handle::Util 3pm"
.TH IO::Handle::Util 3pm "2018-07-01" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Handle::Util \- Functions for working with IO::Handle like objects.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # 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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a number of helpful routines to manipulate or create
IO::Handle like objects.
.SH "EXPORTS"
.IX Header "EXPORTS"
.SS "Coercions resulting in \s-1IO\s0 objects"
.IX Subsection "Coercions resulting in IO objects"
These are available using the \f(CW\*(C`:io_from\*(C'\fR export group.
.ie n .IP "io_from_any $whatever" 4
.el .IP "io_from_any \f(CW$whatever\fR" 4
.IX Item "io_from_any $whatever"
Inspects the value of \f(CW\*(C`whatever\*(C'\fR and calls the appropriate coercion function
on it, either \f(CW\*(C`io_from_ref\*(C'\fR or \f(CW\*(C`io_from_string\*(C'\fR.
.ie n .IP "io_from_ref $some_ref" 4
.el .IP "io_from_ref \f(CW$some_ref\fR" 4
.IX Item "io_from_ref $some_ref"
Depending on the reference type of \f(CW$some_ref\fR invokes either
\&\f(CW\*(C`io_from_object\*(C'\fR, \f(CW\*(C`io_from_array\*(C'\fR or \f(CW\*(C`io_from_scalar_ref\*(C'\fR.
.Sp
Code references are not coerced automatically because either \f(CW\*(C`io_from_thunk\*(C'\fR
or \f(CW\*(C`io_from_getline\*(C'\fR or \f(CW\*(C`io_from_write_cb\*(C'\fR could all make sense.
.Sp
Globs are returned as is \fBonly\fR if they have a valid \f(CW\*(C`IO\*(C'\fR slot.
.ie n .IP "io_from_object $obj" 4
.el .IP "io_from_object \f(CW$obj\fR" 4
.IX Item "io_from_object $obj"
Depending on the class of \f(CW$obj\fR either returns or coerces the object.
.PP
Objects that are passed through include anything that subclasses IO::Handle
or seems to duck type (supports the \f(CW\*(C`print\*(C'\fR and \f(CW\*(C`getline\*(C'\fR methods, which
might be a bit too permissive).
.PP
Objects that are coerced currently only include Path::Class::File, which
will have the \f(CW\*(C`openr\*(C'\fR method invoked on it.
.PP
Anything else is an error.
.ie n .IP "io_from_string $str" 4
.el .IP "io_from_string \f(CW$str\fR" 4
.IX Item "io_from_string $str"
Instantiates an IO::String object using \f(CW$str\fR as the buffer.
.Sp
Note that \f(CW$str\fR is \fBnot\fR passed as an alias, so writing to the \s-1IO\s0 object
will not modify string. For that see \f(CW\*(C`io_from_scalar_ref\*(C'\fR.
.IP "io_from_array \e@array" 4
.IX Item "io_from_array @array"
Creates an IO::Handle::Iterator that will return the elements of \f(CW@array\fR
one by one.
.Sp
Note that a \fIcopy\fR of \f(CW@array\fR is made.
.Sp
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.
.IP "io_from_scalar_ref \e$str" 4
.IX Item "io_from_scalar_ref $str"
Creates an IO::String object using \f(CW$str\fR as the buffer.
.Sp
Writing to the \s-1IO\s0 object will modify \f(CW$str\fR.
.IP "io_from_thunk sub { ... }" 4
.IX Item "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 \f(CW\*(C`io_from_array\*(C'\fR would.
.IP "io_from_getline sub { ... }" 4
.IX Item "io_from_getline sub { ... }"
Creates an IO::Handle::Iterator object using the callback.
.IP "io_from_write_cb sub { ... }" 4
.IX Item "io_from_write_cb sub { ... }"
Creates an IO::Handle::Prototype::Fallback using the callback.
.Sp
The callback will always be invoked with one string argument and with the
values of \f(CW$,\fR and \f(CW\*(C`$\e\*(C'\fR localized to \f(CW\*(C`undef\*(C'\fR.
.SS "Coercions utilizing \s-1IO\s0 objects"
.IX Subsection "Coercions utilizing IO objects"
These coercions will actually call \f(CW\*(C`io_from_any\*(C'\fR on their argument first. This
allows you to do things like:
.PP
.Vb 2
\&    my $str = \*(Aq\*(Aq;
\&    my $sub = io_to_write_cb(\e$str);
\&
\&    $sub\->("foo");
.Ve
.PP
These are available using the \f(CW\*(C`:io_to\*(C'\fR export group.
.ie n .IP "io_to_write_cb $thing" 4
.el .IP "io_to_write_cb \f(CW$thing\fR" 4
.IX Item "io_to_write_cb $thing"
Creates a code ref that will invoke \f(CW\*(C`print\*(C'\fR on the handle with the arguments
to the callback.
.Sp
\&\f(CW$,\fR and \f(CW\*(C`$\e\*(C'\fR will both be localized to \f(CW\*(C`undef\*(C'\fR.
.ie n .IP "io_to_read_cb $thing" 4
.el .IP "io_to_read_cb \f(CW$thing\fR" 4
.IX Item "io_to_read_cb $thing"
Creates a code ref that will invoke \f(CW\*(C`getline\*(C'\fR on the handle.
.Sp
\&\f(CW$/\fR will not be localized and should probably be set to a reference to a
number if you want efficient iteration. See perlvar for details.
.ie n .IP "io_to_string $thing" 4
.el .IP "io_to_string \f(CW$thing\fR" 4
.IX Item "io_to_string $thing"
Slurps a string out of the \s-1IO\s0 object by reading all the data.
.Sp
If a string was passed it is returned as is.
.ie n .IP "io_to_array $thing" 4
.el .IP "io_to_array \f(CW$thing\fR" 4
.IX Item "io_to_array $thing"
Returns an array reference containing all the lines of the \s-1IO\s0 object.
.Sp
If an array reference was passed it is returned as is.
.ie n .IP "io_to_list $thing" 4
.el .IP "io_to_list \f(CW$thing\fR" 4
.IX Item "io_to_list $thing"
Returns the list of lines from the \s-1IO\s0 object.
.Sp
Warns if not invoked in list context.
.Sp
If an array reference was passed it is dereferenced an its elements are
returned.
.ie n .IP "io_to_glob $thing" 4
.el .IP "io_to_glob \f(CW$thing\fR" 4
.IX Item "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 \s-1OO\s0 interface.
.Sp
This lets you use most of the builtins without the method syntax:
.Sp
.Vb 1
\&    my $fh = io_to_glob($some_kind_of_OO_handle);
\&
\&    while ( defined( my $line = <$fh> ) ) {
\&        ...
\&    }
.Ve
.SS "Misc functions"
.IX Subsection "Misc functions"
.ie n .IP "io_prototype %callbacks" 4
.el .IP "io_prototype \f(CW%callbacks\fR" 4
.IX Item "io_prototype %callbacks"
Given a key-value pair list of named callbacks, constructs an
IO::Handle::Prototype::Fallback object with those callbacks.
.Sp
For example:
.Sp
.Vb 2
\&    my $io = io_prototype print => sub {
\&        my $self = shift;
\&
\&        no warnings \*(Aquninitialized\*(Aq;
\&        $string .= join($,, @_) . $\e;
\&    };
\&
\&    $io\->say("Hello"); # $string now has "Hello\en"
.Ve
.Sp
See IO::Handle::Prototype::Fallback for more details.
.ie n .IP "is_real_fh $io" 4
.el .IP "is_real_fh \f(CW$io\fR" 4
.IX Item "is_real_fh $io"
Returns true if the \s-1IO\s0 handle probably could be passed to something like
AnyEvent::Handle which would break encapsulation.
.Sp
Checks for the following conditions:
.RS 4
.IP "\(bu" 4
The handle has a reftype of either a \f(CW\*(C`GLOB\*(C'\fR with an \f(CW\*(C`IO\*(C'\fR slot, or is an \f(CW\*(C`IO\*(C'\fR
itself.
.IP "\(bu" 4
The handle's \f(CW\*(C`fileno\*(C'\fR method returns a positive number, corresponding to a
filedescriptor.
.IP "\(bu" 4
The \f(CW\*(C`fileno\*(C'\fR builtin returns the same thing as \f(CW\*(C`fileno\*(C'\fR invoked as a method.
.RE
.RS 4
.Sp
If these conditions hold the handle is \fIprobably\fR \s-1OK\s0 to work with using the \s-1IO\s0
builtins directly, or passing the filedesctiptor to C land, instead of by
invoking methods on it.
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::Handle, FileHandle, IO::String, perlio, \*(L"open\*(R" in perlfunc
.SH "VERSION CONTROL"
.IX Header "VERSION CONTROL"
<http://github.com/nothingmuch/io\-handle\-util>
.SH "AUTHOR"
.IX Header "AUTHOR"
Yuval Kogman
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
.Vb 3
\&        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.
.Ve