.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Plack::Util 3pm"
.TH Plack::Util 3pm "2011-11-02" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Plack::Util \- Utility subroutines for Plack server and framework developers
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\s-1TRUE\s0, \s-1FALSE\s0" 4
.IX Item "TRUE, FALSE"
.Vb 2
\&  my $true  = Plack::Util::TRUE;
\&  my $false = Plack::Util::FALSE;
.Ve
.Sp
Utility constants to include when you specify boolean variables in \f(CW$env\fR hash (e.g. \f(CW\*(C`psgi.multithread\*(C'\fR).
.IP "load_class" 4
.IX Item "load_class"
.Vb 1
\&  my $class = Plack::Util::load_class($class [, $prefix ]);
.Ve
.Sp
Constructs a class name and \f(CW\*(C`require\*(C'\fR the class. Throws an exception
if the .pm file for the class is not found, just with the built-in
\&\f(CW\*(C`require\*(C'\fR.
.Sp
If \f(CW$prefix\fR is set, the class name is prepended to the \f(CW$class\fR
unless \f(CW$class\fR begins with \f(CW\*(C`+\*(C'\fR sign, which means the class name is
already fully qualified.
.Sp
.Vb 3
\&  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
.Ve
.IP "is_real_fh" 4
.IX Item "is_real_fh"
.Vb 1
\&  if ( Plack::Util::is_real_fh($fh) ) { }
.Ve
.Sp
returns true if a given \f(CW$fh\fR is a real file handle that has a file
descriptor. It returns false if \f(CW$fh\fR is PerlIO handle that is not
really related to the underlying file etc.
.IP "content_length" 4
.IX Item "content_length"
.Vb 1
\&  my $cl = Plack::Util::content_length($body);
.Ve
.Sp
Returns the length of content from body if it can be calculated. If
\&\f(CW$body\fR is an array ref it's a sum of length of each chunk, if
\&\f(CW$body\fR is a real filehandle it's a remaining size of the filehandle,
otherwise returns undef.
.IP "set_io_path" 4
.IX Item "set_io_path"
.Vb 1
\&  Plack::Util::set_io_path($fh, "/path/to/foobar.txt");
.Ve
.Sp
Sets the (absolute) file path to \f(CW$fh\fR filehandle object, so you can
call \f(CW\*(C`$fh\->path\*(C'\fR on it. As a side effect \f(CW$fh\fR is blessed to an
internal package but it can still be treated as a normal file
handle.
.Sp
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.
.IP "foreach" 4
.IX Item "foreach"
.Vb 1
\&  Plack::Util::foreach($body, $cb);
.Ve
.Sp
Iterate through \fI\f(CI$body\fI\fR which is an array reference or
IO::Handle\-like object and pass each line (which is \s-1NOT\s0 really
guaranteed to be a \fIline\fR) to the callback function.
.Sp
It internally sets the buffer length \f(CW$/\fR to 65536 in case it reads
the binary file, unless otherwise set in the caller's code.
.IP "load_psgi" 4
.IX Item "load_psgi"
.Vb 1
\&  my $app = Plack::Util::load_psgi $psgi_file_or_class;
.Ve
.Sp
Load \f(CW\*(C`app.psgi\*(C'\fR file or a class name (like \f(CW\*(C`MyApp::PSGI\*(C'\fR) and
require the file to get \s-1PSGI\s0 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.
.Sp
\&\fBSecurity\fR: 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:
.Sp
.Vb 2
\&  my $psgi = ...; # user\-input: consider "Moose.pm"
\&  $app = Plack::Util::load_psgi($psgi); # this does \*(Aqrequire "Moose.pm"\*(Aq!
.Ve
.Sp
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 \f(CW$psgi_file_or_class\fR begins with \f(CW\*(C`/\*(C'\fR so
that Perl's built-in do function won't search the include path.
.IP "run_app" 4
.IX Item "run_app"
.Vb 1
\&  my $res = Plack::Util::run_app $app, $env;
.Ve
.Sp
Runs the \fI\f(CI$app\fI\fR by wrapping errors with \fIeval\fR and if an error is
found, logs it to \f(CW\*(C`$env\->{\*(Aqpsgi.errors\*(Aq}\*(C'\fR and returns the
template 500 Error response.
.IP "header_get, header_exists, header_set, header_push, header_remove" 4
.IX Item "header_get, header_exists, header_set, header_push, header_remove"
.Vb 1
\&  my $hdrs = [ \*(AqContent\-Type\*(Aq => \*(Aqtext/plain\*(Aq ];
\&
\&  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);
.Ve
.Sp
Utility functions to manipulate \s-1PSGI\s0 response headers array
reference. The methods that read existent header value handles header
name as case insensitive.
.Sp
.Vb 2
\&  my $hdrs = [ \*(AqContent\-Type\*(Aq => \*(Aqtext/plain\*(Aq ];
\&  my $v = Plack::Util::header_get($hdrs, \*(Aqcontent\-type\*(Aq); # \*(Aqtext/plain\*(Aq
.Ve
.IP "headers" 4
.IX Item "headers"
.Vb 1
\&  my $headers = [ \*(AqContent\-Type\*(Aq => \*(Aqtext/plain\*(Aq ];
\&
\&  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
.Ve
.Sp
Given a header array reference, returns a convenient object that has
an instance methods to access \f(CW\*(C`header_*\*(C'\fR functions with an \s-1OO\s0
interface. The object holds a reference to the original given
\&\f(CW$headers\fR argument and updates the reference accordingly when called
write methods like \f(CW\*(C`set\*(C'\fR, \f(CW\*(C`push\*(C'\fR or \f(CW\*(C`remove\*(C'\fR. It also has \f(CW\*(C`headers\*(C'\fR
method that would return the same reference.
.IP "status_with_no_entity_body" 4
.IX Item "status_with_no_entity_body"
.Vb 1
\&  if (status_with_no_entity_body($res\->[0])) { }
.Ve
.Sp
Returns true if the given status code doesn't have any Entity body in
\&\s-1HTTP\s0 response, i.e. it's 100, 101, 204 or 304.
.IP "inline_object" 4
.IX Item "inline_object"
.Vb 6
\&  my $o = Plack::Util::inline_object(
\&      write => sub { $h\->push_write(@_) },
\&      close => sub { $h\->push_shutdown },
\&  );
\&  $o\->write(@stuff);
\&  $o\->close;
.Ve
.Sp
Creates an instant object that can react to methods passed in the
constructor. Handy to create when you need to create an \s-1IO\s0 stream
object for input or errors.
.IP "response_cb" 4
.IX Item "response_cb"
See \*(L"\s-1RESPONSE\s0 \s-1CALLBACK\s0\*(R" in Plack::Middleware for details.