@node MIME/IO, MIME/Latin1, MIME/Head, Module List
@unnumbered a small package for turning things into IO handles


@unnumberedsec NAME

MIME::IO - a small package for turning things into IO handles

@unnumberedsec DESCRIPTION

As of MIME-tools 2.0, input and output routines cannot just assume that 
they are dealing with filehandles.  In an effort to come up with a nice,
OO way of encapsulating input/output streams, I decided to use a minimal
subset of Graham Barr@'s @strong{IO::Handle} interface (which is itself derived
from the FileHandle interface).

Therefore, all that MIME::Body, MIME::Decoder, and the other classes
require (and, thus, all that they can assume) is that they are manipulating
an object which responds to the following small, well-defined set of 
messages:

@table @asis
@item close
@emph{Instance method.}
This should close the input/output stream.

@item getline
@emph{Instance method.}
This should get a single line from the input stream, and return it
(or undef on end of file).  The returned line should end
with the newline (unless, of course, this is the last line of a
file which is not terminated by a newline).  

@item getlines
@emph{Instance method.}
This should get the entire input stream as an array of lines,
which each line is terminated by the @code{"\n"} (except, maybe,
the last one).

@item print ARGS...
@emph{Instance method.}
This should output the ARGS to the stream.

@item read BUFFER,NBYTES
@emph{Instance method.}
This should get NBYTES from the input stream, placing them in BUFFER.
It should return the number of bytes actually read, undef on error,
and 0 on end of file.

@end table
@emph{Thanks to Achim Bohnet for suggesting this more-generic I/O model.}

@unnumberedsec BUILT-IN SUBCLASSES

@unnumberedsubsec MIME::IO::Handle

@table @asis
@item DESCRIPTION
An I/O interface object wrapped around a raw filehandle.
If you hand this class@' @code{wrap()} constructor an argument, it is 
expected to be one of the following:

@itemize @bullet
@item 
@strong{A raw scalar filehandle name,} like @code{"STDOUT"} or @code{"Class::HANDLE"}.
In this case, the filehandle name is wrapped in a MIME::IO object, 
which is returned.

@item 
@strong{A raw filehandle glob,} like @code{\*STDOUT}.
In this case, the filehandle glob is wrapped in a MIME::IO object, 
which is returned.

@item 
@strong{A blessed FileHandle object.}
In this case, the FileHandle is wrapped in a MIME::IO object if and only
if your FileHandle class does not support the @code{read()} method.

@item 
@strong{Any other kind of blessed object,} which is assumed to be already
conformant to the I/O object interface.
In this case, you just get back that object.

@end itemize
Like this:

@example
my $IO = wrap MIME::IO::Handle \*STDOUT;
@end example

@strong{All this class does} is to provide a simple means for the MIME::
classes to wrap raw filehandles inside a class which responds to 
the above messages (by passing the messages on to the actual filehandle
in the form of the standard function calls).

The bottom line: what you get back is an object which is guaranteed 
to support the methods defined above.

This interface is used by many of the MIME-tool classes, for backwards 
compatibility with earlier versions of MIME-parser: if you supply a 
raw filehandle where an INSTREAM or OUTSTREAM is expected, most MIME
packages will automatically wrap that raw filehandle in a MIME::IO 
object, which fits the I/O handle criteria.

@item NOTES
Clearly, when wrapping a raw external filehandle (like \*STDOUT), 
I didn@'t want to close the file descriptor when this object is
destructed... since the user might not appreciate that.  Hence,
there@'s no DESTROY method in this class.

When wrapping a FileHandle object, however, I believe that Perl will 
invoke the FileHandle::DESTROY when the last reference goes away,
so in that case, the filehandle is closed if the wrapped FileHandle
really was the last reference to it.

@end table
@unnumberedsubsec MIME::IO::Scalar

@table @asis
@item DESCRIPTION
An I/O interface object wrapped around a scalar.  
This is to implement things that look like filehandles, but
which keep all of their data in-core.

Use it like this:

@example
$IO = new MIME::IO::Scalar \$scalar;
$IO->print("Some data\n");
$IO->print("Some more data\n");
$IO->close;    # ...$scalar now holds "Some data\nSome more data\n"
@end example

@end table
@unnumberedsec NOTES

I know, I know: three-level-nesting of packages is evil when
those packages are not "private".  Sure, I could have made
this two modules, @code{MIME::IOHandle} and @code{MIME::IOScalar}...
but it just seemed more sensible to mimic the IO:: hierarchy,
one level down (under MIME::).

@unnumberedsec AUTHOR

Copyright (c) 1996 by Eryq / eryq@@rhine.gsfc.nasa.gov

All rights reserved.  This program is free software; you can redistribute 
it and/or modify it under the same terms as Perl itself.

@unnumberedsec VERSION

$Revision: 1.5 $ $Date: 1996/10/28 18:47:29 $

