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