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.