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
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.