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