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
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.
Since version 1.0006, this function would not load PSGI files from include
paths (@INC) unless it looks like a class name that only consists of
"[A-Za-z0-9_:]". For example:
Plack::Util::load_psgi("app.psgi"); # ./app.psgi
Plack::Util::load_psgi("/path/to/app.psgi"); # /path/to/app.psgi
Plack::Util::load_psgi("MyApp::PSGI"); # MyApp/PSGI.pm from @INC
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"
$app = Plack::Util::load_psgi($psgi); # this would lead to 'require "Moose.pm"'!
Generally speaking, passing an external input to this function is considered
very insecure. If you really want to do that, validate that a given file
name contains dots (like "foo.psgi") and also turn it into a
full path in your caller's code.
- 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.