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