local-lib5/man/man3/Catalyst.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 3"
 132 .TH Catalyst 3 "2009-12-02" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Catalyst \- The Elegant MVC Web Application Framework
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 See the Catalyst::Manual distribution for comprehensive
 138 documentation and tutorials.
 139 .PP
 140 .Vb 3
 141 \&    # Install Catalyst::Devel for helpers and other development tools
 142 \&    # use the helper to create a new application
 143 \&    catalyst.pl MyApp
 144 .Ve
 145 .PP
 146 .Vb 4
 147 \&    # add models, views, controllers
 148 \&    script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
 149 \&    script/myapp_create.pl view MyTemplate TT
 150 \&    script/myapp_create.pl controller Search
 151 .Ve
 152 .PP
 153 .Vb 3
 154 \&    # built in testserver \-\- use \-r to restart automatically on changes
 155 \&    # \-\-help to see all available options
 156 \&    script/myapp_server.pl
 157 .Ve
 158 .PP
 159 .Vb 2
 160 \&    # command line testing interface
 161 \&    script/myapp_test.pl /yada
 162 .Ve
 163 .PP
 164 .Vb 2
 165 \&    ### in lib/MyApp.pm
 166 \&    use Catalyst qw/\-Debug/; # include plugins here as well
 167 .Ve
 168 .PP
 169 .Vb 12
 170 \&    ### In lib/MyApp/Controller/Root.pm (autocreated)
 171 \&    sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
 172 \&        my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
 173 \&        $c\->stash\->{template} = 'foo.tt'; # set the template
 174 \&        # lookup something from db \-\- stash vars are passed to TT
 175 \&        $c\->stash\->{data} =
 176 \&          $c\->model('Database::Foo')\->search( { country => $args[0] } );
 177 \&        if ( $c\->req\->params\->{bar} ) { # access GET or POST parameters
 178 \&            $c\->forward( 'bar' ); # process another action
 179 \&            # do something else after forward returns
 180 \&        }
 181 \&    }
 182 .Ve
 183 .PP
 184 .Vb 4
 185 \&    # The foo.tt TT template can use the stash data from the database
 186 \&    [% WHILE (item = data.next) %]
 187 \&        [% item.foo %]
 188 \&    [% END %]
 189 .Ve
 190 .PP
 191 .Vb 2
 192 \&    # called for /bar/of/soap, /bar/of/soap/10, etc.
 193 \&    sub bar : Path('/bar/of/soap') { ... }
 194 .Ve
 195 .PP
 196 .Vb 9
 197 \&    # called for all actions, from the top\-most controller downwards
 198 \&    sub auto : Private {
 199 \&        my ( $self, $c ) = @_;
 200 \&        if ( !$c\->user_exists ) { # Catalyst::Plugin::Authentication
 201 \&            $c\->res\->redirect( '/login' ); # require login
 202 \&            return 0; # abort request and go immediately to end()
 203 \&        }
 204 \&        return 1; # success; carry on to next action
 205 \&    }
 206 .Ve
 207 .PP
 208 .Vb 7
 209 \&    # called after all actions are finished
 210 \&    sub end : Private {
 211 \&        my ( $self, $c ) = @_;
 212 \&        if ( scalar @{ $c\->error } ) { ... } # handle errors
 213 \&        return if $c\->res\->body; # already have a response
 214 \&        $c\->forward( 'MyApp::View::TT' ); # render template
 215 \&    }
 216 .Ve
 217 .PP
 218 .Vb 3
 219 \&    ### in MyApp/Controller/Foo.pm
 220 \&    # called for /foo/bar
 221 \&    sub bar : Local { ... }
 222 .Ve
 223 .PP
 224 .Vb 2
 225 \&    # called for /blargle
 226 \&    sub blargle : Global { ... }
 227 .Ve
 228 .PP
 229 .Vb 2
 230 \&    # an index action matches /foo, but not /foo/1, etc.
 231 \&    sub index : Private { ... }
 232 .Ve
 233 .PP
 234 .Vb 3
 235 \&    ### in MyApp/Controller/Foo/Bar.pm
 236 \&    # called for /foo/bar/baz
 237 \&    sub baz : Local { ... }
 238 .Ve
 239 .PP
 240 .Vb 2
 241 \&    # first Root auto is called, then Foo auto, then this
 242 \&    sub auto : Private { ... }
 243 .Ve
 244 .PP
 245 .Vb 6
 246 \&    # powerful regular expression paths are also possible
 247 \&    sub details : Regex('^product/(\ew+)/details$') {
 248 \&        my ( $self, $c ) = @_;
 249 \&        # extract the (\ew+) from the URI
 250 \&        my $product = $c\->req\->captures\->[0];
 251 \&    }
 252 .Ve
 253 .PP
 254 See Catalyst::Manual::Intro for additional information.
 255 .SH "DESCRIPTION"
 256 .IX Header "DESCRIPTION"
 257 Catalyst is a modern framework for making web applications without the
 258 pain usually associated with this process. This document is a reference
 259 to the main Catalyst application. If you are a new user, we suggest you
 260 start with Catalyst::Manual::Tutorial or Catalyst::Manual::Intro.
 261 .PP
 262 See Catalyst::Manual for more documentation.
 263 .PP
 264 Catalyst plugins can be loaded by naming them as arguments to the \*(L"use
 265 Catalyst\*(R" statement. Omit the \f(CW\*(C`Catalyst::Plugin::\*(C'\fR prefix from the
 266 plugin name, i.e., \f(CW\*(C`Catalyst::Plugin::My::Module\*(C'\fR becomes
 267 \&\f(CW\*(C`My::Module\*(C'\fR.
 268 .PP
 269 .Vb 1
 270 \&    use Catalyst qw/My::Module/;
 271 .Ve
 272 .PP
 273 If your plugin starts with a name other than \f(CW\*(C`Catalyst::Plugin::\*(C'\fR, you can
 274 fully qualify the name by using a unary plus:
 275 .PP
 276 .Vb 4
 277 \&    use Catalyst qw/
 278 \&        My::Module
 279 \&        +Fully::Qualified::Plugin::Name
 280 \&    /;
 281 .Ve
 282 .PP
 283 Special flags like \f(CW\*(C`\-Debug\*(C'\fR and \f(CW\*(C`\-Engine\*(C'\fR can also be specified as
 284 arguments when Catalyst is loaded:
 285 .PP
 286 .Vb 1
 287 \&    use Catalyst qw/\-Debug My::Module/;
 288 .Ve
 289 .PP
 290 The position of plugins and flags in the chain is important, because
 291 they are loaded in the order in which they appear.
 292 .PP
 293 The following flags are supported:
 294 .Sh "\-Debug"
 295 .IX Subsection "-Debug"
 296 Enables debug output. You can also force this setting from the system
 297 environment with \s-1CATALYST_DEBUG\s0 or <\s-1MYAPP\s0>_DEBUG. The environment
 298 settings override the application, with <\s-1MYAPP\s0>_DEBUG having the highest
 299 priority.
 300 .Sh "\-Engine"
 301 .IX Subsection "-Engine"
 302 Forces Catalyst to use a specific engine. Omit the
 303 \&\f(CW\*(C`Catalyst::Engine::\*(C'\fR prefix of the engine name, i.e.:
 304 .PP
 305 .Vb 1
 306 \&    use Catalyst qw/\-Engine=CGI/;
 307 .Ve
 308 .Sh "\-Home"
 309 .IX Subsection "-Home"
 310 Forces Catalyst to use a specific home directory, e.g.:
 311 .PP
 312 .Vb 1
 313 \&    use Catalyst qw[\-Home=/usr/mst];
 314 .Ve
 315 .PP
 316 This can also be done in the shell environment by setting either the
 317 \&\f(CW\*(C`CATALYST_HOME\*(C'\fR environment variable or \f(CW\*(C`MYAPP_HOME\*(C'\fR; where \f(CW\*(C`MYAPP\*(C'\fR
 318 is replaced with the uppercased name of your application, any \*(L"::\*(R" in
 319 the name will be replaced with underscores, e.g. MyApp::Web should use
 320 \&\s-1MYAPP_WEB_HOME\s0. If both variables are set, the \s-1MYAPP_HOME\s0 one will be used.
 321 .Sh "\-Log"
 322 .IX Subsection "-Log"
 323 .Vb 1
 324 \&    use Catalyst '\-Log=warn,fatal,error';
 325 .Ve
 326 .PP
 327 Specifies a comma-delimited list of log levels.
 328 .Sh "\-Stats"
 329 .IX Subsection "-Stats"
 330 Enables statistics collection and reporting. You can also force this setting
 331 from the system environment with \s-1CATALYST_STATS\s0 or <\s-1MYAPP\s0>_STATS. The
 332 environment settings override the application, with <\s-1MYAPP\s0>_STATS having the
 333 highest priority.
 334 .PP
 335 e.g.
 336 .PP
 337 .Vb 1
 338 \&   use Catalyst qw/\-Stats=1/
 339 .Ve
 340 .SH "METHODS"
 341 .IX Header "METHODS"
 342 .Sh "\s-1INFORMATION\s0 \s-1ABOUT\s0 \s-1THE\s0 \s-1CURRENT\s0 \s-1REQUEST\s0"
 343 .IX Subsection "INFORMATION ABOUT THE CURRENT REQUEST"
 344 .Sh "$c\->action"
 345 .IX Subsection "$c->action"
 346 Returns a Catalyst::Action object for the current action, which
 347 stringifies to the action name. See Catalyst::Action.
 348 .Sh "$c\->namespace"
 349 .IX Subsection "$c->namespace"
 350 Returns the namespace of the current action, i.e., the \s-1URI\s0 prefix
 351 corresponding to the controller of the current action. For example:
 352 .PP
 353 .Vb 2
 354 \&    # in Controller::Foo::Bar
 355 \&    $c\->namespace; # returns 'foo/bar';
 356 .Ve
 357 .Sh "$c\->request"
 358 .IX Subsection "$c->request"
 359 .Sh "$c\->req"
 360 .IX Subsection "$c->req"
 361 Returns the current Catalyst::Request object, giving access to
 362 information about the current client request (including parameters,
 363 cookies, \s-1HTTP\s0 headers, etc.). See Catalyst::Request.
 364 .Sh "\s-1REQUEST\s0 \s-1FLOW\s0 \s-1HANDLING\s0"
 365 .IX Subsection "REQUEST FLOW HANDLING"
 366 .ie n .Sh "$c\->forward( $action [, \e@arguments ] )"
 367 .el .Sh "$c\->forward( \f(CW$action\fP [, \e@arguments ] )"
 368 .IX Subsection "$c->forward( $action [, @arguments ] )"
 369 .ie n .Sh "$c\->forward( $class\fP, \f(CW$method, [, \e@arguments ] )"
 370 .el .Sh "$c\->forward( \f(CW$class\fP, \f(CW$method\fP, [, \e@arguments ] )"
 371 .IX Subsection "$c->forward( $class, $method, [, @arguments ] )"
 372 Forwards processing to another action, by its private name. If you give a
 373 class name but no method, \f(CW\*(C`process()\*(C'\fR is called. You may also optionally
 374 pass arguments in an arrayref. The action will receive the arguments in
 375 \&\f(CW@_\fR and \f(CW\*(C`$c\->req\->args\*(C'\fR. Upon returning from the function,
 376 \&\f(CW\*(C`$c\->req\->args\*(C'\fR will be restored to the previous values.
 377 .PP
 378 Any data \f(CW\*(C`return\*(C'\fRed from the action forwarded to, will be returned by the
 379 call to forward.
 380 .PP
 381 .Vb 4
 382 \&    my $foodata = $c\->forward('/foo');
 383 \&    $c\->forward('index');
 384 \&    $c\->forward(qw/MyApp::Model::DBIC::Foo do_stuff/);
 385 \&    $c\->forward('MyApp::View::TT');
 386 .Ve
 387 .PP
 388 Note that forward implies
 389 an \f(CW\*(C`eval { }\*(C'\fR around the call (actually
 390 execute does), thus de-fatalizing
 391 all 'dies' within the called action. If you want \f(CW\*(C`die\*(C'\fR to propagate you
 392 need to do something like:
 393 .PP
 394 .Vb 2
 395 \&    $c\->forward('foo');
 396 \&    die $c\->error if $c\->error;
 397 .Ve
 398 .PP
 399 Or make sure to always return true values from your actions and write
 400 your code like this:
 401 .PP
 402 .Vb 1
 403 \&    $c\->forward('foo') || return;
 404 .Ve
 405 .PP
 406 Another note is that \f(CW\*(C`$c\->forward\*(C'\fR always returns a scalar because it
 407 actually returns \f(CW$c\fR\->state which operates in a scalar context.
 408 Thus, something like:
 409 .PP
 410 .Vb 1
 411 \&    return @array;
 412 .Ve
 413 .PP
 414 in an action that is forwarded to is going to return a scalar,
 415 i.e. how many items are in that array, which is probably not what you want.
 416 If you need to return an array then return a reference to it,
 417 or stash it like so:
 418 .PP
 419 .Vb 1
 420 \&    $c\->stash\->{array} = \e@array;
 421 .Ve
 422 .PP
 423 and access it from the stash.
 424 .ie n .Sh "$c\->detach( $action [, \e@arguments ] )"
 425 .el .Sh "$c\->detach( \f(CW$action\fP [, \e@arguments ] )"
 426 .IX Subsection "$c->detach( $action [, @arguments ] )"
 427 .ie n .Sh "$c\->detach( $class\fP, \f(CW$method, [, \e@arguments ] )"
 428 .el .Sh "$c\->detach( \f(CW$class\fP, \f(CW$method\fP, [, \e@arguments ] )"
 429 .IX Subsection "$c->detach( $class, $method, [, @arguments ] )"
 430 .Sh "$c\->\fIdetach()\fP"
 431 .IX Subsection "$c->detach()"
 432 The same as forward, but
 433 doesn't return to the previous action when processing is finished.
 434 .PP
 435 When called with no arguments it escapes the processing chain entirely.
 436 .ie n .Sh "$c\->visit( $action [, \e@captures, \e@arguments ] )"
 437 .el .Sh "$c\->visit( \f(CW$action\fP [, \e@captures, \e@arguments ] )"
 438 .IX Subsection "$c->visit( $action [, @captures, @arguments ] )"
 439 .ie n .Sh "$c\->visit( $class\fP, \f(CW$method, [, \e@captures, \e@arguments ] )"
 440 .el .Sh "$c\->visit( \f(CW$class\fP, \f(CW$method\fP, [, \e@captures, \e@arguments ] )"
 441 .IX Subsection "$c->visit( $class, $method, [, @captures, @arguments ] )"
 442 Almost the same as forward,
 443 but does a full dispatch, instead of just calling the new \f(CW$action\fR /
 444 \&\f(CW\*(C`$class\->$method\*(C'\fR. This means that \f(CW\*(C`begin\*(C'\fR, \f(CW\*(C`auto\*(C'\fR and the method
 445 you go to are called, just like a new request.
 446 .PP
 447 In addition both \f(CW\*(C`$c\->action\*(C'\fR and \f(CW\*(C`$c\->namespace\*(C'\fR are localized.
 448 This means, for example, that \f(CW\*(C`$c\->action\*(C'\fR methods such as
 449 name, class and
 450 reverse return information for the visited action
 451 when they are invoked within the visited action.  This is different from the
 452 behavior of forward, which
 453 continues to use the \f(CW$c\fR\->action object from the caller action even when
 454 invoked from the callee.
 455 .PP
 456 \&\f(CW\*(C`$c\->stash\*(C'\fR is kept unchanged.
 457 .PP
 458 In effect, visit
 459 allows you to \*(L"wrap\*(R" another action, just as it would have been called by
 460 dispatching from a \s-1URL\s0, while the analogous
 461 go allows you to
 462 transfer control to another action as if it had been reached directly from a \s-1URL\s0.
 463 .ie n .Sh "$c\->go( $action [, \e@captures, \e@arguments ] )"
 464 .el .Sh "$c\->go( \f(CW$action\fP [, \e@captures, \e@arguments ] )"
 465 .IX Subsection "$c->go( $action [, @captures, @arguments ] )"
 466 .ie n .Sh "$c\->go( $class\fP, \f(CW$method, [, \e@captures, \e@arguments ] )"
 467 .el .Sh "$c\->go( \f(CW$class\fP, \f(CW$method\fP, [, \e@captures, \e@arguments ] )"
 468 .IX Subsection "$c->go( $class, $method, [, @captures, @arguments ] )"
 469 The relationship between \f(CW\*(C`go\*(C'\fR and
 470 visit is the same as
 471 the relationship between
 472 forward and
 473 detach. Like \f(CW\*(C`$c\->visit\*(C'\fR,
 474 \&\f(CW\*(C`$c\->go\*(C'\fR will perform a full dispatch on the specified action or method,
 475 with localized \f(CW\*(C`$c\->action\*(C'\fR and \f(CW\*(C`$c\->namespace\*(C'\fR. Like \f(CW\*(C`detach\*(C'\fR,
 476 \&\f(CW\*(C`go\*(C'\fR escapes the processing of the current request chain on completion, and
 477 does not return to its caller.
 478 .Sh "$c\->response"
 479 .IX Subsection "$c->response"
 480 .Sh "$c\->res"
 481 .IX Subsection "$c->res"
 482 Returns the current Catalyst::Response object, see there for details.
 483 .Sh "$c\->stash"
 484 .IX Subsection "$c->stash"
 485 Returns a hashref to the stash, which may be used to store data and pass
 486 it between components during a request. You can also set hash keys by
 487 passing arguments. The stash is automatically sent to the view. The
 488 stash is cleared at the end of a request; it cannot be used for
 489 persistent storage (for this you must use a session; see
 490 Catalyst::Plugin::Session for a complete system integrated with
 491 Catalyst).
 492 .PP
 493 .Vb 3
 494 \&    $c\->stash\->{foo} = $bar;
 495 \&    $c\->stash( { moose => 'majestic', qux => 0 } );
 496 \&    $c\->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
 497 .Ve
 498 .PP
 499 .Vb 2
 500 \&    # stash is automatically passed to the view for use in a template
 501 \&    $c\->forward( 'MyApp::View::TT' );
 502 .Ve
 503 .Sh "$c\->error"
 504 .IX Subsection "$c->error"
 505 .Sh "$c\->error($error, ...)"
 506 .IX Subsection "$c->error($error, ...)"
 507 .Sh "$c\->error($arrayref)"
 508 .IX Subsection "$c->error($arrayref)"
 509 Returns an arrayref containing error messages.  If Catalyst encounters an
 510 error while processing a request, it stores the error in \f(CW$c\fR\->error.  This
 511 method should only be used to store fatal error messages.
 512 .PP
 513 .Vb 1
 514 \&    my @error = @{ $c\->error };
 515 .Ve
 516 .PP
 517 Add a new error.
 518 .PP
 519 .Vb 1
 520 \&    $c\->error('Something bad happened');
 521 .Ve
 522 .Sh "$c\->state"
 523 .IX Subsection "$c->state"
 524 Contains the return value of the last executed action.
 525 Note that << \f(CW$c\fR\->state >> operates in a scalar context which means that all
 526 values it returns are scalar.
 527 .Sh "$c\->clear_errors"
 528 .IX Subsection "$c->clear_errors"
 529 Clear errors.  You probably don't want to clear the errors unless you are
 530 implementing a custom error screen.
 531 .PP
 532 This is equivalent to running
 533 .PP
 534 .Vb 1
 535 \&    $c\->error(0);
 536 .Ve
 537 .Sh "\s-1COMPONENT\s0 \s-1ACCESSORS\s0"
 538 .IX Subsection "COMPONENT ACCESSORS"
 539 .Sh "$c\->controller($name)"
 540 .IX Subsection "$c->controller($name)"
 541 Gets a Catalyst::Controller instance by name.
 542 .PP
 543 .Vb 1
 544 \&    $c\->controller('Foo')\->do_stuff;
 545 .Ve
 546 .PP
 547 If the name is omitted, will return the controller for the dispatched
 548 action.
 549 .PP
 550 If you want to search for controllers, pass in a regexp as the argument.
 551 .PP
 552 .Vb 2
 553 \&    # find all controllers that start with Foo
 554 \&    my @foo_controllers = $c\->controller(qr{^Foo});
 555 .Ve
 556 .Sh "$c\->model($name)"
 557 .IX Subsection "$c->model($name)"
 558 Gets a Catalyst::Model instance by name.
 559 .PP
 560 .Vb 1
 561 \&    $c\->model('Foo')\->do_stuff;
 562 .Ve
 563 .PP
 564 Any extra arguments are directly passed to \s-1ACCEPT_CONTEXT\s0.
 565 .PP
 566 If the name is omitted, it will look for
 567  \- a model object in \f(CW$c\fR\->stash\->{current_model_instance}, then
 568  \- a model name in \f(CW$c\fR\->stash\->{current_model}, then
 569  \- a config setting 'default_model', or
 570  \- check if there is only one model, and return it if that's the case.
 571 .PP
 572 If you want to search for models, pass in a regexp as the argument.
 573 .PP
 574 .Vb 2
 575 \&    # find all models that start with Foo
 576 \&    my @foo_models = $c\->model(qr{^Foo});
 577 .Ve
 578 .Sh "$c\->view($name)"
 579 .IX Subsection "$c->view($name)"
 580 Gets a Catalyst::View instance by name.
 581 .PP
 582 .Vb 1
 583 \&    $c\->view('Foo')\->do_stuff;
 584 .Ve
 585 .PP
 586 Any extra arguments are directly passed to \s-1ACCEPT_CONTEXT\s0.
 587 .PP
 588 If the name is omitted, it will look for
 589  \- a view object in \f(CW$c\fR\->stash\->{current_view_instance}, then
 590  \- a view name in \f(CW$c\fR\->stash\->{current_view}, then
 591  \- a config setting 'default_view', or
 592  \- check if there is only one view, and return it if that's the case.
 593 .PP
 594 If you want to search for views, pass in a regexp as the argument.
 595 .PP
 596 .Vb 2
 597 \&    # find all views that start with Foo
 598 \&    my @foo_views = $c\->view(qr{^Foo});
 599 .Ve
 600 .Sh "$c\->controllers"
 601 .IX Subsection "$c->controllers"
 602 Returns the available names which can be passed to \f(CW$c\fR\->controller
 603 .Sh "$c\->models"
 604 .IX Subsection "$c->models"
 605 Returns the available names which can be passed to \f(CW$c\fR\->model
 606 .Sh "$c\->views"
 607 .IX Subsection "$c->views"
 608 Returns the available names which can be passed to \f(CW$c\fR\->view
 609 .Sh "$c\->comp($name)"
 610 .IX Subsection "$c->comp($name)"
 611 .Sh "$c\->component($name)"
 612 .IX Subsection "$c->component($name)"
 613 Gets a component object by name. This method is not recommended,
 614 unless you want to get a specific component by full
 615 class. \f(CW\*(C`$c\->controller\*(C'\fR, \f(CW\*(C`$c\->model\*(C'\fR, and \f(CW\*(C`$c\->view\*(C'\fR
 616 should be used instead.
 617 .PP
 618 If \f(CW$name\fR is a regexp, a list of components matched against the full
 619 component name will be returned.
 620 .PP
 621 If Catalyst can't find a component by name, it will fallback to regex
 622 matching by default. To disable this behaviour set
 623 disable_component_resolution_regex_fallback to a true value.
 624 .PP
 625 .Vb 1
 626 \&    __PACKAGE__\->config( disable_component_resolution_regex_fallback => 1 );
 627 .Ve
 628 .Sh "\s-1CLASS\s0 \s-1DATA\s0 \s-1AND\s0 \s-1HELPER\s0 \s-1CLASSES\s0"
 629 .IX Subsection "CLASS DATA AND HELPER CLASSES"
 630 .Sh "$c\->config"
 631 .IX Subsection "$c->config"
 632 Returns or takes a hashref containing the application's configuration.
 633 .PP
 634 .Vb 1
 635 \&    __PACKAGE__\->config( { db => 'dsn:SQLite:foo.db' } );
 636 .Ve
 637 .PP
 638 You can also use a \f(CW\*(C`YAML\*(C'\fR, \f(CW\*(C`XML\*(C'\fR or Config::General config file
 639 like \f(CW\*(C`myapp.conf\*(C'\fR in your applications home directory. See
 640 Catalyst::Plugin::ConfigLoader.
 641 .PP
 642 \fICascading configuration\fR
 643 .IX Subsection "Cascading configuration"
 644 .PP
 645 The config method is present on all Catalyst components, and configuration
 646 will be merged when an application is started. Configuration loaded with
 647 Catalyst::Plugin::ConfigLoader takes precedence over other configuration,
 648 followed by configuration in your top level \f(CW\*(C`MyApp\*(C'\fR class. These two
 649 configurations are merged, and then configuration data whose hash key matches a
 650 component name is merged with configuration for that component.
 651 .PP
 652 The configuration for a component is then passed to the \f(CW\*(C`new\*(C'\fR method when a
 653 component is constructed.
 654 .PP
 655 For example:
 656 .PP
 657 .Vb 2
 658 \&    MyApp\->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
 659 \&    MyApp::Model::Foo\->config({ quux => 'frob', 'overrides => 'this' });
 660 .Ve
 661 .PP
 662 will mean that \f(CW\*(C`MyApp::Model::Foo\*(C'\fR receives the following data when
 663 constructed:
 664 .PP
 665 .Vb 5
 666 \&    MyApp::Model::Foo\->new({
 667 \&        bar => 'baz',
 668 \&        quux => 'frob',
 669 \&        overrides => 'me',
 670 \&    });
 671 .Ve
 672 .Sh "$c\->log"
 673 .IX Subsection "$c->log"
 674 Returns the logging object instance. Unless it is already set, Catalyst
 675 sets this up with a Catalyst::Log object. To use your own log class,
 676 set the logger with the \f(CW\*(C`_\|_PACKAGE_\|_\->log\*(C'\fR method prior to calling
 677 \&\f(CW\*(C`_\|_PACKAGE_\|_\->setup\*(C'\fR.
 678 .PP
 679 .Vb 2
 680 \& __PACKAGE__\->log( MyLogger\->new );
 681 \& __PACKAGE__\->setup;
 682 .Ve
 683 .PP
 684 And later:
 685 .PP
 686 .Vb 1
 687 \&    $c\->log\->info( 'Now logging with my own logger!' );
 688 .Ve
 689 .PP
 690 Your log class should implement the methods described in
 691 Catalyst::Log.
 692 .Sh "$c\->debug"
 693 .IX Subsection "$c->debug"
 694 Returns 1 if debug mode is enabled, 0 otherwise.
 695 .PP
 696 You can enable debug mode in several ways:
 697 .IP "By calling myapp_server.pl with the \-d flag" 4
 698 .IX Item "By calling myapp_server.pl with the -d flag"
 699 .PD 0
 700 .IP "With the environment variables \s-1MYAPP_DEBUG\s0, or \s-1CATALYST_DEBUG\s0" 4
 701 .IX Item "With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG"
 702 .IP "The \-Debug option in your MyApp.pm" 4
 703 .IX Item "The -Debug option in your MyApp.pm"
 704 .ie n .IP "By declaring ""sub debug { 1 }"" in your MyApp.pm." 4
 705 .el .IP "By declaring \f(CWsub debug { 1 }\fR in your MyApp.pm." 4
 706 .IX Item "By declaring sub debug { 1 } in your MyApp.pm."
 707 .PD
 708 .PP
 709 Calling \f(CW\*(C`$c\->debug(1)\*(C'\fR has no effect.
 710 .Sh "$c\->dispatcher"
 711 .IX Subsection "$c->dispatcher"
 712 Returns the dispatcher instance. See Catalyst::Dispatcher.
 713 .Sh "$c\->engine"
 714 .IX Subsection "$c->engine"
 715 Returns the engine instance. See Catalyst::Engine.
 716 .Sh "\s-1UTILITY\s0 \s-1METHODS\s0"
 717 .IX Subsection "UTILITY METHODS"
 718 .Sh "$c\->path_to(@path)"
 719 .IX Subsection "$c->path_to(@path)"
 720 Merges \f(CW@path\fR with \f(CW\*(C`$c\->config\->{home}\*(C'\fR and returns a
 721 Path::Class::Dir object. Note you can usually use this object as
 722 a filename, but sometimes you will have to explicitly stringify it
 723 yourself by calling the \f(CW\*(C`\->stringify\*(C'\fR method.
 724 .PP
 725 For example:
 726 .PP
 727 .Vb 1
 728 \&    $c\->path_to( 'db', 'sqlite.db' );
 729 .Ve
 730 .ie n .Sh "$c\->plugin( $name\fP, \f(CW$class\fP, \f(CW@args )"
 731 .el .Sh "$c\->plugin( \f(CW$name\fP, \f(CW$class\fP, \f(CW@args\fP )"
 732 .IX Subsection "$c->plugin( $name, $class, @args )"
 733 Helper method for plugins. It creates a class data accessor/mutator and
 734 loads and instantiates the given class.
 735 .PP
 736 .Vb 1
 737 \&    MyApp\->plugin( 'prototype', 'HTML::Prototype' );
 738 .Ve
 739 .PP
 740 .Vb 1
 741 \&    $c\->prototype\->define_javascript_functions;
 742 .Ve
 743 .PP
 744 \&\fBNote:\fR This method of adding plugins is deprecated. The ability
 745 to add plugins like this \fBwill be removed\fR in a Catalyst 5.81.
 746 Please do not use this functionality in new code.
 747 .Sh "MyApp\->setup"
 748 .IX Subsection "MyApp->setup"
 749 Initializes the dispatcher and engine, loads any plugins, and loads the
 750 model, view, and controller components. You may also specify an array
 751 of plugins to load here, if you choose to not load them in the \f(CW\*(C`use
 752 Catalyst\*(C'\fR line.
 753 .PP
 754 .Vb 2
 755 \&    MyApp\->setup;
 756 \&    MyApp\->setup( qw/\-Debug/ );
 757 .Ve
 758 .Sh "$app\->setup_finalize"
 759 .IX Subsection "$app->setup_finalize"
 760 A hook to attach modifiers to.
 761 Using \f(CW\*(C`after setup => sub{};\*(C'\fR doesn't work, because of quirky things done for plugin setup.
 762 Also better than \f(CW\*(C` setup_finished(); \*(C'\fR, as that is a getter method.
 763 .PP
 764 .Vb 1
 765 \&    sub setup_finalize {
 766 .Ve
 767 .PP
 768 .Vb 1
 769 \&        my $app = shift;
 770 .Ve
 771 .PP
 772 .Vb 1
 773 \&        ## do stuff, i.e., determine a primary key column for sessions stored in a DB
 774 .Ve
 775 .PP
 776 .Vb 1
 777 \&        $app\->next::method(@_);
 778 .Ve
 779 .PP
 780 .Vb 1
 781 \&    }
 782 .Ve
 783 .ie n .Sh "$c\->uri_for( $path\fP?, \f(CW@args?, \e%query_values? )"
 784 .el .Sh "$c\->uri_for( \f(CW$path\fP?, \f(CW@args\fP?, \e%query_values? )"
 785 .IX Subsection "$c->uri_for( $path?, @args?, %query_values? )"
 786 .ie n .Sh "$c\->uri_for( $action\fP, \e@captures?, \f(CW@args?, \e%query_values? )"
 787 .el .Sh "$c\->uri_for( \f(CW$action\fP, \e@captures?, \f(CW@args\fP?, \e%query_values? )"
 788 .IX Subsection "$c->uri_for( $action, @captures?, @args?, %query_values? )"
 789 Constructs an absolute \s-1URI\s0 object based on the application root, the
 790 provided path, and the additional arguments and query parameters provided.
 791 When used as a string, provides a textual \s-1URI\s0.
 792 .PP
 793 If no arguments are provided, the \s-1URI\s0 for the current action is returned.
 794 To return the current action and also provide \f(CW@args\fR, use
 795 \&\f(CW\*(C`$c\->uri_for( $c\->action, @args )\*(C'\fR.
 796 .PP
 797 If the first argument is a string, it is taken as a public \s-1URI\s0 path relative
 798 to \f(CW\*(C`$c\->namespace\*(C'\fR (if it doesn't begin with a forward slash) or
 799 relative to the application root (if it does). It is then merged with
 800 \&\f(CW\*(C`$c\->request\->base\*(C'\fR; any \f(CW@args\fR are appended as additional path
 801 components; and any \f(CW%query_values\fR are appended as \f(CW\*(C`?foo=bar\*(C'\fR parameters.
 802 .PP
 803 If the first argument is a Catalyst::Action it represents an action which
 804 will have its path resolved using \f(CW\*(C`$c\->dispatcher\->uri_for_action\*(C'\fR. The
 805 optional \f(CW\*(C`\e@captures\*(C'\fR argument (an arrayref) allows passing the captured
 806 variables that are needed to fill in the paths of Chained and Regex actions;
 807 once the path is resolved, \f(CW\*(C`uri_for\*(C'\fR continues as though a path was
 808 provided, appending any arguments or parameters and creating an absolute
 809 \&\s-1URI\s0.
 810 .PP
 811 The captures for the current request can be found in
 812 \&\f(CW\*(C`$c\->request\->captures\*(C'\fR, and actions can be resolved using
 813 \&\f(CW\*(C`Catalyst::Controller\->action_for($name)\*(C'\fR. If you have a private action
 814 path, use \f(CW\*(C`$c\->uri_for_action\*(C'\fR instead.
 815 .PP
 816 .Vb 3
 817 \&  # Equivalent to $c\->req\->uri
 818 \&  $c\->uri_for($c\->action, $c\->req\->captures,
 819 \&      @{ $c\->req\->args }, $c\->req\->params);
 820 .Ve
 821 .PP
 822 .Vb 2
 823 \&  # For the Foo action in the Bar controller
 824 \&  $c\->uri_for($c\->controller('Bar')\->action_for('Foo'));
 825 .Ve
 826 .PP
 827 .Vb 2
 828 \&  # Path to a static resource
 829 \&  $c\->uri_for('/static/images/logo.png');
 830 .Ve
 831 .ie n .Sh "$c\->uri_for_action( $path\fP, \e@captures?, \f(CW@args?, \e%query_values? )"
 832 .el .Sh "$c\->uri_for_action( \f(CW$path\fP, \e@captures?, \f(CW@args\fP?, \e%query_values? )"
 833 .IX Subsection "$c->uri_for_action( $path, @captures?, @args?, %query_values? )"
 834 .ie n .Sh "$c\->uri_for_action( $action\fP, \e@captures?, \f(CW@args?, \e%query_values? )"
 835 .el .Sh "$c\->uri_for_action( \f(CW$action\fP, \e@captures?, \f(CW@args\fP?, \e%query_values? )"
 836 .IX Subsection "$c->uri_for_action( $action, @captures?, @args?, %query_values? )"
 837 .IP "$path" 4
 838 .IX Item "$path"
 839 A private path to the Catalyst action you want to create a \s-1URI\s0 for.
 840 .Sp
 841 This is a shortcut for calling \f(CW\*(C`$c\->dispatcher\->get_action_by_path($path)\*(C'\fR and passing the resulting \f(CW$action\fR and the remaining arguments to \f(CW\*(C`$c\->uri_for\*(C'\fR.
 842 .Sp
 843 You can also pass in a Catalyst::Action object, in which case it is passed to
 844 \&\f(CW\*(C`$c\->uri_for\*(C'\fR.
 845 .Sh "$c\->welcome_message"
 846 .IX Subsection "$c->welcome_message"
 847 Returns the Catalyst welcome \s-1HTML\s0 page.
 848 .SH "INTERNAL METHODS"
 849 .IX Header "INTERNAL METHODS"
 850 These methods are not meant to be used by end users.
 851 .Sh "$c\->components"
 852 .IX Subsection "$c->components"
 853 Returns a hash of components.
 854 .Sh "$c\->context_class"
 855 .IX Subsection "$c->context_class"
 856 Returns or sets the context class.
 857 .Sh "$c\->counter"
 858 .IX Subsection "$c->counter"
 859 Returns a hashref containing coderefs and execution counts (needed for
 860 deep recursion detection).
 861 .Sh "$c\->depth"
 862 .IX Subsection "$c->depth"
 863 Returns the number of actions on the current internal execution stack.
 864 .Sh "$c\->dispatch"
 865 .IX Subsection "$c->dispatch"
 866 Dispatches a request to actions.
 867 .Sh "$c\->dispatcher_class"
 868 .IX Subsection "$c->dispatcher_class"
 869 Returns or sets the dispatcher class.
 870 .Sh "$c\->dump_these"
 871 .IX Subsection "$c->dump_these"
 872 Returns a list of 2\-element array references (name, structure) pairs
 873 that will be dumped on the error page in debug mode.
 874 .Sh "$c\->engine_class"
 875 .IX Subsection "$c->engine_class"
 876 Returns or sets the engine class.
 877 .ie n .Sh "$c\->execute( $class\fP, \f(CW$coderef )"
 878 .el .Sh "$c\->execute( \f(CW$class\fP, \f(CW$coderef\fP )"
 879 .IX Subsection "$c->execute( $class, $coderef )"
 880 Execute a coderef in given class and catch exceptions. Errors are available
 881 via \f(CW$c\fR\->error.
 882 .Sh "$c\->finalize"
 883 .IX Subsection "$c->finalize"
 884 Finalizes the request.
 885 .Sh "$c\->finalize_body"
 886 .IX Subsection "$c->finalize_body"
 887 Finalizes body.
 888 .Sh "$c\->finalize_cookies"
 889 .IX Subsection "$c->finalize_cookies"
 890 Finalizes cookies.
 891 .Sh "$c\->finalize_error"
 892 .IX Subsection "$c->finalize_error"
 893 Finalizes error.
 894 .Sh "$c\->finalize_headers"
 895 .IX Subsection "$c->finalize_headers"
 896 Finalizes headers.
 897 .Sh "$c\->finalize_output"
 898 .IX Subsection "$c->finalize_output"
 899 An alias for finalize_body.
 900 .Sh "$c\->finalize_read"
 901 .IX Subsection "$c->finalize_read"
 902 Finalizes the input after reading is complete.
 903 .Sh "$c\->finalize_uploads"
 904 .IX Subsection "$c->finalize_uploads"
 905 Finalizes uploads. Cleans up any temporary files.
 906 .ie n .Sh "$c\->get_action( $action\fP, \f(CW$namespace )"
 907 .el .Sh "$c\->get_action( \f(CW$action\fP, \f(CW$namespace\fP )"
 908 .IX Subsection "$c->get_action( $action, $namespace )"
 909 Gets an action in a given namespace.
 910 .ie n .Sh "$c\->get_actions( $action\fP, \f(CW$namespace )"
 911 .el .Sh "$c\->get_actions( \f(CW$action\fP, \f(CW$namespace\fP )"
 912 .IX Subsection "$c->get_actions( $action, $namespace )"
 913 Gets all actions of a given name in a namespace and all parent
 914 namespaces.
 915 .ie n .Sh "$c\->handle_request( $class\fP, \f(CW@arguments )"
 916 .el .Sh "$c\->handle_request( \f(CW$class\fP, \f(CW@arguments\fP )"
 917 .IX Subsection "$c->handle_request( $class, @arguments )"
 918 Called to handle each \s-1HTTP\s0 request.
 919 .ie n .Sh "$c\->prepare( @arguments )"
 920 .el .Sh "$c\->prepare( \f(CW@arguments\fP )"
 921 .IX Subsection "$c->prepare( @arguments )"
 922 Creates a Catalyst context from an engine-specific request (Apache, \s-1CGI\s0,
 923 etc.).
 924 .Sh "$c\->prepare_action"
 925 .IX Subsection "$c->prepare_action"
 926 Prepares action. See Catalyst::Dispatcher.
 927 .Sh "$c\->prepare_body"
 928 .IX Subsection "$c->prepare_body"
 929 Prepares message body.
 930 .ie n .Sh "$c\->prepare_body_chunk( $chunk )"
 931 .el .Sh "$c\->prepare_body_chunk( \f(CW$chunk\fP )"
 932 .IX Subsection "$c->prepare_body_chunk( $chunk )"
 933 Prepares a chunk of data before sending it to HTTP::Body.
 934 .PP
 935 See Catalyst::Engine.
 936 .Sh "$c\->prepare_body_parameters"
 937 .IX Subsection "$c->prepare_body_parameters"
 938 Prepares body parameters.
 939 .Sh "$c\->prepare_connection"
 940 .IX Subsection "$c->prepare_connection"
 941 Prepares connection.
 942 .Sh "$c\->prepare_cookies"
 943 .IX Subsection "$c->prepare_cookies"
 944 Prepares cookies.
 945 .Sh "$c\->prepare_headers"
 946 .IX Subsection "$c->prepare_headers"
 947 Prepares headers.
 948 .Sh "$c\->prepare_parameters"
 949 .IX Subsection "$c->prepare_parameters"
 950 Prepares parameters.
 951 .Sh "$c\->prepare_path"
 952 .IX Subsection "$c->prepare_path"
 953 Prepares path and base.
 954 .Sh "$c\->prepare_query_parameters"
 955 .IX Subsection "$c->prepare_query_parameters"
 956 Prepares query parameters.
 957 .Sh "$c\->prepare_read"
 958 .IX Subsection "$c->prepare_read"
 959 Prepares the input for reading.
 960 .Sh "$c\->prepare_request"
 961 .IX Subsection "$c->prepare_request"
 962 Prepares the engine request.
 963 .Sh "$c\->prepare_uploads"
 964 .IX Subsection "$c->prepare_uploads"
 965 Prepares uploads.
 966 .Sh "$c\->prepare_write"
 967 .IX Subsection "$c->prepare_write"
 968 Prepares the output for writing.
 969 .Sh "$c\->request_class"
 970 .IX Subsection "$c->request_class"
 971 Returns or sets the request class.
 972 .Sh "$c\->response_class"
 973 .IX Subsection "$c->response_class"
 974 Returns or sets the response class.
 975 .Sh "$c\->read( [$maxlength] )"
 976 .IX Subsection "$c->read( [$maxlength] )"
 977 Reads a chunk of data from the request body. This method is designed to
 978 be used in a while loop, reading \f(CW$maxlength\fR bytes on every call.
 979 \&\f(CW$maxlength\fR defaults to the size of the request if not specified.
 980 .PP
 981 You have to set \f(CW\*(C`MyApp\->config(parse_on_demand => 1)\*(C'\fR to use this
 982 directly.
 983 .PP
 984 Warning: If you use \fIread()\fR, Catalyst will not process the body,
 985 so you will not be able to access \s-1POST\s0 parameters or file uploads via
 986 \&\f(CW$c\fR\->request.  You must handle all body parsing yourself.
 987 .Sh "$c\->run"
 988 .IX Subsection "$c->run"
 989 Starts the engine.
 990 .ie n .Sh "$c\->set_action( $action\fP, \f(CW$code\fP, \f(CW$namespace\fP, \f(CW$attrs )"
 991 .el .Sh "$c\->set_action( \f(CW$action\fP, \f(CW$code\fP, \f(CW$namespace\fP, \f(CW$attrs\fP )"
 992 .IX Subsection "$c->set_action( $action, $code, $namespace, $attrs )"
 993 Sets an action in a given namespace.
 994 .Sh "$c\->setup_actions($component)"
 995 .IX Subsection "$c->setup_actions($component)"
 996 Sets up actions for a component.
 997 .Sh "$c\->setup_components"
 998 .IX Subsection "$c->setup_components"
 999 This method is called internally to set up the application's components.
1000 .PP
1001 It finds modules by calling the locate_components method, expands them to
1002 package names with the expand_component_module method, and then installs
1003 each component into the application.
1004 .PP
1005 The \f(CW\*(C`setup_components\*(C'\fR config option is passed to both of the above methods.
1006 .PP
1007 Installation of each component is performed by the setup_component method,
1008 below.
1009 .ie n .Sh "$c\->locate_components( $setup_component_config )"
1010 .el .Sh "$c\->locate_components( \f(CW$setup_component_config\fP )"
1011 .IX Subsection "$c->locate_components( $setup_component_config )"
1012 This method is meant to provide a list of component modules that should be
1013 setup for the application.  By default, it will use Module::Pluggable.
1014 .PP
1015 Specify a \f(CW\*(C`setup_components\*(C'\fR config option to pass additional options directly
1016 to Module::Pluggable. To add additional search paths, specify a key named
1017 \&\f(CW\*(C`search_extra\*(C'\fR as an array reference. Items in the array beginning with \f(CW\*(C`::\*(C'\fR
1018 will have the application class name prepended to them.
1019 .ie n .Sh "$c\->expand_component_module( $component\fP, \f(CW$setup_component_config )"
1020 .el .Sh "$c\->expand_component_module( \f(CW$component\fP, \f(CW$setup_component_config\fP )"
1021 .IX Subsection "$c->expand_component_module( $component, $setup_component_config )"
1022 Components found by \f(CW\*(C`locate_components\*(C'\fR will be passed to this method, which
1023 is expected to return a list of component (package) names to be set up.
1024 .Sh "$c\->setup_component"
1025 .IX Subsection "$c->setup_component"
1026 .Sh "$c\->setup_dispatcher"
1027 .IX Subsection "$c->setup_dispatcher"
1028 Sets up dispatcher.
1029 .Sh "$c\->setup_engine"
1030 .IX Subsection "$c->setup_engine"
1031 Sets up engine.
1032 .Sh "$c\->setup_home"
1033 .IX Subsection "$c->setup_home"
1034 Sets up the home directory.
1035 .Sh "$c\->setup_log"
1036 .IX Subsection "$c->setup_log"
1037 Sets up log by instantiating a Catalyst::Log object and
1038 passing it to \f(CW\*(C`log()\*(C'\fR. Pass in a comma-delimited list of levels to set the
1039 log to.
1040 .PP
1041 This method also installs a \f(CW\*(C`debug\*(C'\fR method that returns a true value into the
1042 catalyst subclass if the \*(L"debug\*(R" level is passed in the comma-delimited list,
1043 or if the \f(CW$CATALYST_DEBUG\fR environment variable is set to a true value.
1044 .PP
1045 Note that if the log has already been setup, by either a previous call to
1046 \&\f(CW\*(C`setup_log\*(C'\fR or by a call such as \f(CW\*(C`_\|_PACKAGE_\|_\->log( MyLogger\->new )\*(C'\fR,
1047 that this method won't actually set up the log object.
1048 .Sh "$c\->setup_plugins"
1049 .IX Subsection "$c->setup_plugins"
1050 Sets up plugins.
1051 .Sh "$c\->setup_stats"
1052 .IX Subsection "$c->setup_stats"
1053 Sets up timing statistics class.
1054 .Sh "$c\->registered_plugins"
1055 .IX Subsection "$c->registered_plugins"
1056 Returns a sorted list of the plugins which have either been stated in the
1057 import list or which have been added via \f(CW\*(C`MyApp\->plugin(@args);\*(C'\fR.
1058 .PP
1059 If passed a given plugin name, it will report a boolean value indicating
1060 whether or not that plugin is loaded.  A fully qualified name is required if
1061 the plugin name does not begin with \f(CW\*(C`Catalyst::Plugin::\*(C'\fR.
1062 .PP
1063 .Vb 3
1064 \& if ($c\->registered_plugins('Some::Plugin')) {
1065 \&     ...
1066 \& }
1067 .Ve
1068 .Sh "$c\->stack"
1069 .IX Subsection "$c->stack"
1070 Returns an arrayref of the internal execution stack (actions that are
1071 currently executing).
1072 .Sh "$c\->stats_class"
1073 .IX Subsection "$c->stats_class"
1074 Returns or sets the stats (timing statistics) class.
1075 .Sh "$c\->use_stats"
1076 .IX Subsection "$c->use_stats"
1077 Returns 1 when stats collection is enabled.  Stats collection is enabled
1078 when the \-Stats options is set, debug is on or when the <\s-1MYAPP\s0>_STATS
1079 environment variable is set.
1080 .PP
1081 Note that this is a static method, not an accessor and should be overridden
1082 by declaring \f(CW\*(C`sub use_stats { 1 }\*(C'\fR in your MyApp.pm, not by calling \f(CW\*(C`$c\->use_stats(1)\*(C'\fR.
1083 .ie n .Sh "$c\->write( $data )"
1084 .el .Sh "$c\->write( \f(CW$data\fP )"
1085 .IX Subsection "$c->write( $data )"
1086 Writes \f(CW$data\fR to the output stream. When using this method directly, you
1087 will need to manually set the \f(CW\*(C`Content\-Length\*(C'\fR header to the length of
1088 your output data, if known.
1089 .Sh "version"
1090 .IX Subsection "version"
1091 Returns the Catalyst version number. Mostly useful for \*(L"powered by\*(R"
1092 messages in template systems.
1093 .SH "CONFIGURATION"
1094 .IX Header "CONFIGURATION"
1095 There are a number of 'base' config variables which can be set:
1096 .IP "\(bu" 4
1097 \&\f(CW\*(C`default_model\*(C'\fR \- The default model picked if you say \f(CW\*(C`$c\->model\*(C'\fR. See \*(L"$c\-\*(R"model($name)>.
1098 .IP "\(bu" 4
1099 \&\f(CW\*(C`default_view\*(C'\fR \- The default view to be rendered or returned when \f(CW\*(C`$c\->view\*(C'\fR. See \*(L"$c\-\*(R"view($name)>.
1100 is called.
1101 .IP "\(bu" 4
1102 \&\f(CW\*(C`disable_component_resolution_regex_fallback\*(C'\fR \- Turns
1103 off the deprecated component resolution functionality so
1104 that if any of the component methods (e.g. \f(CW\*(C`$c\->controller('Foo')\*(C'\fR)
1105 are called then regex search will not be attempted on string values and
1106 instead \f(CW\*(C`undef\*(C'\fR will be returned.
1107 .IP "\(bu" 4
1108 \&\f(CW\*(C`home\*(C'\fR \- The application home directory. In an uninstalled application,
1109 this is the top level application directory. In an installed application,
1110 this will be the directory containing \f(CW\*(C`MyApp.pm\*(C'\fR.
1111 .IP "\(bu" 4
1112 \&\f(CW\*(C`ignore_frontend_proxy\*(C'\fR \- See \*(L"\s-1PROXY\s0 \s-1SUPPORT\s0\*(R"
1113 .IP "\(bu" 4
1114 \&\f(CW\*(C`name\*(C'\fR \- The name of the application in debug messages and the debug and
1115 welcome screens
1116 .IP "\(bu" 4
1117 \&\f(CW\*(C`parse_on_demand\*(C'\fR \- The request body (for example file uploads) will not be parsed
1118 until it is accessed. This allows you to (for example) check authentication (and reject
1119 the upload) before actually recieving all the data. See \*(L"\s-1ON\-DEMAND\s0 \s-1PARSER\s0\*(R"
1120 .IP "\(bu" 4
1121 \&\f(CW\*(C`root\*(C'\fR \- The root directory for templates. Usually this is just a
1122 subdirectory of the home directory, but you can set it to change the
1123 templates to a different directory.
1124 .IP "\(bu" 4
1125 \&\f(CW\*(C`search_extra\*(C'\fR \- Array reference passed to Module::Pluggable to for additional
1126 namespaces from which components will be loaded (and constructed and stored in
1127 \&\f(CW\*(C`$c\->components\*(C'\fR).
1128 .IP "\(bu" 4
1129 \&\f(CW\*(C`show_internal_actions\*(C'\fR \- If true, causes internal actions such as \f(CW\*(C`_DISPATCH\*(C'\fR
1130 to be shown in hit debug tables in the test server.
1131 .IP "\(bu" 4
1132 \&\f(CW\*(C`using_frontend_proxy\*(C'\fR \- See \*(L"\s-1PROXY\s0 \s-1SUPPORT\s0\*(R".
1133 .SH "INTERNAL ACTIONS"
1134 .IX Header "INTERNAL ACTIONS"
1135 Catalyst uses internal actions like \f(CW\*(C`_DISPATCH\*(C'\fR, \f(CW\*(C`_BEGIN\*(C'\fR, \f(CW\*(C`_AUTO\*(C'\fR,
1136 \&\f(CW\*(C`_ACTION\*(C'\fR, and \f(CW\*(C`_END\*(C'\fR. These are by default not shown in the private
1137 action table, but you can make them visible with a config parameter.
1138 .PP
1139 .Vb 1
1140 \&    MyApp\->config(show_internal_actions => 1);
1141 .Ve
1142 .SH "ON-DEMAND PARSER"
1143 .IX Header "ON-DEMAND PARSER"
1144 The request body is usually parsed at the beginning of a request,
1145 but if you want to handle input yourself, you can enable on-demand
1146 parsing with a config parameter.
1147 .PP
1148 .Vb 1
1149 \&    MyApp\->config(parse_on_demand => 1);
1150 .Ve
1151 .SH "PROXY SUPPORT"
1152 .IX Header "PROXY SUPPORT"
1153 Many production servers operate using the common double-server approach,
1154 with a lightweight frontend web server passing requests to a larger
1155 backend server. An application running on the backend server must deal
1156 with two problems: the remote user always appears to be \f(CW127.0.0.1\fR and
1157 the server's hostname will appear to be \f(CW\*(C`localhost\*(C'\fR regardless of the
1158 virtual host that the user connected through.
1159 .PP
1160 Catalyst will automatically detect this situation when you are running
1161 the frontend and backend servers on the same machine. The following
1162 changes are made to the request.
1163 .PP
1164 .Vb 2
1165 \&    $c\->req\->address is set to the user's real IP address, as read from
1166 \&    the HTTP X\-Forwarded\-For header.
1167 .Ve
1168 .PP
1169 .Vb 2
1170 \&    The host value for $c\->req\->base and $c\->req\->uri is set to the real
1171 \&    host, as read from the HTTP X\-Forwarded\-Host header.
1172 .Ve
1173 .PP
1174 Additionally, you may be running your backend application on an insecure
1175 connection (port 80) while your frontend proxy is running under \s-1SSL\s0.  If there
1176 is a discrepancy in the ports, use the \s-1HTTP\s0 header \f(CW\*(C`X\-Forwarded\-Port\*(C'\fR to
1177 tell Catalyst what port the frontend listens on.  This will allow all URIs to
1178 be created properly.
1179 .PP
1180 In the case of passing in:
1181 .PP
1182 .Vb 1
1183 \&    X\-Forwarded\-Port: 443
1184 .Ve
1185 .PP
1186 All calls to \f(CW\*(C`uri_for\*(C'\fR will result in an https link, as is expected.
1187 .PP
1188 Obviously, your web server must support these headers for this to work.
1189 .PP
1190 In a more complex server farm environment where you may have your
1191 frontend proxy server(s) on different machines, you will need to set a
1192 configuration option to tell Catalyst to read the proxied data from the
1193 headers.
1194 .PP
1195 .Vb 1
1196 \&    MyApp\->config(using_frontend_proxy => 1);
1197 .Ve
1198 .PP
1199 If you do not wish to use the proxy support at all, you may set:
1200 .PP
1201 .Vb 1
1202 \&    MyApp\->config(ignore_frontend_proxy => 1);
1203 .Ve
1204 .SH "THREAD SAFETY"
1205 .IX Header "THREAD SAFETY"
1206 Catalyst has been tested under Apache 2's threading \f(CW\*(C`mpm_worker\*(C'\fR,
1207 \&\f(CW\*(C`mpm_winnt\*(C'\fR, and the standalone forking \s-1HTTP\s0 server on Windows. We
1208 believe the Catalyst core to be thread\-safe.
1209 .PP
1210 If you plan to operate in a threaded environment, remember that all other
1211 modules you are using must also be thread\-safe. Some modules, most notably
1212 DBD::SQLite, are not thread\-safe.
1213 .SH "SUPPORT"
1214 .IX Header "SUPPORT"
1215 \&\s-1IRC:\s0
1216 .PP
1217 .Vb 1
1218 \&    Join #catalyst on irc.perl.org.
1219 .Ve
1220 .PP
1221 Mailing Lists:
1222 .PP
1223 .Vb 2
1224 \&    http://lists.scsys.co.uk/cgi\-bin/mailman/listinfo/catalyst
1225 \&    http://lists.scsys.co.uk/cgi\-bin/mailman/listinfo/catalyst\-dev
1226 .Ve
1227 .PP
1228 Web:
1229 .PP
1230 .Vb 1
1231 \&    http://catalyst.perl.org
1232 .Ve
1233 .PP
1234 Wiki:
1235 .PP
1236 .Vb 1
1237 \&    http://dev.catalyst.perl.org
1238 .Ve
1239 .SH "SEE ALSO"
1240 .IX Header "SEE ALSO"
1241 .Sh "Task::Catalyst \- All you need to start with Catalyst"
1242 .IX Subsection "Task::Catalyst - All you need to start with Catalyst"
1243 .Sh "Catalyst::Manual \- The Catalyst Manual"
1244 .IX Subsection "Catalyst::Manual - The Catalyst Manual"
1245 .Sh "Catalyst::Component, Catalyst::Controller \- Base classes for components"
1246 .IX Subsection "Catalyst::Component, Catalyst::Controller - Base classes for components"
1247 .Sh "Catalyst::Engine \- Core engine"
1248 .IX Subsection "Catalyst::Engine - Core engine"
1249 .Sh "Catalyst::Log \- Log class."
1250 .IX Subsection "Catalyst::Log - Log class."
1251 .Sh "Catalyst::Request \- Request object"
1252 .IX Subsection "Catalyst::Request - Request object"
1253 .Sh "Catalyst::Response \- Response object"
1254 .IX Subsection "Catalyst::Response - Response object"
1255 .Sh "Catalyst::Test \- The test suite."
1256 .IX Subsection "Catalyst::Test - The test suite."
1257 .SH "PROJECT FOUNDER"
1258 .IX Header "PROJECT FOUNDER"
1259 sri: Sebastian Riedel <sri@cpan.org>
1260 .SH "CONTRIBUTORS"
1261 .IX Header "CONTRIBUTORS"
1262 abw: Andy Wardley
1263 .PP
1264 acme: Leon Brocard <leon@astray.com>
1265 .PP
1266 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
1267 .PP
1268 Andrew Bramble
1269 .PP
1270 Andrew Ford <A.Ford@ford\-mason.co.uk>
1271 .PP
1272 Andrew Ruthven
1273 .PP
1274 andyg: Andy Grundman <andy@hybridized.org>
1275 .PP
1276 audreyt: Audrey Tang
1277 .PP
1278 bricas: Brian Cassidy <bricas@cpan.org>
1279 .PP
1280 Caelum: Rafael Kitover <rkitover@io.com>
1281 .PP
1282 chansen: Christian Hansen
1283 .PP
1284 chicks: Christopher Hicks
1285 .PP
1286 Chisel Wright \f(CW\*(C`pause@herlpacker.co.uk\*(C'\fR
1287 .PP
1288 Danijel Milicevic \f(CW\*(C`me@danijel.de\*(C'\fR
1289 .PP
1290 David Kamholz <dkamholz@cpan.org>
1291 .PP
1292 David Naughton, \f(CW\*(C`naughton@umn.edu\*(C'\fR
1293 .PP
1294 David E. Wheeler
1295 .PP
1296 dhoss: Devin Austin <dhoss@cpan.org>
1297 .PP
1298 dkubb: Dan Kubb <dan.kubb\-cpan@onautopilot.com>
1299 .PP
1300 Drew Taylor
1301 .PP
1302 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
1303 .PP
1304 esskar: Sascha Kiefer
1305 .PP
1306 fireartist: Carl Franks <cfranks@cpan.org>
1307 .PP
1308 frew: Arthur Axel \*(L"fREW\*(R" Schmidt <frioux@gmail.com>
1309 .PP
1310 gabb: Danijel Milicevic
1311 .PP
1312 Gary Ashton Jones
1313 .PP
1314 Gavin Henry \f(CW\*(C`ghenry@perl.me.uk\*(C'\fR
1315 .PP
1316 Geoff Richards
1317 .PP
1318 groditi: Guillermo Roditi <groditi@gmail.com>
1319 .PP
1320 hobbs: Andrew Rodland <andrew@cleverdomain.org>
1321 .PP
1322 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
1323 .PP
1324 jcamacho: Juan Camacho
1325 .PP
1326 jester: Jesse Sheidlower \f(CW\*(C`jester@panix.com\*(C'\fR
1327 .PP
1328 jhannah: Jay Hannah <jay@jays.net>
1329 .PP
1330 Jody Belka
1331 .PP
1332 Johan Lindstrom
1333 .PP
1334 jon: Jon Schutz <jjschutz@cpan.org>
1335 .PP
1336 Jonathan Rockway \f(CW\*(C`<jrockway@cpan.org>\*(C'\fR
1337 .PP
1338 Kieren Diment \f(CW\*(C`kd@totaldatasolution.com\*(C'\fR
1339 .PP
1340 konobi: Scott McWhirter <konobi@cpan.org>
1341 .PP
1342 marcus: Marcus Ramberg <mramberg@cpan.org>
1343 .PP
1344 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
1345 .PP
1346 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
1347 .PP
1348 mugwump: Sam Vilain
1349 .PP
1350 naughton: David Naughton
1351 .PP
1352 ningu: David Kamholz <dkamholz@cpan.org>
1353 .PP
1354 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
1355 .PP
1356 numa: Dan Sully <daniel@cpan.org>
1357 .PP
1358 obra: Jesse Vincent
1359 .PP
1360 omega: Andreas Marienborg
1361 .PP
1362 Oleg Kostyuk <cub.uanic@gmail.com>
1363 .PP
1364 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
1365 .PP
1366 rafl: Florian Ragwitz <rafl@debian.org>
1367 .PP
1368 random: Roland Lammel <lammel@cpan.org>
1369 .PP
1370 Robert Sedlacek \f(CW\*(C`<rs@474.at>\*(C'\fR
1371 .PP
1372 sky: Arthur Bergman
1373 .PP
1374 t0m: Tomas Doran <bobtfish@bobtfish.net>
1375 .PP
1376 Ulf Edvinsson
1377 .PP
1378 Viljo Marrandi \f(CW\*(C`vilts@yahoo.com\*(C'\fR
1379 .PP
1380 Will Hawes \f(CW\*(C`info@whawes.co.uk\*(C'\fR
1381 .PP
1382 willert: Sebastian Willert <willert@cpan.org>
1383 .PP
1384 Yuval Kogman, \f(CW\*(C`nothingmuch@woobling.org\*(C'\fR
1385 .SH "LICENSE"
1386 .IX Header "LICENSE"
1387 This library is free software. You can redistribute it and/or modify it under
1388 the same terms as Perl itself.