.\" 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 "Dancer2::Core::App 3pm"
.TH Dancer2::Core::App 3pm "2018-12-23" "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"
Dancer2::Core::App \- encapsulation of Dancer2 packages
.SH "VERSION"
.IX Header "VERSION"
version 0.207000
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Everything a package that uses Dancer2 does is encapsulated into a
\&\f(CW\*(C`Dancer2::Core::App\*(C'\fR instance. This class defines all that can be done in such
objects.
.PP
Mainly, it will contain all the route handlers, the configuration settings and
the hooks that are defined in the calling package.
.PP
Note that with Dancer2, everything that is done within a package is scoped to
that package, thanks to that encapsulation.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "plugins"
.IX Subsection "plugins"
.SS "runner_config"
.IX Subsection "runner_config"
.SS "default_config"
.IX Subsection "default_config"
.SS "with_return"
.IX Subsection "with_return"
Used to cache the coderef from Return::MultiLevel within the dispatcher.
.SS "destroyed_session"
.IX Subsection "destroyed_session"
We cache a destroyed session here; once this is set we must not attempt to
retrieve the session from the cookie in the request.  If no new session is
created, this is set (with expiration) as a cookie to force the browser to
expire the cookie.
.SH "METHODS"
.IX Header "METHODS"
.SS "has_session"
.IX Subsection "has_session"
Returns true if session engine has been defined and if either a session
object has been instantiated or if a session cookie was found and not
subsequently invalidated.
.SS "change_session_id"
.IX Subsection "change_session_id"
Changes the session \s-1ID\s0 used by the current session. This should be used on
any change of privilege level, for example on login. Returns the new session
\&\s-1ID.\s0
.SS "destroy_session"
.IX Subsection "destroy_session"
Destroys the current session and ensures any subsequent session is created
from scratch and not from the request session cookie
.SS "register_plugin"
.IX Subsection "register_plugin"
.ie n .SS "with_plugins( @plugin_names )"
.el .SS "with_plugins( \f(CW@plugin_names\fP )"
.IX Subsection "with_plugins( @plugin_names )"
Creates instances of the given plugins and tie them to the app.
The plugin classes are automatically loaded.
Returns the newly created plugins.
.PP
The plugin names are expected to be without the leading \f(CW\*(C`Dancer2::Plugin\*(C'\fR.
I.e., use \f(CW\*(C`Foo\*(C'\fR to mean \f(CW\*(C`Dancer2::Plugin::Foo\*(C'\fR.
.PP
If a given plugin is already tied to the app, the already-existing
instance will be used and returned by \f(CW\*(C`with_plugins\*(C'\fR (think of it
as using a role).
.PP
.Vb 1
\&    my @plugins = $app\->with_plugins( \*(AqFoo\*(Aq, \*(AqBar\*(Aq );
\&
\&    # now $app uses the plugins Dancer2::Plugin::Foo
\&    # and Dancer2::Plugin::Bar
.Ve
.ie n .SS "with_plugin( $plugin_name )"
.el .SS "with_plugin( \f(CW$plugin_name\fP )"
.IX Subsection "with_plugin( $plugin_name )"
Just like \f(CW\*(C`with_plugin\*(C'\fR, but for a single plugin.
.PP
.Vb 1
\&    my $plugin = $app\->with_plugin(\*(AqFoo\*(Aq);
.Ve
.ie n .SS "redirect($destination, $status)"
.el .SS "redirect($destination, \f(CW$status\fP)"
.IX Subsection "redirect($destination, $status)"
Sets a redirect in the response object.  If \f(CW$destination\fR is not an absolute \s-1URI,\s0 then it will
be made into an absolute \s-1URI,\s0 relative to the \s-1URI\s0 in the request.
.SS "halt"
.IX Subsection "halt"
Flag the response object as 'halted'.
.PP
If called during request dispatch, immediately returns the response
to the dispatcher and after hooks will not be run.
.SS "pass"
.IX Subsection "pass"
Flag the response object as 'passed'.
.PP
If called during request dispatch, immediately returns the response
to the dispatcher.
.SS "forward"
.IX Subsection "forward"
Create a new request which is a clone of the current one, apart
from the path location, which points instead to the new location.
This is used internally to chain requests using the forward keyword.
.PP
This method takes 3 parameters: the url to forward to, followed by an
optional hashref of parameters added to the current request parameters,
followed by a hashref of options regarding the redirect, such as
\&\f(CW\*(C`method\*(C'\fR to change the request method.
.PP
For example:
.PP
.Vb 1
\&    forward \*(Aq/login\*(Aq, { login_failed => 1 }, { method => \*(AqGET\*(Aq });
.Ve
.SS "lexical_prefix"
.IX Subsection "lexical_prefix"
Allow for setting a lexical prefix
.PP
.Vb 3
\&    $app\->lexical_prefix(\*(Aq/blog\*(Aq, sub {
\&        ...
\&    });
.Ve
.PP
All the route defined within the callback will have a prefix appended to the
current one.
.SS "add_route"
.IX Subsection "add_route"
Register a new route handler.
.PP
.Vb 6
\&    $app\->add_route(
\&        method  => \*(Aqget\*(Aq,
\&        regexp  => \*(Aq/somewhere\*(Aq,
\&        code    => sub { ... },
\&        options => $conditions,
\&    );
.Ve
.SS "route_exists"
.IX Subsection "route_exists"
Check if a route already exists.
.PP
.Vb 4
\&    my $route = Dancer2::Core::Route\->new(...);
\&    if ($app\->route_exists($route)) {
\&        ...
\&    }
.Ve
.SS "routes_regexps_for"
.IX Subsection "routes_regexps_for"
Sugar for getting the ordered list of all registered route regexps by method.
.PP
.Vb 1
\&    my $regexps = $app\->routes_regexps_for( \*(Aqget\*(Aq );
.Ve
.PP
Returns an ArrayRef with the results.
.SS "app"
.IX Subsection "app"
Returns itself. This is simply available as a shim to help transition from
a previous version in which hooks were sent a context object (originally
\&\f(CW\*(C`Dancer2::Core::Context\*(C'\fR) which has since been removed.
.PP
.Vb 5
\&    # before
\&    hook before => sub {
\&        my $ctx = shift;
\&        my $app = $ctx\->app;
\&    };
\&
\&    # after
\&    hook before => sub {
\&        my $app = shift;
\&    };
.Ve
.PP
This meant that \f(CW\*(C`$app\->app\*(C'\fR would fail, so this method has been provided
to make it work.
.PP
.Vb 5
\&    # now
\&    hook before => sub {
\&        my $WannaBeCtx = shift;
\&        my $app        = $WannaBeContext\->app; # works
\&    };
.Ve
.ie n .SS " $SIG{_\|_DIE_\|_}  Compatibility via  $Dancer2::Core::App::EVAL_SHIM "
.el .SS "\f(CW $SIG{_\|_DIE_\|_} \fP Compatibility via \f(CW $Dancer2::Core::App::EVAL_SHIM \fP"
.IX Subsection " $SIG{__DIE__} Compatibility via $Dancer2::Core::App::EVAL_SHIM "
If an installation wishes to use \f(CW $SIG{_\|_DIE_\|_} \fR hooks to enhance
their error handling then it may be required to ensure that certain
bookkeeping code is executed within every \f(CW\*(C`eval BLOCK\*(C'\fR that Dancer2
performs. This can be accomplished by overriding the global variable
\&\f(CW$Dancer2::Core::App::EVAL_SHIM\fR with a subroutine which does whatever
logic is required.
.PP
This routine must perform the equivalent of the following subroutine:
.PP
.Vb 4
\&    our $EVAL_SHIM = sub {
\&        my $code = shift;
\&        return $code\->(@_);
\&    };
.Ve
.PP
An example of overriding this sub might be as follows:
.PP
.Vb 5
\&    $Dancer2::Core::App::EVAL_SHIM = sub {
\&        my $code = shift;
\&        local $IGNORE_EVAL_COUNTER = $IGNORE_EVAL_COUNTER + 1;
\&        return $code\->(@_);
\&    };
.Ve
.PP
\&\fBNote:\fR that this is a \s-1GLOBAL\s0 setting, which must be set up before
any form of dispatch or use of Dancer2.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2018 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.