If you're writing an Imager file handler your code will be passed an
Imager::IO object to write to or read from.
-=head1 METHODS
+X<UTF-8>X<Unicode>Note that Imager::IO can only work with collections of bytes -
+if you need to read UTF-8 data you will need to read the bytes and
+decode them. If you want to write UTF-8 data you will need to encode
+your characters to bytes and write the bytes.
+
+=head1 CONSTRUCTORS
+
+=over
+
+=item new_fd($fd)
+
+Create a new I/O layer based on a file descriptor.
+
+ my $io = Imager::IO->new(fileno($fh));
+
+=item new_buffer($data)
+
+Create a new I/O layer based on a memory buffer.
+
+The supplied variable must not be changed on the the life of the I/O
+object.
+
+Buffer I/O layers are read only.
+
+=item new_cb($writecb, $readcb, $seekcb, $closecb)
+
+Create a new I/O layer based on callbacks. See
+L<Imager::Files/"I/O Callbacks"> for details on the behavior of
+the callbacks.
+
+=item new_bufchain()
+
+Create a new C<bufchain> based I/O layer. This accumulates the file
+data as a chain of buffers starting from an empty stream.
+
+Use the L</slurp()> method to retrieve the accumulated content into a
+perl string.
+
+=back
+
+=head1 BUFFERED I/O METHODS
+
+These methods use buffered I/O to improve performance unless you call
+set_buffered() to disable buffering.
+
+Prior to Imager 0.86 the write and read methods performed raw I/O.
=over
-=item write
+=item write($data)
Call to write to the file. Returns the number of bytes written. The
data provided may contain only characters \x00 to \xFF - characters
isn't the number of bytes supplied you'll want to treat it as an error
anyway.
-=item read
+=item read($buffer, $size)
my $buffer;
my $count = $io->read($buffer, $max_bytes);
success or an empty list on failure. Note that a read of zero bytes
is B<not> a failure, this indicates end of file.
-=item read2
+=item read2($size)
my $buffer = $io->read2($max_bytes);
An alternative interface to read, that might be simpler to use in some
cases.
-Returns the data read or an empty list.
+Returns the data read or an empty list. At end of file the data read
+will be an empty string.
-=item seek
+=item seek($offset, $whence)
my $new_position = $io->seek($offset, $whence);
Note that seeking past the end of the file may or may not result in an
error.
+Any buffered output will be flushed, if flushing fails, seek() will
+return -1.
+
Returns the new position in the file, or -1 on error.
-=item close
+=item getc()
+
+Return the next byte from the stream.
+
+Returns the ordinal of the byte or -1 on error or end of file.
+
+ while ((my $c = $io->getc) != -1) {
+ print chr($c);
+ }
+
+=item gets()
+
+=item gets($max_size)
+
+=item gets($max_size, $end_of_line)
+
+Returns the next line of input from the stream, as terminated by
+C<end_of_line>.
+
+The default C<max_size> is 8192.
+
+The default C<end_of_line> is C<ord "\n">.
+
+Returns nothing if the stream is in error or at end of file.
+
+Returns the line as a string, including the line terminator (if one
+was found) on success.
+
+ while (defined(my $line = $io->gets)) {
+ # do something with $line
+ }
+
+=item peekc()
+
+Return the buffered next character from the stream, loading the buffer
+if necessary.
+
+For an unbuffered stream a buffer will be setup and loaded with a
+single character.
+
+Returns the ordinal of the byte or -1 on error or end of file.
+
+ my $c = $io->peekc;
+
+=item peekn($size)
+
+Returns up to the next C<size> bytes from the file as a string.
+
+Only up to the stream buffer size bytes (currently 8192) can be peeked.
+
+This method ignores the buffering state of the stream.
+
+Returns nothing on EOF.
+
+ my $s = $io->peekn(4);
+ if ($s =~ /^(II|MM)\*\0/) {
+ print "TIFF image";
+ }
+
+=item putc($code)
+
+Write a single character to the stream.
+
+Returns C<code> on success, or -1 on failure.
+
+=item close()
my $result = $io->close;
-Call when you're with the file. If the IO object is connected to a
-file this won't close the file handle, but buffers may be flushed (if
-any).
+Call when you're done with the file. If the IO object is connected to
+a file this won't close the file handle, but buffers may be flushed
+(if any).
+
+Returns 0 on success, -1 on failure.
+
+=item eof()
+
+ $io->eof
+
+Test if the stream is at end of file. No further read requests will
+be passed to your read callback until you seek().
+
+=item error()
+
+Test if the stream has encountered a read or write error.
+
+ my $data = $io->read2(100);
+ $io->error
+ and die "Failed";
+
+When the stream has the error flag set no further read or write
+requests will be passed to your callbacks until you seek.
+
+=item flush()
+
+ $io->flush
+ or die "Flush error";
+
+Flush any buffered output. This will not call lower write layers when
+the stream has it's error flag set.
+
+Returns a true value on success.
+
+=item is_buffered()
+
+Test if buffering is enabled for this stream.
+
+Returns a true value if the stream is buffered.
+
+=item set_buffered($enabled)
+
+If C<$enabled> is a non-zero integer, enable buffering, other disable
+it.
+
+Disabling buffering will flush any buffered output, but any buffered
+input will be retained and consumed by input methods.
+
+Returns true if any buffered output was flushed successfully, false if
+there was an error flushing output.
+
+=back
+
+=head1 RAW I/O METHODS
+
+These call the underlying I/O abstraction directly.
+
+=over
+
+=item raw_write()
+
+Call to write to the file. Returns the number of bytes written. The
+data provided may contain only characters \x00 to \xFF - characters
+outside this range will cause this method to croak().
+
+If you supply a UTF-8 flagged string it will be converted to a byte
+string, which may have a performance impact.
+
+Returns -1 on error, though in most cases if the result of the write
+isn't the number of bytes supplied you'll want to treat it as an error
+anyway.
+
+=item raw_read()
+
+ my $buffer;
+ my $count = $io->raw_read($buffer, $max_bytes);
+
+Reads up to I<$max_bytes> bytes from the current position in the file
+and stores them in I<$buffer>. Returns the number of bytes read on
+success or an empty list on failure. Note that a read of zero bytes
+is B<not> a failure, this indicates end of file.
+
+=item raw_read2()
+
+ my $buffer = $io->raw_read2($max_bytes);
+
+An alternative interface to raw_read, that might be simpler to use in some
+cases.
+
+Returns the data read or an empty list.
+
+=item raw_seek()
+
+ my $new_position = $io->raw_seek($offset, $whence);
+
+Seek to a new position in the file. Possible values for I<$whence> are:
+
+=over
+
+=item *
+
+C<SEEK_SET> - I<$offset> is the new position in the file.
+
+=item *
+
+C<SEEK_CUR> - I<$offset> is the offset from the current position in
+the file.
+
+=item *
+
+C<SEEK_END> - I<$offset> is the offset relative to the end of the
+file.
+
+=back
+
+Note that seeking past the end of the file may or may not result in an
+error.
+
+Returns the new position in the file, or -1 on error.
+
+=item raw_close()
+
+ my $result = $io->raw_close;
+
+Call when you're done with the file. If the IO object is connected to
+a file this won't close the file handle.
Returns 0 on success, -1 on failure.
=back
+=head1 UTILITY METHODS
+
+=over
+
+=item slurp()
+
+Retrieve the data accumulated from an I/O layer object created with
+the new_bufchain() method.
+
+ my $data = $io->slurp;
+
+=item dump()
+
+Dump the internal buffering state of the I/O object to C<stderr>.
+
+ $io->dump();
+
+=back
+
=head1 AUTHOR
-Tony Cook <tony@imager.perl.org>
+Tony Cook <tonyc@cpan.org>
=head1 SEE ALSO
projects / imager.git / blobdiff