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