SYNOPSIS
      use CGI::Application::Plugin::Stream 'stream';

      sub runmode {
        # ...

        # Set up any headers you want to set explicitly
        # using header_props() or header_add() as usual

        #...

        return $self->stream($file);
      }

DESCRIPTION
    This plugin provides a way to stream a file back to the user.

    This is useful if you are creating a PDF or Spreadsheet document
    dynamically to deliver to the user.

    The file is read and printed in small chunks to keep memory consumption
    down.

    The "stream()" method should be run as the last call in a a run mode,
    and affects the HTTP response headers. If you pass along a filehandle,
    we'll make sure to close it for you.

METHODS
  stream()
      $self->stream($fh);
      $self->stream( '/path/to/file',2048);

    This method can take two parameters, the first the path to the file or a
    filehandle and the second, an optional number of bytes to determine the
    chunk size of the stream. It defaults to 1024.

    It will either stream a file to the user or die if it fails, perhaps
    because it couldn't find the file you referenced.

    We highly recommend you provide a file name if passing along a
    filehandle, as we won't be able to deduce the file name, and will use
    'FILE' by default. Example:

     $self->header_add( -attachment => 'my_file.txt' );

    With both a file handle or file name, we will try to determine the
    correct content type by using File::MMagic. A default of
    'application/octet-stream' will be used if File::MMagic can't figure it
    out.

    The size will be calculated and added to the headers as well.

    Again, you can set these explicitly if you want as well:

     $self->header_add(
          -type                     =>      'text/plain',
          -Content_Length   =>      42, # bytes
     );

  stream_file()  ( deprecated )
    This works the same as stream(), but returns false to indicate a
    problem.

    This is included because this was the original API. It does not give you
    access to "$@" if there is a problem.

AUTHOR
    Jason Purdy, <Jason@Purdy.INFO>, with inspiration from Tobias Henoeckl
    and tremendous support from the cgiapp mailing list.

    Mark Stosberg also contributed to this module.

SEE ALSO
    CGI::Application, <http://www.cgi-app.org>, "CREATING A STANDARD HTTP
    HEADER" in CGI.pm,
    <http://www.mail-archive.com/cgiapp@lists.erlbaum.net/msg02660.html>,
    File::Basename, "$|" in perlvar

LICENSE
    Copyright (C) 2004-2005 Jason Purdy, <Jason@Purdy.INFO>

    This library is free software. You can modify and or distribute it under
    the same terms as Perl itself.

