.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 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.
.\"
.\" 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
.\"
.\" 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 "Dancer::Request 3pm"
.TH Dancer::Request 3pm "2014-10-20" "perl v5.20.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"
Dancer::Request \- interface for accessing incoming requests
.SH "VERSION"
.IX Header "VERSION"
version 1.3132
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class implements a common interface for accessing incoming requests in
a Dancer application.
.PP
In a route handler, the current request object can be accessed by the \f(CW\*(C`request\*(C'\fR
method, like in the following example:
.PP
.Vb 6
\&    get \*(Aq/foo\*(Aq => sub {
\&        request\->params; # request, params parsed as a hash ref
\&        request\->body; # returns the request body, unparsed
\&        request\->path; # the path requested by the client
\&        # ...
\&    };
.Ve
.PP
A route handler should not read the environment by itself, but should instead
use the current request object.
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.SS "\fInew()\fP"
.IX Subsection "new()"
The constructor of the class, used internally by Dancer's core to create request
objects.
.PP
It uses the environment hash table given to build the request object:
.PP
.Vb 1
\&    Dancer::Request\->new(env => \e%ENV);
.Ve
.PP
It also accepts the \f(CW\*(C`is_forward\*(C'\fR boolean flag, if the new request
object is the result of a forward.
.SS "\fIinit()\fP"
.IX Subsection "init()"
Used internally to define some default values and parse parameters.
.ie n .SS "new_for_request($method, $path, $params, $body, $headers)"
.el .SS "new_for_request($method, \f(CW$path\fP, \f(CW$params\fP, \f(CW$body\fP, \f(CW$headers\fP)"
.IX Subsection "new_for_request($method, $path, $params, $body, $headers)"
An alternate constructor convenient for test scripts which creates a request
object with the arguments given.
.ie n .SS "forward($request, $new_location)"
.el .SS "forward($request, \f(CW$new_location\fP)"
.IX Subsection "forward($request, $new_location)"
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
Note that the new location should be a hash reference. Only one key is
required, the \f(CW\*(C`to_url\*(C'\fR, that should point to the \s-1URL\s0 that forward
will use. Optional values are the key \f(CW\*(C`params\*(C'\fR to a hash of
parameters to be added to the current request parameters, and the key
\&\f(CW\*(C`options\*(C'\fR that points to a hash of options about the redirect (for
instance, \f(CW\*(C`method\*(C'\fR pointing to a new request method).
.SS "is_forward"
.IX Subsection "is_forward"
Flag that will be set to true if the request has been forwarded.
.SS "\fIto_string()\fP"
.IX Subsection "to_string()"
Return a string representing the request object (eg: \f(CW"GET /some/path"\fR)
.SS "\fImethod()\fP"
.IX Subsection "method()"
Return the \s-1HTTP\s0 method used by the client to access the application.
.PP
While this method returns the method string as provided by the environment, it's
better to use one of the following boolean accessors if you want to inspect the
requested method.
.SS "\fIaddress()\fP"
.IX Subsection "address()"
Return the \s-1IP\s0 address of the client.
.SS "\fIremote_host()\fP"
.IX Subsection "remote_host()"
Return the remote host of the client. This only works with web servers configured
to do a reverse \s-1DNS\s0 lookup on the client's \s-1IP\s0 address.
.SS "\fIprotocol()\fP"
.IX Subsection "protocol()"
Return the protocol (\s-1HTTP/1.0\s0 or \s-1HTTP/1.1\s0) used for the request.
.SS "\fIport()\fP"
.IX Subsection "port()"
Return the port of the server.
.SS "\fIuri()\fP"
.IX Subsection "uri()"
An alias to \fIrequest_uri()\fR
.SS "\fIrequest_uri()\fP"
.IX Subsection "request_uri()"
Return the raw, undecoded request \s-1URI\s0 path.
.SS "\fIuser()\fP"
.IX Subsection "user()"
Return remote user if defined.
.SS "\fIscript_name()\fP"
.IX Subsection "script_name()"
Return script_name from the environment.
.SS "\fIscheme()\fP"
.IX Subsection "scheme()"
Return the scheme of the request
.SS "\fIsecure()\fP"
.IX Subsection "secure()"
Return true of false, indicating whether the connection is secure
.SS "\fIis_get()\fP"
.IX Subsection "is_get()"
Return true if the method requested by the client is '\s-1GET\s0'
.SS "\fIis_head()\fP"
.IX Subsection "is_head()"
Return true if the method requested by the client is '\s-1HEAD\s0'
.SS "\fIis_patch()\fP"
.IX Subsection "is_patch()"
Return true if the method requested by the client is '\s-1PATCH\s0'
.SS "\fIis_post()\fP"
.IX Subsection "is_post()"
Return true if the method requested by the client is '\s-1POST\s0'
.SS "\fIis_put()\fP"
.IX Subsection "is_put()"
Return true if the method requested by the client is '\s-1PUT\s0'
.SS "\fIis_delete()\fP"
.IX Subsection "is_delete()"
Return true if the method requested by the client is '\s-1DELETE\s0'
.SS "\fIpath()\fP"
.IX Subsection "path()"
Return the path requested by the client.
.SS "\fIbase()\fP"
.IX Subsection "base()"
Returns an absolute \s-1URI\s0 for the base of the application.  Returns a \s-1URI\s0
object (which stringifies to the \s-1URL,\s0 as you'd expect).
.SS "\fIuri_base()\fP"
.IX Subsection "uri_base()"
Same thing as \f(CW\*(C`base\*(C'\fR above, except it removes the last trailing slash in the
path if it is the only path.
.PP
This means that if your base is \fIhttp://myserver/\fR, \f(CW\*(C`uri_base\*(C'\fR will return
\&\fIhttp://myserver\fR (notice no trailing slash). This is considered very useful
when using templates to do the following thing:
.PP
.Vb 1
\&    <link rel="stylesheet" href="<% request.uri_base %>/css/style.css" />
.Ve
.SS "uri_for(path, params)"
.IX Subsection "uri_for(path, params)"
Constructs a \s-1URI\s0 from the base and the passed path.  If params (hashref) is
supplied, these are added to the query string of the uri.  If the base is
\&\f(CW\*(C`http://localhost:5000/foo\*(C'\fR, \f(CW\*(C`request\->uri_for(\*(Aq/bar\*(Aq, { baz => \*(Aqbaz\*(Aq })\*(C'\fR
would return \f(CW\*(C`http://localhost:5000/foo/bar?baz=baz\*(C'\fR.  Returns a \s-1URI\s0 object
(which stringifies to the \s-1URL,\s0 as you'd expect).
.SS "params($source)"
.IX Subsection "params($source)"
Called in scalar context, returns a hashref of params, either from the specified
source (see below for more info on that) or merging all sources.
.PP
So, you can use, for instance:
.PP
.Vb 1
\&    my $foo = params\->{foo}
.Ve
.PP
If called in list context, returns a list of key => value pairs, so you could use:
.PP
.Vb 1
\&    my %allparams = params;
.Ve
.PP
If the incoming form data contains multiple values for the same key, they will
be returned as an arrayref.
.PP
\fIFetching only params from a given source\fR
.IX Subsection "Fetching only params from a given source"
.PP
If a required source isn't specified, a mixed hashref (or list of key value
pairs, in list context) will be returned; this will contain params from all
sources (route, query, body).
.PP
In practical terms, this means that if the param \f(CW\*(C`foo\*(C'\fR is passed both on the
querystring and in a \s-1POST\s0 body, you can only access one of them.
.PP
If you want to see only params from a given source, you can say so by passing
the \f(CW$source\fR param to \f(CW\*(C`params()\*(C'\fR:
.PP
.Vb 3
\&    my %querystring_params = params(\*(Aqquery\*(Aq);
\&    my %route_params       = params(\*(Aqroute\*(Aq);
\&    my %post_params        = params(\*(Aqbody\*(Aq);
.Ve
.PP
If source equals \f(CW\*(C`route\*(C'\fR, then only params parsed from the route pattern
are returned.
.PP
If source equals \f(CW\*(C`query\*(C'\fR, then only params parsed from the query string are
returned.
.PP
If source equals \f(CW\*(C`body\*(C'\fR, then only params sent in the request body will be
returned.
.PP
If another value is given for \f(CW$source\fR, then an exception is triggered.
.SS "Vars"
.IX Subsection "Vars"
Alias to the \f(CW\*(C`params\*(C'\fR accessor, for backward-compatibility with \f(CW\*(C`CGI\*(C'\fR interface.
.SS "request_method"
.IX Subsection "request_method"
Alias to the \f(CW\*(C`method\*(C'\fR accessor, for backward-compatibility with \f(CW\*(C`CGI\*(C'\fR interface.
.SS "input_handle"
.IX Subsection "input_handle"
Alias to the \s-1PSGI\s0 input handle (\f(CW\*(C`<request\->env\->{psgi.input}>\*(C'\fR)
.SS "\fIcontent_type()\fP"
.IX Subsection "content_type()"
Return the content type of the request.
.SS "\fIcontent_length()\fP"
.IX Subsection "content_length()"
Return the content length of the request.
.SS "header($name)"
.IX Subsection "header($name)"
Return the value of the given header, if present. If the header has multiple
values, returns an the list of values if called in list context, the first one
in scalar.
.SS "\fIheaders()\fP"
.IX Subsection "headers()"
Returns the HTTP::Header object used to store all the headers.
.SS "\fIbody()\fP"
.IX Subsection "body()"
Return the raw body of the request, unparsed.
.PP
If you need to access the body of the request, you have to use this accessor and
should not try to read \f(CW\*(C`psgi.input\*(C'\fR by hand. \f(CW\*(C`Dancer::Request\*(C'\fR already did it for you
and kept the raw body untouched in there.
.SS "\fIis_ajax()\fP"
.IX Subsection "is_ajax()"
Return true if the value of the header \f(CW\*(C`X\-Requested\-With\*(C'\fR is XMLHttpRequest.
.SS "\fIenv()\fP"
.IX Subsection "env()"
Return the current environment as a hashref.
.PP
Note that a request's environment is not always reflected by the global
variable \f(CW%ENV\fR (e.g., when running via Plack::Handler::FCGI). In
consequence, it is recommended to always rely on the values returned by
\&\f(CW\*(C`env()\*(C'\fR, and not to access \f(CW%ENV\fR directly.
.SS "\fIuploads()\fP"
.IX Subsection "uploads()"
Returns a reference to a hash containing uploads. Values can be either a
Dancer::Request::Upload object, or an arrayref of Dancer::Request::Upload
objects.
.PP
You should probably use the \f(CW\*(C`upload($name)\*(C'\fR accessor instead of manually accessing the
\&\f(CW\*(C`uploads\*(C'\fR hash table.
.SS "upload($name)"
.IX Subsection "upload($name)"
Context-aware accessor for uploads. It's a wrapper around an access to the hash
table provided by \f(CW\*(C`uploads()\*(C'\fR. It looks at the calling context and returns a
corresponding value.
.PP
If you have many file uploads under the same name, and call \f(CW\*(C`upload(\*(Aqname\*(Aq)\*(C'\fR in
an array context, the accessor will unroll the \s-1ARRAY\s0 ref for you:
.PP
.Vb 1
\&    my @uploads = request\->upload(\*(Aqmany_uploads\*(Aq); # OK
.Ve
.PP
Whereas with a manual access to the hash table, you'll end up with one element
in \f(CW@uploads\fR, being the \s-1ARRAY\s0 ref:
.PP
.Vb 1
\&    my @uploads = request\->uploads\->{\*(Aqmany_uploads\*(Aq}; # $uploads[0]: ARRAY(0xXXXXX)
.Ve
.PP
That is why this accessor should be used instead of a manual access to
\&\f(CW\*(C`uploads\*(C'\fR.
.SH "Values"
.IX Header "Values"
Given a request to http://perldancer.org:5000/request\-methods?a=1 these are
the values returned by the various request\->  method calls:
.PP
.Vb 9
\&  base         http://perldancer.org:5000/
\&  uri_base     http://perldancer.org:5000
\&  uri          /request\-methods?a=1
\&  request_uri  /request\-methods?a=1
\&  path         /request\-methods
\&  method       GET
\&  port         5000
\&  protocol     HTTP/1.1
\&  scheme       http
.Ve
.SH "HTTP environment variables"
.IX Header "HTTP environment variables"
All \s-1HTTP\s0 environment variables that are in \f(CW%ENV\fR will be provided in the
Dancer::Request object through specific accessors, here are those supported:
.ie n .IP """accept""" 4
.el .IP "\f(CWaccept\fR" 4
.IX Item "accept"
.PD 0
.ie n .IP """accept_charset""" 4
.el .IP "\f(CWaccept_charset\fR" 4
.IX Item "accept_charset"
.ie n .IP """accept_encoding""" 4
.el .IP "\f(CWaccept_encoding\fR" 4
.IX Item "accept_encoding"
.ie n .IP """accept_language""" 4
.el .IP "\f(CWaccept_language\fR" 4
.IX Item "accept_language"
.ie n .IP """accept_type""" 4
.el .IP "\f(CWaccept_type\fR" 4
.IX Item "accept_type"
.ie n .IP """agent"" (alias for ""user_agent"")" 4
.el .IP "\f(CWagent\fR (alias for \f(CWuser_agent\fR)" 4
.IX Item "agent (alias for user_agent)"
.ie n .IP """connection""" 4
.el .IP "\f(CWconnection\fR" 4
.IX Item "connection"
.ie n .IP """forwarded_for_address""" 4
.el .IP "\f(CWforwarded_for_address\fR" 4
.IX Item "forwarded_for_address"
.ie n .IP """forwarded_protocol""" 4
.el .IP "\f(CWforwarded_protocol\fR" 4
.IX Item "forwarded_protocol"
.ie n .IP """forwarded_host""" 4
.el .IP "\f(CWforwarded_host\fR" 4
.IX Item "forwarded_host"
.ie n .IP """host""" 4
.el .IP "\f(CWhost\fR" 4
.IX Item "host"
.ie n .IP """keep_alive""" 4
.el .IP "\f(CWkeep_alive\fR" 4
.IX Item "keep_alive"
.ie n .IP """path_info""" 4
.el .IP "\f(CWpath_info\fR" 4
.IX Item "path_info"
.ie n .IP """referer""" 4
.el .IP "\f(CWreferer\fR" 4
.IX Item "referer"
.ie n .IP """remote_address""" 4
.el .IP "\f(CWremote_address\fR" 4
.IX Item "remote_address"
.ie n .IP """request_base""" 4
.el .IP "\f(CWrequest_base\fR" 4
.IX Item "request_base"
.ie n .IP """user_agent""" 4
.el .IP "\f(CWuser_agent\fR" 4
.IX Item "user_agent"
.PD
.SH "AUTHORS"
.IX Header "AUTHORS"
This module has been written by Alexis Sukrieh and was mostly
inspired by Plack::Request, written by Tatsuiko Miyagawa.
.PP
Tatsuiko Miyagawa also gave a hand for the \s-1PSGI\s0 interface.
.SH "LICENCE"
.IX Header "LICENCE"
This module is released under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Dancer
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 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.