Add built local::lib
[catagits/Gitalist.git] / local-lib5 / man / man3 / Catalyst::Request.3pm
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  | will give a
29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
32 .tr \(*W-|\(bv\*(Tr
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "Catalyst::Request 3"
132 .TH Catalyst::Request 3 "2009-11-30" "perl v5.8.7" "User Contributed Perl Documentation"
133 .SH "NAME"
134 Catalyst::Request \- provides information about the current client request
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 .Vb 35
138 \&    $req = $c\->request;
139 \&    $req\->action;
140 \&    $req\->address;
141 \&    $req\->arguments;
142 \&    $req\->args;
143 \&    $req\->base;
144 \&    $req\->body;
145 \&    $req\->body_parameters;
146 \&    $req\->content_encoding;
147 \&    $req\->content_length;
148 \&    $req\->content_type;
149 \&    $req\->cookie;
150 \&    $req\->cookies;
151 \&    $req\->header;
152 \&    $req\->headers;
153 \&    $req\->hostname;
154 \&    $req\->input;
155 \&    $req\->query_keywords;
156 \&    $req\->match;
157 \&    $req\->method;
158 \&    $req\->param;
159 \&    $req\->parameters;
160 \&    $req\->params;
161 \&    $req\->path;
162 \&    $req\->protocol;
163 \&    $req\->query_parameters;
164 \&    $req\->read;
165 \&    $req\->referer;
166 \&    $req\->secure;
167 \&    $req\->captures; # previously knows as snippets
168 \&    $req\->upload;
169 \&    $req\->uploads;
170 \&    $req\->uri;
171 \&    $req\->user;
172 \&    $req\->user_agent;
173 .Ve
174 .PP
175 See also Catalyst, Catalyst::Request::Upload.
176 .SH "DESCRIPTION"
177 .IX Header "DESCRIPTION"
178 This is the Catalyst Request class, which provides an interface to data for the
179 current client request. The request object is prepared by Catalyst::Engine,
180 thus hiding the details of the particular engine implementation.
181 .SH "METHODS"
182 .IX Header "METHODS"
183 .Sh "$req\->action"
184 .IX Subsection "$req->action"
185 [\s-1DEPRECATED\s0] Returns the name of the requested action.
186 .PP
187 Use \f(CW\*(C`$c\->action\*(C'\fR instead (which returns a
188 Catalyst::Action object).
189 .Sh "$req\->address"
190 .IX Subsection "$req->address"
191 Returns the \s-1IP\s0 address of the client.
192 .Sh "$req\->arguments"
193 .IX Subsection "$req->arguments"
194 Returns a reference to an array containing the arguments.
195 .PP
196 .Vb 1
197 \&    print $c\->request\->arguments\->[0];
198 .Ve
199 .PP
200 For example, if your action was
201 .PP
202 .Vb 1
203 \&    package MyApp::Controller::Foo;
204 .Ve
205 .PP
206 .Vb 3
207 \&    sub moose : Local {
208 \&        ...
209 \&    }
210 .Ve
211 .PP
212 and the \s-1URI\s0 for the request was \f(CW\*(C`http://.../foo/moose/bah\*(C'\fR, the string \f(CW\*(C`bah\*(C'\fR
213 would be the first and only argument.
214 .PP
215 Arguments get automatically URI-unescaped for you.
216 .Sh "$req\->args"
217 .IX Subsection "$req->args"
218 Shortcut for \*(L"arguments\*(R".
219 .Sh "$req\->base"
220 .IX Subsection "$req->base"
221 Contains the \s-1URI\s0 base. This will always have a trailing slash. Note that the
222 \&\s-1URI\s0 scheme (eg., http vs. https) must be determined through heuristics;
223 depending on your server configuration, it may be incorrect. See \f(CW$req\fR\->secure
224 for more info.
225 .PP
226 If your application was queried with the \s-1URI\s0
227 \&\f(CW\*(C`http://localhost:3000/some/path\*(C'\fR then \f(CW\*(C`base\*(C'\fR is \f(CW\*(C`http://localhost:3000/\*(C'\fR.
228 .Sh "$req\->body"
229 .IX Subsection "$req->body"
230 Returns the message body of the request, as returned by HTTP::Body: a string,
231 unless Content-Type is \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR, \f(CW\*(C`text/xml\*(C'\fR, or
232 \&\f(CW\*(C`multipart/form\-data\*(C'\fR, in which case a File::Temp object is returned.
233 .Sh "$req\->body_parameters"
234 .IX Subsection "$req->body_parameters"
235 Returns a reference to a hash containing body (\s-1POST\s0) parameters. Values can
236 be either a scalar or an arrayref containing scalars.
237 .PP
238 .Vb 2
239 \&    print $c\->request\->body_parameters\->{field};
240 \&    print $c\->request\->body_parameters\->{field}\->[0];
241 .Ve
242 .PP
243 These are the parameters from the \s-1POST\s0 part of the request, if any.
244 .Sh "$req\->body_params"
245 .IX Subsection "$req->body_params"
246 Shortcut for body_parameters.
247 .Sh "$req\->content_encoding"
248 .IX Subsection "$req->content_encoding"
249 Shortcut for \f(CW$req\fR\->headers\->content_encoding.
250 .Sh "$req\->content_length"
251 .IX Subsection "$req->content_length"
252 Shortcut for \f(CW$req\fR\->headers\->content_length.
253 .Sh "$req\->content_type"
254 .IX Subsection "$req->content_type"
255 Shortcut for \f(CW$req\fR\->headers\->content_type.
256 .Sh "$req\->cookie"
257 .IX Subsection "$req->cookie"
258 A convenient method to access \f(CW$req\fR\->cookies.
259 .PP
260 .Vb 2
261 \&    $cookie  = $c\->request\->cookie('name');
262 \&    @cookies = $c\->request\->cookie;
263 .Ve
264 .Sh "$req\->cookies"
265 .IX Subsection "$req->cookies"
266 Returns a reference to a hash containing the cookies.
267 .PP
268 .Vb 1
269 \&    print $c\->request\->cookies\->{mycookie}\->value;
270 .Ve
271 .PP
272 The cookies in the hash are indexed by name, and the values are CGI::Simple::Cookie
273 objects.
274 .Sh "$req\->header"
275 .IX Subsection "$req->header"
276 Shortcut for \f(CW$req\fR\->headers\->header.
277 .Sh "$req\->headers"
278 .IX Subsection "$req->headers"
279 Returns an HTTP::Headers object containing the headers for the current request.
280 .PP
281 .Vb 1
282 \&    print $c\->request\->headers\->header('X\-Catalyst');
283 .Ve
284 .Sh "$req\->hostname"
285 .IX Subsection "$req->hostname"
286 Returns the hostname of the client.
287 .Sh "$req\->input"
288 .IX Subsection "$req->input"
289 Alias for \f(CW$req\fR\->body.
290 .Sh "$req\->query_keywords"
291 .IX Subsection "$req->query_keywords"
292 Contains the keywords portion of a query string, when no '=' signs are
293 present.
294 .PP
295 .Vb 1
296 \&    http://localhost/path?some+keywords
297 .Ve
298 .PP
299 .Vb 1
300 \&    $c\->request\->query_keywords will contain 'some keywords'
301 .Ve
302 .Sh "$req\->match"
303 .IX Subsection "$req->match"
304 This contains the matching part of a Regex action. Otherwise
305 it returns the same as 'action', except for default actions,
306 which return an empty string.
307 .Sh "$req\->method"
308 .IX Subsection "$req->method"
309 Contains the request method (\f(CW\*(C`GET\*(C'\fR, \f(CW\*(C`POST\*(C'\fR, \f(CW\*(C`HEAD\*(C'\fR, etc).
310 .Sh "$req\->param"
311 .IX Subsection "$req->param"
312 Returns \s-1GET\s0 and \s-1POST\s0 parameters with a \s-1CGI\s0.pm\-compatible param method. This
313 is an alternative method for accessing parameters in \f(CW$c\fR\->req\->parameters.
314 .PP
315 .Vb 3
316 \&    $value  = $c\->request\->param( 'foo' );
317 \&    @values = $c\->request\->param( 'foo' );
318 \&    @params = $c\->request\->param;
319 .Ve
320 .PP
321 Like \s-1CGI\s0, and \fBunlike\fR earlier versions of Catalyst, passing multiple
322 arguments to this method, like this:
323 .PP
324 .Vb 1
325 \&    $c\->request\->param( 'foo', 'bar', 'gorch', 'quxx' );
326 .Ve
327 .PP
328 will set the parameter \f(CW\*(C`foo\*(C'\fR to the multiple values \f(CW\*(C`bar\*(C'\fR, \f(CW\*(C`gorch\*(C'\fR and
329 \&\f(CW\*(C`quxx\*(C'\fR. Previously this would have added \f(CW\*(C`bar\*(C'\fR as another value to \f(CW\*(C`foo\*(C'\fR
330 (creating it if it didn't exist before), and \f(CW\*(C`quxx\*(C'\fR as another value for
331 \&\f(CW\*(C`gorch\*(C'\fR.
332 .PP
333 \&\fB\s-1NOTE\s0\fR this is considered a legacy interface and care should be taken when
334 using it. \f(CW\*(C`scalar $c\->req\->param( 'foo' )\*(C'\fR will return only the first
335 \&\f(CW\*(C`foo\*(C'\fR param even if multiple are present; \f(CW\*(C`$c\->req\->param( 'foo' )\*(C'\fR will
336 return a list of as many are present, which can have unexpected consequences
337 when writing code of the form:
338 .PP
339 .Vb 4
340 \&    $foo\->bar(
341 \&        a => 'b',
342 \&        baz => $c\->req\->param( 'baz' ),
343 \&    );
344 .Ve
345 .PP
346 If multiple \f(CW\*(C`baz\*(C'\fR parameters are provided this code might corrupt data or
347 cause a hash initialization error. For a more straightforward interface see
348 \&\f(CW\*(C`$c\->req\->parameters\*(C'\fR.
349 .Sh "$req\->parameters"
350 .IX Subsection "$req->parameters"
351 Returns a reference to a hash containing \s-1GET\s0 and \s-1POST\s0 parameters. Values can
352 be either a scalar or an arrayref containing scalars.
353 .PP
354 .Vb 2
355 \&    print $c\->request\->parameters\->{field};
356 \&    print $c\->request\->parameters\->{field}\->[0];
357 .Ve
358 .PP
359 This is the combination of \f(CW\*(C`query_parameters\*(C'\fR and \f(CW\*(C`body_parameters\*(C'\fR.
360 .Sh "$req\->params"
361 .IX Subsection "$req->params"
362 Shortcut for \f(CW$req\fR\->parameters.
363 .Sh "$req\->path"
364 .IX Subsection "$req->path"
365 Returns the path, i.e. the part of the \s-1URI\s0 after \f(CW$req\fR\->base, for the current request.
366 .Sh "$req\->path_info"
367 .IX Subsection "$req->path_info"
368 Alias for path, added for compatibility with \s-1CGI\s0.
369 .Sh "$req\->protocol"
370 .IX Subsection "$req->protocol"
371 Returns the protocol (\s-1HTTP/1\s0.0 or \s-1HTTP/1\s0.1) used for the current request.
372 .Sh "$req\->query_parameters"
373 .IX Subsection "$req->query_parameters"
374 .Sh "$req\->query_params"
375 .IX Subsection "$req->query_params"
376 Returns a reference to a hash containing query string (\s-1GET\s0) parameters. Values can
377 be either a scalar or an arrayref containing scalars.
378 .PP
379 .Vb 2
380 \&    print $c\->request\->query_parameters\->{field};
381 \&    print $c\->request\->query_parameters\->{field}\->[0];
382 .Ve
383 .Sh "$req\->read( [$maxlength] )"
384 .IX Subsection "$req->read( [$maxlength] )"
385 Reads a chunk of data from the request body. This method is intended to be
386 used in a while loop, reading \f(CW$maxlength\fR bytes on every call. \f(CW$maxlength\fR
387 defaults to the size of the request if not specified.
388 .PP
389 You have to set MyApp\->config(parse_on_demand => 1) to use this directly.
390 .Sh "$req\->referer"
391 .IX Subsection "$req->referer"
392 Shortcut for \f(CW$req\fR\->headers\->referer. Returns the referring page.
393 .Sh "$req\->secure"
394 .IX Subsection "$req->secure"
395 Returns true or false, indicating whether the connection is secure
396 (https). Note that the \s-1URI\s0 scheme (eg., http vs. https) must be determined
397 through heuristics, and therefore the reliablity of \f(CW$req\fR\->secure will depend
398 on your server configuration. If you are serving secure pages on the standard
399 \&\s-1SSL\s0 port (443) and/or setting the \s-1HTTPS\s0 environment variable, \f(CW$req\fR\->secure
400 should be valid.
401 .Sh "$req\->captures"
402 .IX Subsection "$req->captures"
403 Returns a reference to an array containing captured args from chained
404 actions or regex captures.
405 .PP
406 .Vb 1
407 \&    my @captures = @{ $c\->request\->captures };
408 .Ve
409 .Sh "$req\->snippets"
410 .IX Subsection "$req->snippets"
411 \&\f(CW\*(C`captures\*(C'\fR used to be called snippets. This is still available for backwards
412 compatibility, but is considered deprecated.
413 .Sh "$req\->upload"
414 .IX Subsection "$req->upload"
415 A convenient method to access \f(CW$req\fR\->uploads.
416 .PP
417 .Vb 3
418 \&    $upload  = $c\->request\->upload('field');
419 \&    @uploads = $c\->request\->upload('field');
420 \&    @fields  = $c\->request\->upload;
421 .Ve
422 .PP
423 .Vb 3
424 \&    for my $upload ( $c\->request\->upload('field') ) {
425 \&        print $upload\->filename;
426 \&    }
427 .Ve
428 .Sh "$req\->uploads"
429 .IX Subsection "$req->uploads"
430 Returns a reference to a hash containing uploads. Values can be either a
431 Catalyst::Request::Upload object, or an arrayref of
432 Catalyst::Request::Upload objects.
433 .PP
434 .Vb 2
435 \&    my $upload = $c\->request\->uploads\->{field};
436 \&    my $upload = $c\->request\->uploads\->{field}\->[0];
437 .Ve
438 .Sh "$req\->uri"
439 .IX Subsection "$req->uri"
440 Returns a \s-1URI\s0 object for the current request. Stringifies to the \s-1URI\s0 text.
441 .ie n .Sh "$req\->mangle_params( { key => 'value' }, $appendmode);"
442 .el .Sh "$req\->mangle_params( { key => 'value' }, \f(CW$appendmode\fP);"
443 .IX Subsection "$req->mangle_params( { key => 'value' }, $appendmode);"
444 Returns a hashref of parameters stemming from the current request's params,
445 plus the ones supplied.  Keys for which no current param exists will be
446 added, keys with undefined values will be removed and keys with existing
447 params will be replaced.  Note that you can supply a true value as the final
448 argument to change behavior with regards to existing parameters, appending
449 values rather than replacing them.
450 .PP
451 A quick example:
452 .PP
453 .Vb 3
454 \&  # URI query params foo=1
455 \&  my $hashref = $req\->mangle_params({ foo => 2 });
456 \&  # Result is query params of foo=2
457 .Ve
458 .PP
459 versus append mode:
460 .PP
461 .Vb 3
462 \&  # URI query params foo=1
463 \&  my $hashref = $req\->mangle_params({ foo => 2 }, 1);
464 \&  # Result is query params of foo=1&foo=2
465 .Ve
466 .PP
467 This is the code behind \f(CW\*(C`uri_with\*(C'\fR.
468 .Sh "$req\->uri_with( { key => 'value' } );"
469 .IX Subsection "$req->uri_with( { key => 'value' } );"
470 Returns a rewritten \s-1URI\s0 object for the current request. Key/value pairs
471 passed in will override existing parameters. You can remove an existing
472 parameter by passing in an undef value. Unmodified pairs will be
473 preserved.
474 .PP
475 You may also pass an optional second parameter that puts \f(CW\*(C`uri_with\*(C'\fR into
476 append mode:
477 .PP
478 .Vb 1
479 \&  $req\->uri_with( { key => 'value' }, { mode => 'append' } );
480 .Ve
481 .PP
482 See \f(CW\*(C`mangle_params\*(C'\fR for an explanation of this behavior.
483 .Sh "$req\->user"
484 .IX Subsection "$req->user"
485 Returns the currently logged in user. \fBHighly deprecated\fR, do not call,
486 this will be removed in version 5.81. To retrieve the currently authenticated
487 user, see \f(CW\*(C`$c\->user\*(C'\fR and \f(CW\*(C`$c\->user_exists\*(C'\fR in
488 Catalyst::Plugin::Authentication. For the \f(CW\*(C`REMOTE_USER\*(C'\fR provided by the
489 webserver, see \f(CW\*(C`$req\->remote_user\*(C'\fR below.
490 .Sh "$req\->remote_user"
491 .IX Subsection "$req->remote_user"
492 Returns the value of the \f(CW\*(C`REMOTE_USER\*(C'\fR environment variable.
493 .Sh "$req\->user_agent"
494 .IX Subsection "$req->user_agent"
495 Shortcut to \f(CW$req\fR\->headers\->user_agent. Returns the user agent (browser)
496 version string.
497 .Sh "meta"
498 .IX Subsection "meta"
499 Provided by Moose
500 .SH "AUTHORS"
501 .IX Header "AUTHORS"
502 Catalyst Contributors, see Catalyst.pm
503 .SH "COPYRIGHT"
504 .IX Header "COPYRIGHT"
505 This library is free software. You can redistribute it and/or modify
506 it under the same terms as Perl itself.