.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    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 "Catalyst::Engine 3pm"
.TH Catalyst::Engine 3pm "2019-01-19" "perl v5.28.1" "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"
Catalyst::Engine \- The Catalyst Engine
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
See Catalyst.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$self\->finalize_body($c)"
.el .SS "\f(CW$self\fP\->finalize_body($c)"
.IX Subsection "$self->finalize_body($c)"
Finalize body.  Prints the response output as blocking stream if it looks like
a filehandle, otherwise write it out all in one go.  If there is no body in
the response, we assume you are handling it 'manually', such as for nonblocking
style or asynchronous streaming responses.  You do this by calling \*(L"write\*(R"
several times (which sends \s-1HTTP\s0 headers if needed) or you close over
\&\f(CW\*(C`$response\->write_fh\*(C'\fR.
.PP
See \*(L"write\*(R" in Catalyst::Response and \*(L"write_fh\*(R" in Catalyst::Response for more.
.ie n .SS "$self\->finalize_cookies($c)"
.el .SS "\f(CW$self\fP\->finalize_cookies($c)"
.IX Subsection "$self->finalize_cookies($c)"
Create CGI::Simple::Cookie objects from \f(CW$c\fR\->res\->cookies, and set them as
response headers.
.ie n .SS "$self\->finalize_error($c)"
.el .SS "\f(CW$self\fP\->finalize_error($c)"
.IX Subsection "$self->finalize_error($c)"
Output an appropriate error message. Called if there's an error in \f(CW$c\fR
after the dispatch has finished. Will output debug messages if Catalyst
is in debug mode, or a `please come back later` message otherwise.
.ie n .SS "$self\->finalize_headers($c)"
.el .SS "\f(CW$self\fP\->finalize_headers($c)"
.IX Subsection "$self->finalize_headers($c)"
Allows engines to write headers to response
.ie n .SS "$self\->finalize_uploads($c)"
.el .SS "\f(CW$self\fP\->finalize_uploads($c)"
.IX Subsection "$self->finalize_uploads($c)"
Clean up after uploads, deleting temp files.
.ie n .SS "$self\->prepare_body($c)"
.el .SS "\f(CW$self\fP\->prepare_body($c)"
.IX Subsection "$self->prepare_body($c)"
sets up the Catalyst::Request object body using HTTP::Body
.ie n .SS "$self\->prepare_body_chunk($c)"
.el .SS "\f(CW$self\fP\->prepare_body_chunk($c)"
.IX Subsection "$self->prepare_body_chunk($c)"
Add a chunk to the request body.
.ie n .SS "$self\->prepare_body_parameters($c)"
.el .SS "\f(CW$self\fP\->prepare_body_parameters($c)"
.IX Subsection "$self->prepare_body_parameters($c)"
Sets up parameters from body.
.ie n .SS "$self\->prepare_parameters($c)"
.el .SS "\f(CW$self\fP\->prepare_parameters($c)"
.IX Subsection "$self->prepare_parameters($c)"
Sets up parameters from query and post parameters.
If parameters have already been set up will clear
existing parameters and set up again.
.ie n .SS "$self\->prepare_path($c)"
.el .SS "\f(CW$self\fP\->prepare_path($c)"
.IX Subsection "$self->prepare_path($c)"
abstract method, implemented by engines.
.ie n .SS "$self\->prepare_request($c)"
.el .SS "\f(CW$self\fP\->prepare_request($c)"
.IX Subsection "$self->prepare_request($c)"
.ie n .SS "$self\->prepare_query_parameters($c)"
.el .SS "\f(CW$self\fP\->prepare_query_parameters($c)"
.IX Subsection "$self->prepare_query_parameters($c)"
process the query string and extract query parameters.
.ie n .SS "$self\->prepare_read($c)"
.el .SS "\f(CW$self\fP\->prepare_read($c)"
.IX Subsection "$self->prepare_read($c)"
Prepare to read by initializing the Content-Length from headers.
.ie n .SS "$self\->prepare_request(@arguments)"
.el .SS "\f(CW$self\fP\->prepare_request(@arguments)"
.IX Subsection "$self->prepare_request(@arguments)"
Populate the context object from the request object.
.ie n .SS "$self\->prepare_uploads($c)"
.el .SS "\f(CW$self\fP\->prepare_uploads($c)"
.IX Subsection "$self->prepare_uploads($c)"
.ie n .SS "$self\->write($c, $buffer)"
.el .SS "\f(CW$self\fP\->write($c, \f(CW$buffer\fP)"
.IX Subsection "$self->write($c, $buffer)"
Writes the buffer to the client.
.ie n .SS "$self\->unencoded_write($c, $buffer)"
.el .SS "\f(CW$self\fP\->unencoded_write($c, \f(CW$buffer\fP)"
.IX Subsection "$self->unencoded_write($c, $buffer)"
Writes the buffer to the client without encoding. Necessary for
already encoded buffers. Used when a \f(CW$c\fR\->write has been done
followed by \f(CW$c\fR\->res\->body.
.ie n .SS "$self\->read($c, [$maxlength])"
.el .SS "\f(CW$self\fP\->read($c, [$maxlength])"
.IX Subsection "$self->read($c, [$maxlength])"
Reads from the input stream by calling \f(CW\*(C`$self\->read_chunk\*(C'\fR.
.PP
Maintains the read_length and read_position counters as data is read.
.ie n .SS "$self\->read_chunk($c, \e$buffer, $length)"
.el .SS "\f(CW$self\fP\->read_chunk($c, \e$buffer, \f(CW$length\fP)"
.IX Subsection "$self->read_chunk($c, $buffer, $length)"
Each engine implements read_chunk as its preferred way of reading a chunk
of data. Returns the number of bytes read. A return of 0 indicates that
there is no more data to be read.
.ie n .SS "$self\->run($app, $server)"
.el .SS "\f(CW$self\fP\->run($app, \f(CW$server\fP)"
.IX Subsection "$self->run($app, $server)"
Start the engine. Builds a \s-1PSGI\s0 application and calls the
run method on the server passed in, which then causes the
engine to loop, handling requests..
.ie n .SS "build_psgi_app ($app, @args)"
.el .SS "build_psgi_app ($app, \f(CW@args\fP)"
.IX Subsection "build_psgi_app ($app, @args)"
Builds and returns a \s-1PSGI\s0 application closure. (Raw, not wrapped in middleware)
.ie n .SS "$self\->unescape_uri($uri)"
.el .SS "\f(CW$self\fP\->unescape_uri($uri)"
.IX Subsection "$self->unescape_uri($uri)"
Unescapes a given \s-1URI\s0 using the most efficient method available.  Engines such
as Apache may implement this using Apache's C\-based modules, for example.
.ie n .SS "$self\->finalize_output"
.el .SS "\f(CW$self\fP\->finalize_output"
.IX Subsection "$self->finalize_output"
<obsolete>, see finalize_body
.ie n .SS "$self\->env"
.el .SS "\f(CW$self\fP\->env"
.IX Subsection "$self->env"
Hash containing environment variables including many special variables inserted
by \s-1WWW\s0 server \- like SERVER_*, REMOTE_*, HTTP_* ...
.PP
Before accessing environment variables consider whether the same information is
not directly available via Catalyst objects \f(CW$c\fR\->request, \f(CW$c\fR\->engine ...
.PP
\&\s-1BEWARE:\s0 If you really need to access some environment variable from your Catalyst
application you should use \f(CW$c\fR\->engine\->env\->{\s-1VARNAME\s0} instead of \f(CW$ENV\fR{\s-1VARNAME\s0},
as in some environments the \f(CW%ENV\fR hash does not contain what you would expect.
.SH "AUTHORS"
.IX Header "AUTHORS"
Catalyst Contributors, see Catalyst.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software. You can redistribute it and/or modify it under
the same terms as Perl itself.