Plack::Util(3) User Contributed Perl Documentation Plack::Util(3)NAMEPlack::Util - Utility subroutines for Plack server and framework
developers
FUNCTIONS
TRUE, FALSE
my $true = Plack::Util::TRUE;
my $false = Plack::Util::FALSE;
Utility constants to include when you specify boolean variables in
$env hash (e.g. "psgi.multithread").
load_class
my $class = Plack::Util::load_class($class [, $prefix ]);
Constructs a class name and "require" the class. Throws an
exception if the .pm file for the class is not found, just with the
built-in "require".
If $prefix is set, the class name is prepended to the $class unless
$class begins with "+" sign, which means the class name is already
fully qualified.
my $class = Plack::Util::load_class("Foo"); # Foo
my $class = Plack::Util::load_class("Baz", "Foo::Bar"); # Foo::Bar::Baz
my $class = Plack::Util::load_class("+XYZ::ZZZ", "Foo::Bar"); # XYZ::ZZZ
Note that this function doesn't validate (or "sanitize") the passed
string, hence if you pass a user input to this function (which is
an insecure thing to do in the first place) it might lead to
unexpected behavior of loading files outside your @INC path. If you
want a generic module loading function, you should check out CPAN
modules such as Module::Runtime.
is_real_fh
if ( Plack::Util::is_real_fh($fh) ) { }
returns true if a given $fh is a real file handle that has a file
descriptor. It returns false if $fh is PerlIO handle that is not
really related to the underlying file etc.
content_length
my $cl = Plack::Util::content_length($body);
Returns the length of content from body if it can be calculated. If
$body is an array ref it's a sum of length of each chunk, if $body
is a real filehandle it's a remaining size of the filehandle,
otherwise returns undef.
set_io_path
Plack::Util::set_io_path($fh, "/path/to/foobar.txt");
Sets the (absolute) file path to $fh filehandle object, so you can
call "$fh->path" on it. As a side effect $fh is blessed to an
internal package but it can still be treated as a normal file
handle.
This module doesn't normalize or absolutize the given path, and is
intended to be used from Server or Middleware implementations. See
also IO::File::WithPath.
foreach
Plack::Util::foreach($body, $cb);
Iterate through $body which is an array reference or
IO::Handle-like object and pass each line (which is NOT really
guaranteed to be a line) to the callback function.
It internally sets the buffer length $/ to 65536 in case it reads
the binary file, unless otherwise set in the caller's code.
load_psgi
my $app = Plack::Util::load_psgi $psgi_file_or_class;
Load "app.psgi" file or a class name (like "MyApp::PSGI") and
require the file to get PSGI application handler. If the file can't
be loaded (e.g. file doesn't exist or has a perl syntax error), it
will throw an exception.
Security: If you give this function a class name or module name
that is loadable from your system, it will load the module. This
could lead to a security hole:
my $psgi = ...; # user-input: consider "Moose.pm"
$app = Plack::Util::load_psgi($psgi); # this does 'require "Moose.pm"'!
Generally speaking, passing an external input to this function is
considered very insecure. But if you really want to do that, be
sure to validate the argument passed to this function. Also, if you
do not want to accept an arbitrary class name but only load from a
file path, make sure that the argument $psgi_file_or_class begins
with "/" so that Perl's built-in do function won't search the
include path.
run_app
my $res = Plack::Util::run_app $app, $env;
Runs the $app by wrapping errors with eval and if an error is
found, logs it to "$env->{'psgi.errors'}" and returns the template
500 Error response.
header_get, header_exists, header_set, header_push, header_remove
my $hdrs = [ 'Content-Type' => 'text/plain' ];
my $v = Plack::Util::header_get($hdrs, $key); # First found only
my @v = Plack::Util::header_get($hdrs, $key);
my $bool = Plack::Util::header_exists($hdrs, $key);
Plack::Util::header_set($hdrs, $key, $val); # overwrites existent header
Plack::Util::header_push($hdrs, $key, $val);
Plack::Util::header_remove($hdrs, $key);
Utility functions to manipulate PSGI response headers array
reference. The methods that read existent header value handles
header name as case insensitive.
my $hdrs = [ 'Content-Type' => 'text/plain' ];
my $v = Plack::Util::header_get($hdrs, 'content-type'); # 'text/plain'
headers
my $headers = [ 'Content-Type' => 'text/plain' ];
my $h = Plack::Util::headers($headers);
$h->get($key);
if ($h->exists($key)) { ... }
$h->set($key => $val);
$h->push($key => $val);
$h->remove($key);
$h->headers; # same reference as $headers
Given a header array reference, returns a convenient object that
has an instance methods to access "header_*" functions with an OO
interface. The object holds a reference to the original given
$headers argument and updates the reference accordingly when called
write methods like "set", "push" or "remove". It also has "headers"
method that would return the same reference.
status_with_no_entity_body
if (status_with_no_entity_body($res->[0])) { }
Returns true if the given status code doesn't have any Entity body
in HTTP response, i.e. it's 100, 101, 204 or 304.
inline_object
my $o = Plack::Util::inline_object(
write => sub { $h->push_write(@_) },
close => sub { $h->push_shutdown },
);
$o->write(@stuff);
$o->close;
Creates an instant object that can react to methods passed in the
constructor. Handy to create when you need to create an IO stream
object for input or errors.
encode_html
my $encoded_string = Plack::Util::encode( $string );
Entity encodes "<", ">", "&", """ and "'" in the input string and
returns it.
response_cb
See "RESPONSE CALLBACK" in Plack::Middleware for details.
perl v5.14.2 2012-08-13 Plack::Util(3)
