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 andrequire the class. Throws an exception if the .pm file for the class is not found, just with the built-inrequire.

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");                   # Foomy $class = Plack::Util::load_class("Baz", "Foo::Bar");       # Foo::Bar::Bazmy $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 asModule::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 alsoIO::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 aline) 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;

Loadapp.psgi file or a class name (likeMyApp::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.psgiPlack::Util::load_psgi("/path/to/app.psgi"); # /path/to/app.psgiPlack::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 (likefoo.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 witheval 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 onlymy @v = Plack::Util::header_get($hdrs, $key);my $bool = Plack::Util::header_exists($hdrs, $key);Plack::Util::header_set($hdrs, $key, $val);   # overwrites existent headerPlack::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 accessheader_* 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 likeset,push orremove. It also hasheaders 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_html( $string );

Entity encodes<,>,&," and' in the input string and returns it.

response_cb

See"RESPONSE CALLBACK" in Plack::Middleware for details.