.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Plack::Response 3pm"
.TH Plack::Response 3pm 2024-01-20 "perl v5.38.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::Response \- Portable HTTP Response object for PSGI response
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Plack::Response;
\&
\&  sub psgi_handler {
\&      my $env = shift;
\&
\&      my $res = Plack::Response\->new(200);
\&      $res\->content_type(\*(Aqtext/html\*(Aq);
\&      $res\->body("Hello World");
\&
\&      return $res\->finalize;
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Plack::Response allows you a way to create PSGI response array ref through a simple API.
.SH METHODS
.IX Header "METHODS"
.IP new 4
.IX Item "new"
.Vb 4
\&  $res = Plack::Response\->new;
\&  $res = Plack::Response\->new($status);
\&  $res = Plack::Response\->new($status, $headers);
\&  $res = Plack::Response\->new($status, $headers, $body);
.Ve
.Sp
Creates a new Plack::Response object.
.IP status 4
.IX Item "status"
.Vb 2
\&  $res\->status(200);
\&  $status = $res\->status;
.Ve
.Sp
Sets and gets HTTP status code. \f(CW\*(C`code\*(C'\fR is an alias.
.IP headers 4
.IX Item "headers"
.Vb 4
\&  $headers = $res\->headers;
\&  $res\->headers([ \*(AqContent\-Type\*(Aq => \*(Aqtext/html\*(Aq ]);
\&  $res\->headers({ \*(AqContent\-Type\*(Aq => \*(Aqtext/html\*(Aq });
\&  $res\->headers( HTTP::Headers::Fast\->new );
.Ve
.Sp
Sets and gets HTTP headers of the response. Setter can take either an
array ref, a hash ref or HTTP::Headers::Fast object containing a list of
headers.
.IP body 4
.IX Item "body"
.Vb 3
\&  $res\->body($body_str);
\&  $res\->body([ "Hello", "World" ]);
\&  $res\->body($io);
.Ve
.Sp
Gets and sets HTTP response body. Setter can take either a string, an
array ref, or an IO::Handle\-like object. \f(CW\*(C`content\*(C'\fR is an alias.
.Sp
Note that this method doesn't automatically set \fIContent-Length\fR for
the response. You have to set it manually if you want, with the
\&\f(CW\*(C`content_length\*(C'\fR method (see below).
.IP header 4
.IX Item "header"
.Vb 2
\&  $res\->header(\*(AqX\-Foo\*(Aq => \*(Aqbar\*(Aq);
\&  my $val = $res\->header(\*(AqX\-Foo\*(Aq);
.Ve
.Sp
Shortcut for \f(CW\*(C`$res\->headers\->header\*(C'\fR.
.IP "content_type, content_length, content_encoding" 4
.IX Item "content_type, content_length, content_encoding"
.Vb 3
\&  $res\->content_type(\*(Aqtext/plain\*(Aq);
\&  $res\->content_length(123);
\&  $res\->content_encoding(\*(Aqgzip\*(Aq);
.Ve
.Sp
Shortcut for the equivalent get/set methods in \f(CW\*(C`$res\->headers\*(C'\fR.
.IP redirect 4
.IX Item "redirect"
.Vb 2
\&  $res\->redirect($url);
\&  $res\->redirect($url, 301);
.Ve
.Sp
Sets redirect URL with an optional status code, which defaults to 302.
.Sp
Note that this method doesn't normalize the given URI string. Users of
this module have to be responsible about properly encoding URI paths
and parameters.
.IP location 4
.IX Item "location"
Gets and sets \f(CW\*(C`Location\*(C'\fR header.
.Sp
Note that this method doesn't normalize the given URI string in the
setter. See above in \f(CW\*(C`redirect\*(C'\fR for details.
.IP cookies 4
.IX Item "cookies"
.Vb 2
\&  $res\->cookies\->{foo} = 123;
\&  $res\->cookies\->{foo} = { value => \*(Aq123\*(Aq };
.Ve
.Sp
Returns a hash reference containing cookies to be set in the
response. The keys of the hash are the cookies' names, and their
corresponding values are a plain string (for \f(CW\*(C`value\*(C'\fR with everything
else defaults) or a hash reference that can contain keys such as
\&\f(CW\*(C`value\*(C'\fR, \f(CW\*(C`domain\*(C'\fR, \f(CW\*(C`expires\*(C'\fR, \f(CW\*(C`path\*(C'\fR, \f(CW\*(C`httponly\*(C'\fR, \f(CW\*(C`secure\*(C'\fR,
\&\f(CW\*(C`max\-age\*(C'\fR.
.Sp
\&\f(CW\*(C`expires\*(C'\fR can take a string or an integer (as an epoch time) and
\&\fBdoes not\fR convert string formats such as \f(CW\*(C`+3M\*(C'\fR.
.Sp
.Vb 6
\&  $res\->cookies\->{foo} = {
\&      value => \*(Aqtest\*(Aq,
\&      path  => "/",
\&      domain => \*(Aq.example.com\*(Aq,
\&      expires => time + 24 * 60 * 60,
\&  };
.Ve
.IP finalize 4
.IX Item "finalize"
.Vb 1
\&  $res\->finalize;
.Ve
.Sp
Returns the status code, headers, and body of this response as a PSGI
response array reference.
.IP to_app 4
.IX Item "to_app"
.Vb 1
\&  $app = $res\->to_app;
.Ve
.Sp
A helper shortcut for \f(CW\*(C`sub { $res\->finalize }\*(C'\fR.
.SH AUTHOR
.IX Header "AUTHOR"
Tokuhiro Matsuno
.PP
Tatsuhiko Miyagawa
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Plack::Request