1IO::Handle::Util(3) User Contributed Perl Documentation IO::Handle::Util(3)
2
6 IO::Handle::Util - Functions for working with IO::Handle like objects.
7
9 # make something that looks like a filehandle from a random data:
10 my $io = io_from_any $some_data;
11 # or from a callback that returns strings:
13 my $io = io_from_getline sub { return $another_line };
14 # create a callback that iterates through the handle
16 my $read_cb = io_to_read_cb $io;
17
19 This module provides a number of helpful routines to manipulate or
20 create IO::Handle like objects.
21
23 Coercions resulting in IO objects
24 These are available using the ":io_from" export group.
25 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 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 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 Globs are returned as is only if they have a valid "IO" slot.
39 io_from_object $obj
41 Depending on the class of $obj either returns or coerces the
42 object.
43 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 Objects that are coerced currently only include Path::Class::File,
49 which will have the "openr" method invoked on it.
50 Anything else is an error.
52 io_from_string $str
54 Instantiates an IO::String object using $str as the buffer.
55 Note that $str is not passed as an alias, so writing to the IO
57 object will not modify string. For that see
58 "io_from_scalar_ref".
59 io_from_array \@array
61 Creates an IO::Handle::Iterator that will return the elements
62 of @array one by one.
63 Note that a copy of @array is made.
65 In order to be able to append more elements to the array or
67 remove the ones that have been returned use
68 IO::Handle::Iterator yourself directly.
69 io_from_scalar_ref \$str
71 Creates an IO::String object using $str as the buffer.
72 Writing to the IO object will modify $str.
74 io_from_thunk sub { ... }
76 Invokes the callback once in list context the first time it's
77 needed, and then returns each element of the list like
78 "io_from_array" would.
79 io_from_getline sub { ... }
81 Creates an IO::Handle::Iterator object using the callback.
82 io_from_write_cb sub { ... }
84 Creates an IO::Handle::Prototype::Fallback using the callback.
85 The callback will always be invoked with one string argument
87 and with the values of $, and "$\" localized to "undef".
88 Coercions utilizing IO objects
90 These coercions will actually call "io_from_any" on their argument
91 first. This allows you to do things like:
92 my $str = '';
94 my $sub = io_to_write_cb(\$str);
95 $sub->("foo");
97 These are available using the ":io_to" export group.
99 io_to_write_cb $thing
101 Creates a code ref that will invoke "print" on the handle with the
102 arguments to the callback.
103 $, and "$\" will both be localized to "undef".
105 io_to_read_cb $thing
107 Creates a code ref that will invoke "getline" on the handle.
108 $/ will not be localized and should probably be set to a reference
110 to a number if you want efficient iteration. See perlvar for
111 details.
112 io_to_string $thing
114 Slurps a string out of the IO object by reading all the data.
115 If a string was passed it is returned as is.
117 io_to_array $thing
119 Returns an array reference containing all the lines of the IO
120 object.
121 If an array reference was passed it is returned as is.
123 io_to_list $thing
125 Returns the list of lines from the IO object.
126 Warns if not invoked in list context.
128 If an array reference was passed it is dereferenced an its elements
130 are returned.
131 io_to_glob $thing
133 If the filehandle is an unblessed glob returns it as is, otherwise
134 returns a new glob which is tied to delegate to the OO interface.
135 This lets you use most of the builtins without the method syntax:
137 my $fh = io_to_glob($some_kind_of_OO_handle);
139 while ( defined( my $line = <$fh> ) ) {
141 ...
142 }
143 Misc functions
145 io_prototype %callbacks
146 Given a key-value pair list of named callbacks, constructs an
147 IO::Handle::Prototype::Fallback object with those callbacks.
148 For example:
150 my $io = io_prototype print => sub {
152 my $self = shift;
153 no warnings 'uninitialized';
155 $string .= join($,, @_) . $\;
156 };
157 $io->say("Hello"); # $string now has "Hello\n"
159 See IO::Handle::Prototype::Fallback for more details.
161 is_real_fh $io
163 Returns true if the IO handle probably could be passed to something
164 like AnyEvent::Handle which would break encapsulation.
165 Checks for the following conditions:
167 · The handle has a reftype of either a "GLOB" with an "IO" slot,
169 or is an "IO" itself.
170 · The handle's "fileno" method returns a positive number,
172 corresponding to a filedescriptor.
173 · The "fileno" builtin returns the same thing as "fileno" invoked
175 as a method.
176 If these conditions hold the handle is probably OK to work with
178 using the IO builtins directly, or passing the filedesctiptor to C
179 land, instead of by invoking methods on it.
180
182 IO::Handle, FileHandle, IO::String, perlio, "open" in perlfunc
183
185 http://github.com/nothingmuch/io-handle-util
186 <http://github.com/nothingmuch/io-handle-util>
187
189 Yuval Kogman
190
192 Copyright (c) 2009 Yuval Kogman. All rights reserved
193 This program is free software; you can redistribute
194 it and/or modify it under the same terms as Perl itself.
195
197 Hey! The above document had some coding errors, which are explained
198 below:
199 Around line 425:
201 You forgot a '=back' before '=head2'
202perl v5.12.1 2009-10-01 IO::Handle::Util(3)