NAME¶
Plack::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
- 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.
- response_cb
- See "RESPONSE CALLBACK" in Plack::Middleware for
details.