1d0501e20a3c91fe56022720383f05af1540f67c
[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 gets()
153
154 =item gets($max_size)
155
156 =item gets($max_size, $end_of_line)
157
158 Returns the next line of input from the stream, as terminated by
159 C<end_of_line>.
160
161 The default C<max_size> is 8192.
162
163 The default C<end_of_line> is C<ord "\n">.
164
165 Returns nothing if the stream is in error or at end of file.
166
167 Returns the line as a string, including the line terminator (if one
168 was found) on success.
169
170   while (defined(my $line = $io->gets)) {
171     # do something with $line
172   }
173
174 =item peekc()
175
176 Return the buffered next character from the stream, loading the buffer
177 if necessary.
178
179 For an unbuffered stream a buffer will be setup and loaded with a
180 single character.
181
182 Returns the ordinal of the byte or -1 on error or end of file.
183
184   my $c = $io->peekc;
185
186 =item peekn($size)
187
188 Returns up to the next C<size> bytes from the file as a string.
189
190 Only up to the stream buffer size bytes (currently 8192) can be peeked.
191
192 This method ignores the buffering state of the stream.
193
194 Returns nothing on EOF.
195
196   my $s = $io->peekn(4);
197   if ($s =~ /^(II|MM)\*\0/) {
198     print "TIFF image";
199   }
200
201 =item putc($code)
202
203 Write a single character to the stream.
204
205 Returns C<code> on success, or -1 on failure.
206
207 =item close()
208
209   my $result = $io->close;
210
211 Call when you're done with the file.  If the IO object is connected to
212 a file this won't close the file handle, but buffers may be flushed
213 (if any).
214
215 Returns 0 on success, -1 on failure.
216
217 =item eof()
218
219   $io->eof
220
221 Test if the stream is at end of file.  No further read requests will
222 be passed to your read callback until you seek().
223
224 =item error()
225
226 Test if the stream has encountered a read or write error.
227
228   my $data = $io->read2(100);
229   $io->error
230      and die "Failed";
231
232 When the stream has the error flag set no further read or write
233 requests will be passed to your callbacks until you seek.
234
235 =item flush()
236
237   $io->flush
238     or die "Flush error";
239
240 Flush any buffered output.  This will not call lower write layers when
241 the stream has it's error flag set.
242
243 Returns a true value on success.
244
245 =item is_buffered()
246
247 Test if buffering is enabled for this stream.
248
249 Returns a true value if the stream is buffered.
250
251 =item set_buffered($enabled)
252
253 If C<$enabled> is a non-zero integer, enable buffering, other disable
254 it.
255
256 Disabling buffering will flush any buffered output, but any buffered
257 input will be retained and consumed by input methods.
258
259 Returns true if any buffered output was flushed successfully, false if
260 there was an error flushing output.
261
262 =back
263
264 =head1 RAW I/O METHODS
265
266 These call the underlying I/O abstraction directly.
267
268 =over
269
270 =item raw_write()
271
272 Call to write to the file.  Returns the number of bytes written.  The
273 data provided may contain only characters \x00 to \xFF - characters
274 outside this range will cause this method to croak().
275
276 If you supply a UTF-8 flagged string it will be converted to a byte
277 string, which may have a performance impact.
278
279 Returns -1 on error, though in most cases if the result of the write
280 isn't the number of bytes supplied you'll want to treat it as an error
281 anyway.
282
283 =item raw_read()
284
285   my $buffer;
286   my $count = $io->raw_read($buffer, $max_bytes);
287
288 Reads up to I<$max_bytes> bytes from the current position in the file
289 and stores them in I<$buffer>.  Returns the number of bytes read on
290 success or an empty list on failure.  Note that a read of zero bytes
291 is B<not> a failure, this indicates end of file.
292
293 =item raw_read2()
294
295   my $buffer = $io->raw_read2($max_bytes);
296
297 An alternative interface to raw_read, that might be simpler to use in some
298 cases.
299
300 Returns the data read or an empty list.
301
302 =item raw_seek()
303
304   my $new_position = $io->raw_seek($offset, $whence);
305
306 Seek to a new position in the file.  Possible values for I<$whence> are:
307
308 =over
309
310 =item *
311
312 C<SEEK_SET> - I<$offset> is the new position in the file.
313
314 =item *
315
316 C<SEEK_CUR> - I<$offset> is the offset from the current position in
317 the file.
318
319 =item *
320
321 C<SEEK_END> - I<$offset> is the offset relative to the end of the
322 file.
323
324 =back
325
326 Note that seeking past the end of the file may or may not result in an
327 error.
328
329 Returns the new position in the file, or -1 on error.
330
331 =item raw_close()
332
333   my $result = $io->raw_close;
334
335 Call when you're done with the file.  If the IO object is connected to
336 a file this won't close the file handle.
337
338 Returns 0 on success, -1 on failure.
339
340 =back
341
342 =head1 UTILITY METHODS
343
344 =over
345
346 =item slurp()
347
348 Retrieve the data accumulated from an I/O layer object created with
349 the new_bufchain() method.
350
351   my $data = $io->slurp;
352
353 =item dump()
354
355 Dump the internal buffering state of the I/O object to C<stderr>.
356
357   $io->dump();
358
359 =back
360
361 =head1 AUTHOR
362
363 Tony Cook <tonyc@cpan.org>
364
365 =head1 SEE ALSO
366
367 Imager, Imager::Files
368
369 =cut
370