1IO::Handle::Util(3pm) User Contributed Perl DocumentationIO::Handle::Util(3pm)
2
3
4

NAME

6       IO::Handle::Util - Functions for working with IO::Handle like objects.
7

SYNOPSIS

9           # make something that looks like a filehandle from a random data:
10           my $io = io_from_any $some_data;
11
12           # or from a callback that returns strings:
13           my $io = io_from_getline sub { return $another_line };
14
15           # create a callback that iterates through the handle
16           my $read_cb = io_to_read_cb $io;
17

DESCRIPTION

19       This module provides a number of helpful routines to manipulate or
20       create IO::Handle like objects.
21

EXPORTS

23   Coercions resulting in IO objects
24       These are available using the ":io_from" export group.
25
26       io_from_any $whatever
27           Inspects the value of "whatever" and calls the appropriate coercion
28           function on it, either "io_from_ref" or "io_from_string".
29
30       io_from_ref $some_ref
31           Depending on the reference type of $some_ref invokes either
32           "io_from_object", "io_from_array" or "io_from_scalar_ref".
33
34           Code references are not coerced automatically because either
35           "io_from_thunk" or "io_from_getline" or "io_from_write_cb" could
36           all make sense.
37
38           Globs are returned as is only if they have a valid "IO" slot.
39
40       io_from_object $obj
41           Depending on the class of $obj either returns or coerces the
42           object.
43
44           Objects that are passed through include anything that subclasses
45           IO::Handle or seems to duck type (supports the "print" and
46           "getline" methods, which might be a bit too permissive).
47
48           Objects that are coerced currently only include Path::Class::File,
49           which will have the "openr" method invoked on it.
50
51           Anything else is an error.
52
53       io_from_string $str
54           Instantiates an IO::String object using $str as the buffer.
55
56           Note that $str is not passed as an alias, so writing to the IO
57           object will not modify string. For that see "io_from_scalar_ref".
58
59       io_from_array \@array
60           Creates an IO::Handle::Iterator that will return the elements of
61           @array one by one.
62
63           Note that a copy of @array is made.
64
65           In order to be able to append more elements to the array or remove
66           the ones that have been returned use IO::Handle::Iterator yourself
67           directly.
68
69       io_from_scalar_ref \$str
70           Creates an IO::String object using $str as the buffer.
71
72           Writing to the IO object will modify $str.
73
74       io_from_thunk sub { ... }
75           Invokes the callback once in list context the first time it's
76           needed, and then returns each element of the list like
77           "io_from_array" would.
78
79       io_from_getline sub { ... }
80           Creates an IO::Handle::Iterator object using the callback.
81
82       io_from_write_cb sub { ... }
83           Creates an IO::Handle::Prototype::Fallback using the callback.
84
85           The callback will always be invoked with one string argument and
86           with the values of $, and "$\" localized to "undef".
87
88   Coercions utilizing IO objects
89       These coercions will actually call "io_from_any" on their argument
90       first. This allows you to do things like:
91
92           my $str = '';
93           my $sub = io_to_write_cb(\$str);
94
95           $sub->("foo");
96
97       These are available using the ":io_to" export group.
98
99       io_to_write_cb $thing
100           Creates a code ref that will invoke "print" on the handle with the
101           arguments to the callback.
102
103           $, and "$\" will both be localized to "undef".
104
105       io_to_read_cb $thing
106           Creates a code ref that will invoke "getline" on the handle.
107
108           $/ will not be localized and should probably be set to a reference
109           to a number if you want efficient iteration. See perlvar for
110           details.
111
112       io_to_string $thing
113           Slurps a string out of the IO object by reading all the data.
114
115           If a string was passed it is returned as is.
116
117       io_to_array $thing
118           Returns an array reference containing all the lines of the IO
119           object.
120
121           If an array reference was passed it is returned as is.
122
123       io_to_list $thing
124           Returns the list of lines from the IO object.
125
126           Warns if not invoked in list context.
127
128           If an array reference was passed it is dereferenced an its elements
129           are returned.
130
131       io_to_glob $thing
132           If the filehandle is an unblessed glob returns it as is, otherwise
133           returns a new glob which is tied to delegate to the OO interface.
134
135           This lets you use most of the builtins without the method syntax:
136
137               my $fh = io_to_glob($some_kind_of_OO_handle);
138
139               while ( defined( my $line = <$fh> ) ) {
140                   ...
141               }
142
143   Misc functions
144       io_prototype %callbacks
145           Given a key-value pair list of named callbacks, constructs an
146           IO::Handle::Prototype::Fallback object with those callbacks.
147
148           For example:
149
150               my $io = io_prototype print => sub {
151                   my $self = shift;
152
153                   no warnings 'uninitialized';
154                   $string .= join($,, @_) . $\;
155               };
156
157               $io->say("Hello"); # $string now has "Hello\n"
158
159           See IO::Handle::Prototype::Fallback for more details.
160
161       is_real_fh $io
162           Returns true if the IO handle probably could be passed to something
163           like AnyEvent::Handle which would break encapsulation.
164
165           Checks for the following conditions:
166
167           •   The handle has a reftype of either a "GLOB" with an "IO" slot,
168               or is an "IO" itself.
169
170           •   The handle's "fileno" method returns a positive number,
171               corresponding to a filedescriptor.
172
173           •   The "fileno" builtin returns the same thing as "fileno" invoked
174               as a method.
175
176           If these conditions hold the handle is probably OK to work with
177           using the IO builtins directly, or passing the filedescriptor to C
178           land, instead of by invoking methods on it.
179

SEE ALSO

181       IO::Handle, FileHandle, IO::String, perlio, "open" in perlfunc
182

VERSION CONTROL

184       <http://github.com/nothingmuch/io-handle-util>
185

AUTHOR

187       Yuval Kogman
188
190               Copyright (c) 2009 Yuval Kogman. All rights reserved
191               This program is free software; you can redistribute
192               it and/or modify it under the same terms as Perl itself.
193
194
195
196perl v5.34.0                      2021-07-22             IO::Handle::Util(3pm)
Impressum