avoid ignoring the result of i_io_getc()
[imager.git] / lib / Imager / IO.pod
CommitLineData
1f6c1c10
TC
1=head1 NAME
2
3Imager::IO - Imager's io_layer object.
4
5=head1 SYNOPSIS
6
7 # Imager supplies Imager::IO objects to various callbacks
8 my $IO = ...;
9
10 my $count = $IO->write($data);
11 my $count = $IO->read($buffer, $max_count);
12 my $position = $IO->seek($offset, $whence);
13 my $status = $IO->close;
14
15=head1 DESCRIPTION
16
17Imager uses an abstraction when dealing with image files to allow the
18same code to work with disk files, in memory data and callbacks.
19
20If you're writing an Imager file handler your code will be passed an
21Imager::IO object to write to or read from.
22
6d5c85a2
TC
23X<UTF-8>X<Unicode>Note that Imager::IO can only work with collections of bytes -
24if you need to read UTF-8 data you will need to read the bytes and
25decode them. If you want to write UTF-8 data you will need to encode
26your characters to bytes and write the bytes.
27
28=head1 CONSTRUCTORS
29
30=over
31
32=item new_fd($fd)
33
34Create a new I/O layer based on a file descriptor.
35
36 my $io = Imager::IO->new(fileno($fh));
37
38=item new_buffer($data)
39
40Create a new I/O layer based on a memory buffer.
41
6d5c85a2
TC
42Buffer I/O layers are read only.
43
83e58721 44C<$data> can either a simple octet string, or a reference to an octet
b08d7b0d
TC
45string. If C<$data> contains characters with a code point above
46C<0xFF> an exception will be thrown.
83e58721 47
6d5c85a2
TC
48=item new_cb($writecb, $readcb, $seekcb, $closecb)
49
50Create a new I/O layer based on callbacks. See
51L<Imager::Files/"I/O Callbacks"> for details on the behavior of
52the callbacks.
53
52d990d6
TC
54=item new_fh($fh)
55
56Create a new I/O layer based on a perl file handle.
57
6d5c85a2
TC
58=item new_bufchain()
59
60Create a new C<bufchain> based I/O layer. This accumulates the file
61data as a chain of buffers starting from an empty stream.
62
63Use the L</slurp()> method to retrieve the accumulated content into a
64perl string.
65
66=back
67
68=head1 BUFFERED I/O METHODS
69
70These methods use buffered I/O to improve performance unless you call
71set_buffered() to disable buffering.
72
73Prior to Imager 0.86 the write and read methods performed raw I/O.
1f6c1c10
TC
74
75=over
76
6d5c85a2 77=item write($data)
1f6c1c10
TC
78
79Call to write to the file. Returns the number of bytes written. The
80data provided may contain only characters \x00 to \xFF - characters
81outside this range will cause this method to croak().
82
83If you supply a UTF-8 flagged string it will be converted to a byte
84string, which may have a performance impact.
85
86Returns -1 on error, though in most cases if the result of the write
87isn't the number of bytes supplied you'll want to treat it as an error
88anyway.
89
6d5c85a2 90=item read($buffer, $size)
1f6c1c10
TC
91
92 my $buffer;
93 my $count = $io->read($buffer, $max_bytes);
94
95Reads up to I<$max_bytes> bytes from the current position in the file
96and stores them in I<$buffer>. Returns the number of bytes read on
97success or an empty list on failure. Note that a read of zero bytes
98is B<not> a failure, this indicates end of file.
99
6d5c85a2 100=item read2($size)
1f6c1c10
TC
101
102 my $buffer = $io->read2($max_bytes);
103
104An alternative interface to read, that might be simpler to use in some
105cases.
106
6d5c85a2
TC
107Returns the data read or an empty list. At end of file the data read
108will be an empty string.
1f6c1c10 109
6d5c85a2 110=item seek($offset, $whence)
1f6c1c10
TC
111
112 my $new_position = $io->seek($offset, $whence);
113
114Seek to a new position in the file. Possible values for I<$whence> are:
115
116=over
117
118=item *
119
120C<SEEK_SET> - I<$offset> is the new position in the file.
121
122=item *
123
124C<SEEK_CUR> - I<$offset> is the offset from the current position in
125the file.
126
127=item *
128
129C<SEEK_END> - I<$offset> is the offset relative to the end of the
130file.
131
132=back
133
134Note that seeking past the end of the file may or may not result in an
135error.
136
6d5c85a2
TC
137Any buffered output will be flushed, if flushing fails, seek() will
138return -1.
139
1f6c1c10
TC
140Returns the new position in the file, or -1 on error.
141
6d5c85a2
TC
142=item getc()
143
144Return the next byte from the stream.
145
146Returns the ordinal of the byte or -1 on error or end of file.
147
148 while ((my $c = $io->getc) != -1) {
149 print chr($c);
150 }
151
215d9ead
TC
152=item nextc()
153
154Discard the next byte from the stream.
155
156Returns nothing.
157
6d5c85a2
TC
158=item gets()
159
160=item gets($max_size)
161
162=item gets($max_size, $end_of_line)
163
164Returns the next line of input from the stream, as terminated by
165C<end_of_line>.
166
167The default C<max_size> is 8192.
168
169The default C<end_of_line> is C<ord "\n">.
170
171Returns nothing if the stream is in error or at end of file.
172
173Returns the line as a string, including the line terminator (if one
174was found) on success.
175
176 while (defined(my $line = $io->gets)) {
177 # do something with $line
178 }
179
180=item peekc()
181
182Return the buffered next character from the stream, loading the buffer
183if necessary.
184
185For an unbuffered stream a buffer will be setup and loaded with a
186single character.
187
188Returns the ordinal of the byte or -1 on error or end of file.
189
190 my $c = $io->peekc;
191
192=item peekn($size)
193
194Returns up to the next C<size> bytes from the file as a string.
195
196Only up to the stream buffer size bytes (currently 8192) can be peeked.
197
198This method ignores the buffering state of the stream.
199
200Returns nothing on EOF.
201
202 my $s = $io->peekn(4);
203 if ($s =~ /^(II|MM)\*\0/) {
204 print "TIFF image";
205 }
206
207=item putc($code)
208
209Write a single character to the stream.
210
211Returns C<code> on success, or -1 on failure.
212
213=item close()
1f6c1c10
TC
214
215 my $result = $io->close;
216
6d5c85a2
TC
217Call when you're done with the file. If the IO object is connected to
218a file this won't close the file handle, but buffers may be flushed
219(if any).
220
221Returns 0 on success, -1 on failure.
222
223=item eof()
224
225 $io->eof
226
227Test if the stream is at end of file. No further read requests will
228be passed to your read callback until you seek().
229
230=item error()
231
232Test if the stream has encountered a read or write error.
233
234 my $data = $io->read2(100);
235 $io->error
236 and die "Failed";
237
238When the stream has the error flag set no further read or write
239requests will be passed to your callbacks until you seek.
240
241=item flush()
242
243 $io->flush
244 or die "Flush error";
245
246Flush any buffered output. This will not call lower write layers when
247the stream has it's error flag set.
248
249Returns a true value on success.
250
251=item is_buffered()
252
253Test if buffering is enabled for this stream.
254
255Returns a true value if the stream is buffered.
256
257=item set_buffered($enabled)
258
259If C<$enabled> is a non-zero integer, enable buffering, other disable
260it.
261
262Disabling buffering will flush any buffered output, but any buffered
263input will be retained and consumed by input methods.
264
265Returns true if any buffered output was flushed successfully, false if
266there was an error flushing output.
267
268=back
269
270=head1 RAW I/O METHODS
271
272These call the underlying I/O abstraction directly.
273
274=over
275
276=item raw_write()
277
278Call to write to the file. Returns the number of bytes written. The
279data provided may contain only characters \x00 to \xFF - characters
280outside this range will cause this method to croak().
281
282If you supply a UTF-8 flagged string it will be converted to a byte
283string, which may have a performance impact.
284
285Returns -1 on error, though in most cases if the result of the write
286isn't the number of bytes supplied you'll want to treat it as an error
287anyway.
288
289=item raw_read()
290
291 my $buffer;
292 my $count = $io->raw_read($buffer, $max_bytes);
293
294Reads up to I<$max_bytes> bytes from the current position in the file
295and stores them in I<$buffer>. Returns the number of bytes read on
296success or an empty list on failure. Note that a read of zero bytes
297is B<not> a failure, this indicates end of file.
298
299=item raw_read2()
300
301 my $buffer = $io->raw_read2($max_bytes);
302
303An alternative interface to raw_read, that might be simpler to use in some
304cases.
305
306Returns the data read or an empty list.
307
308=item raw_seek()
309
310 my $new_position = $io->raw_seek($offset, $whence);
311
312Seek to a new position in the file. Possible values for I<$whence> are:
313
314=over
315
316=item *
317
318C<SEEK_SET> - I<$offset> is the new position in the file.
319
320=item *
321
322C<SEEK_CUR> - I<$offset> is the offset from the current position in
323the file.
324
325=item *
326
327C<SEEK_END> - I<$offset> is the offset relative to the end of the
328file.
329
330=back
331
332Note that seeking past the end of the file may or may not result in an
333error.
334
335Returns the new position in the file, or -1 on error.
336
337=item raw_close()
338
339 my $result = $io->raw_close;
340
341Call when you're done with the file. If the IO object is connected to
342a file this won't close the file handle.
1f6c1c10
TC
343
344Returns 0 on success, -1 on failure.
345
346=back
347
6d5c85a2
TC
348=head1 UTILITY METHODS
349
350=over
351
352=item slurp()
353
354Retrieve the data accumulated from an I/O layer object created with
355the new_bufchain() method.
356
357 my $data = $io->slurp;
358
359=item dump()
360
361Dump the internal buffering state of the I/O object to C<stderr>.
362
363 $io->dump();
364
365=back
366
1f6c1c10
TC
367=head1 AUTHOR
368
5b480b14 369Tony Cook <tonyc@cpan.org>
1f6c1c10
TC
370
371=head1 SEE ALSO
372
373Imager, Imager::Files
374
375=cut
376