NAME

Plack::Middleware::AdaptFilehandleRead::Proxy - Wrap an object to supply missing getline

SYNOPSIS

    my $new_fh = Plack::Middleware::AdaptFilehandleRead::Proxy->new($old_fh);
    my $line = $new_fh->getline;
 

DESCRIPTION

Wraps a filehandle like object that has a read method and provides a getline method that works as in IO::Filehandle All other method calls will be delegated to the original object.

This is used primarily to adapt a filehandle like object that does read but not getline so that you can use it as the body value for a PSGI response. For example, MogileFS::Client can return such a custom filehandle like object and you may wish to use that response to stream via a PSGI application.

When adapting read to getline we examine the state of $/ in order to figure out what to do. For the normal case, if $/ is a simple value (such as /n or newline, which is the default) we call read and ask for chunks of 65536 bytes. This may or may not be ideal for your data, in which case you may wish to override it as so:

  my $new_fh = Plack::Middleware::AdaptFilehandleRead::Proxy
    ->new($old_fh, $chunksize);

Please be aware that the chunksize is read into memory.

We then examine the chunk and return records as indicated by the deliminator. When the chunk does not have such a match, we read chunks until it does or we read the entire file.

For the case when $/ is a scalar ref, such as $/ = \'4096' we will instead read fixed sized chunks from ->read and ignore any chunksize settings (you can always localize $/ yourself if you prefer more control).

Typically plack prefers getline to return chunks of a predefined length and all the common plack handers such as Starman, Twiggy set $/ when calling getline although as the PSGI specification indicates this support of "$/" is considered optional for a custom filehandle like body. We choose to support it since it can help avoid a situation where your entire file gets read into memory when the file does not contain newlines (or whatever $/ is set to).

Currently this object delegates all method calls beyond getline to the underlying proxied object via AUTOLOAD. We do not attempt to proxy any overloading (patches for this welcomed).

METHODS

This class defines the following methods

getline

returns a line from the file, as described by IO::Filehandle, suitable for the PSGI requirement of a filehandle like object. It work by calling read in chunks, and returns lines.

AUTOLOAD

Used to delegate all other method calls to the underlying wrapped instance.

SEE ALSO

Plack, Plack::Middleware.

AUTHOR

John Napiorkowski email:jjnapiork@cpan.org

COPYRIGHT & LICENSE

Copyright 2014, John Napiorkowski email:jjnapiork@cpan.org

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