lib/Catalyst.pm

   1 package Catalyst;
   2
   3 use Moose;
   4 use Moose::Meta::Class ();
   5 extends 'Catalyst::Component';
   6 use Moose::Util qw/find_meta/;
   7 use B::Hooks::EndOfScope ();
   8 use Catalyst::Exception;
   9 use Catalyst::Exception::Detach;
  10 use Catalyst::Exception::Go;
  11 use Catalyst::Log;
  12 use Catalyst::Request;
  13 use Catalyst::Request::Upload;
  14 use Catalyst::Response;
  15 use Catalyst::Utils;
  16 use Catalyst::Controller;
  17 use Data::OptList;
  18 use Devel::InnerPackage ();
  19 use File::stat;
  20 use Module::Pluggable::Object ();
  21 use Text::SimpleTable ();
  22 use Path::Class::Dir ();
  23 use Path::Class::File ();
  24 use URI ();
  25 use URI::http;
  26 use URI::https;
  27 use Tree::Simple qw/use_weak_refs/;
  28 use Tree::Simple::Visitor::FindByUID;
  29 use Class::C3::Adopt::NEXT;
  30 use List::Util qw/first/;
  31 use List::MoreUtils qw/uniq/;
  32 use attributes;
  33 use utf8;
  34 use Carp qw/croak carp shortmess/;
  35
  36 BEGIN { require 5.008004; }
  37
  38 has stack => (is => 'ro', default => sub { [] });
  39 has stash => (is => 'rw', default => sub { {} });
  40 has state => (is => 'rw', default => 0);
  41 has stats => (is => 'rw');
  42 has action => (is => 'rw');
  43 has counter => (is => 'rw', default => sub { {} });
  44 has request => (is => 'rw', default => sub { $_[0]->request_class->new({}) }, required => 1, lazy => 1);
  45 has response => (is => 'rw', default => sub { $_[0]->response_class->new({}) }, required => 1, lazy => 1);
  46 has namespace => (is => 'rw');
  47
  48 sub depth { scalar @{ shift->stack || [] }; }
  49 sub comp { shift->component(@_) }
  50
  51 sub req {
  52     my $self = shift; return $self->request(@_);
  53 }
  54 sub res {
  55     my $self = shift; return $self->response(@_);
  56 }
  57
  58 # For backwards compatibility
  59 sub finalize_output { shift->finalize_body(@_) };
  60
  61 # For statistics
  62 our $COUNT     = 1;
  63 our $START     = time;
  64 our $RECURSION = 1000;
  65 our $DETACH    = Catalyst::Exception::Detach->new;
  66 our $GO        = Catalyst::Exception::Go->new;
  67
  68 #I imagine that very few of these really need to be class variables. if any.
  69 #maybe we should just make them attributes with a default?
  70 __PACKAGE__->mk_classdata($_) # XXX FIXME - components remove from here
  71   for qw/container components arguments dispatcher engine log dispatcher_class
  72   engine_class context_class request_class response_class stats_class
  73   setup_finished/;
  74
  75 __PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
  76 __PACKAGE__->engine_class('Catalyst::Engine::CGI');
  77 __PACKAGE__->request_class('Catalyst::Request');
  78 __PACKAGE__->response_class('Catalyst::Response');
  79 __PACKAGE__->stats_class('Catalyst::Stats');
  80
  81 # Remember to update this in Catalyst::Runtime as well!
  82
  83 our $VERSION = '5.80032';
  84
  85 sub import {
  86     my ( $class, @arguments ) = @_;
  87
  88     # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
  89     # callers @ISA.
  90     return unless $class eq 'Catalyst';
  91
  92     my $caller = caller();
  93     return if $caller eq 'main';
  94
  95     my $meta = Moose::Meta::Class->initialize($caller);
  96
  97     unless ( $caller->isa('Catalyst') ) { # XXX - Remove!
  98         my @superclasses = ($meta->superclasses, $class, 'Catalyst::Controller'); # XXX - Remove!
  99         $meta->superclasses(@superclasses); # XXX - Remove!
 100     } # XXX - Remove!
 101
 102     # Avoid possible C3 issues if 'Moose::Object' is already on RHS of MyApp
 103     $meta->superclasses(grep { $_ ne 'Moose::Object' } $meta->superclasses);
 104
 105     unless( $meta->has_method('meta') ){
 106         if ($Moose::VERSION >= 1.15) {
 107             $meta->_add_meta_method('meta');
 108         }
 109         else {
 110             $meta->add_method(meta => sub { Moose::Meta::Class->initialize("${caller}") } );
 111         }
 112     }
 113
 114     $caller->arguments( [@arguments] );
 115     $caller->setup_home;
 116 }
 117
 118 sub _application { $_[0] }
 119
 120 =head1 NAME
 121
 122 Catalyst - The Elegant MVC Web Application Framework
 123
 124 =head1 SYNOPSIS
 125
 126 See the L<Catalyst::Manual> distribution for comprehensive
 127 documentation and tutorials.
 128
 129     # Install Catalyst::Devel for helpers and other development tools
 130     # use the helper to create a new application
 131     catalyst.pl MyApp
 132
 133     # add models, views, controllers
 134     script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
 135     script/myapp_create.pl view MyTemplate TT
 136     script/myapp_create.pl controller Search
 137
 138     # built in testserver -- use -r to restart automatically on changes
 139     # --help to see all available options
 140     script/myapp_server.pl
 141
 142     # command line testing interface
 143     script/myapp_test.pl /yada
 144
 145     ### in lib/MyApp.pm
 146     use Catalyst qw/-Debug/; # include plugins here as well
 147
 148     ### In lib/MyApp/Controller/Root.pm (autocreated)
 149     sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
 150         my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
 151         $c->stash->{template} = 'foo.tt'; # set the template
 152         # lookup something from db -- stash vars are passed to TT
 153         $c->stash->{data} =
 154           $c->model('Database::Foo')->search( { country => $args[0] } );
 155         if ( $c->req->params->{bar} ) { # access GET or POST parameters
 156             $c->forward( 'bar' ); # process another action
 157             # do something else after forward returns
 158         }
 159     }
 160
 161     # The foo.tt TT template can use the stash data from the database
 162     [% WHILE (item = data.next) %]
 163         [% item.foo %]
 164     [% END %]
 165
 166     # called for /bar/of/soap, /bar/of/soap/10, etc.
 167     sub bar : Path('/bar/of/soap') { ... }
 168
 169     # called for all actions, from the top-most controller downwards
 170     sub auto : Private {
 171         my ( $self, $c ) = @_;
 172         if ( !$c->user_exists ) { # Catalyst::Plugin::Authentication
 173             $c->res->redirect( '/login' ); # require login
 174             return 0; # abort request and go immediately to end()
 175         }
 176         return 1; # success; carry on to next action
 177     }
 178
 179     # called after all actions are finished
 180     sub end : Private {
 181         my ( $self, $c ) = @_;
 182         if ( scalar @{ $c->error } ) { ... } # handle errors
 183         return if $c->res->body; # already have a response
 184         $c->forward( 'MyApp::View::TT' ); # render template
 185     }
 186
 187     ### in MyApp/Controller/Foo.pm
 188     # called for /foo/bar
 189     sub bar : Local { ... }
 190
 191     # called for /blargle
 192     sub blargle : Global { ... }
 193
 194     # an index action matches /foo, but not /foo/1, etc.
 195     sub index : Private { ... }
 196
 197     ### in MyApp/Controller/Foo/Bar.pm
 198     # called for /foo/bar/baz
 199     sub baz : Local { ... }
 200
 201     # first Root auto is called, then Foo auto, then this
 202     sub auto : Private { ... }
 203
 204     # powerful regular expression paths are also possible
 205     sub details : Regex('^product/(\w+)/details$') {
 206         my ( $self, $c ) = @_;
 207         # extract the (\w+) from the URI
 208         my $product = $c->req->captures->[0];
 209     }
 210
 211 See L<Catalyst::Manual::Intro> for additional information.
 212
 213 =head1 DESCRIPTION
 214
 215 Catalyst is a modern framework for making web applications without the
 216 pain usually associated with this process. This document is a reference
 217 to the main Catalyst application. If you are a new user, we suggest you
 218 start with L<Catalyst::Manual::Tutorial> or L<Catalyst::Manual::Intro>.
 219
 220 See L<Catalyst::Manual> for more documentation.
 221
 222 Catalyst plugins can be loaded by naming them as arguments to the "use
 223 Catalyst" statement. Omit the C<Catalyst::Plugin::> prefix from the
 224 plugin name, i.e., C<Catalyst::Plugin::My::Module> becomes
 225 C<My::Module>.
 226
 227     use Catalyst qw/My::Module/;
 228
 229 If your plugin starts with a name other than C<Catalyst::Plugin::>, you can
 230 fully qualify the name by using a unary plus:
 231
 232     use Catalyst qw/
 233         My::Module
 234         +Fully::Qualified::Plugin::Name
 235     /;
 236
 237 Special flags like C<-Debug> and C<-Engine> can also be specified as
 238 arguments when Catalyst is loaded:
 239
 240     use Catalyst qw/-Debug My::Module/;
 241
 242 The position of plugins and flags in the chain is important, because
 243 they are loaded in the order in which they appear.
 244
 245 The following flags are supported:
 246
 247 =head2 -Debug
 248
 249 Enables debug output. You can also force this setting from the system
 250 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
 251 settings override the application, with <MYAPP>_DEBUG having the highest
 252 priority.
 253
 254 This sets the log level to 'debug' and enables full debug output on the
 255 error screen. If you only want the latter, see L<< $c->debug >>.
 256
 257 =head2 -Engine
 258
 259 Forces Catalyst to use a specific engine. Omit the
 260 C<Catalyst::Engine::> prefix of the engine name, i.e.:
 261
 262     use Catalyst qw/-Engine=CGI/;
 263
 264 =head2 -Home
 265
 266 Forces Catalyst to use a specific home directory, e.g.:
 267
 268     use Catalyst qw[-Home=/usr/mst];
 269
 270 This can also be done in the shell environment by setting either the
 271 C<CATALYST_HOME> environment variable or C<MYAPP_HOME>; where C<MYAPP>
 272 is replaced with the uppercased name of your application, any "::" in
 273 the name will be replaced with underscores, e.g. MyApp::Web should use
 274 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.
 275
 276 If none of these are set, Catalyst will attempt to automatically detect the
 277 home directory. If you are working in a development envirnoment, Catalyst
 278 will try and find the directory containing either Makefile.PL, Build.PL or
 279 dist.ini. If the application has been installed into the system (i.e.
 280 you have done C<make install>), then Catalyst will use the path to your
 281 application module, without the .pm extension (ie, /foo/MyApp if your
 282 application was installed at /foo/MyApp.pm)
 283
 284 =head2 -Log
 285
 286     use Catalyst '-Log=warn,fatal,error';
 287
 288 Specifies a comma-delimited list of log levels.
 289
 290 =head2 -Stats
 291
 292 Enables statistics collection and reporting.
 293
 294    use Catalyst qw/-Stats=1/;
 295
 296 You can also force this setting from the system environment with CATALYST_STATS
 297 or <MYAPP>_STATS. The environment settings override the application, with
 298 <MYAPP>_STATS having the highest priority.
 299
 300 Stats are also enabled if L<< debugging |/"-Debug" >> is enabled.
 301
 302 =head1 METHODS
 303
 304 =head2 INFORMATION ABOUT THE CURRENT REQUEST
 305
 306 =head2 $c->action
 307
 308 Returns a L<Catalyst::Action> object for the current action, which
 309 stringifies to the action name. See L<Catalyst::Action>.
 310
 311 =head2 $c->namespace
 312
 313 Returns the namespace of the current action, i.e., the URI prefix
 314 corresponding to the controller of the current action. For example:
 315
 316     # in Controller::Foo::Bar
 317     $c->namespace; # returns 'foo/bar';
 318
 319 =head2 $c->request
 320
 321 =head2 $c->req
 322
 323 Returns the current L<Catalyst::Request> object, giving access to
 324 information about the current client request (including parameters,
 325 cookies, HTTP headers, etc.). See L<Catalyst::Request>.
 326
 327 =head2 REQUEST FLOW HANDLING
 328
 329 =head2 $c->forward( $action [, \@arguments ] )
 330
 331 =head2 $c->forward( $class, $method, [, \@arguments ] )
 332
 333 Forwards processing to another action, by its private name. If you give a
 334 class name but no method, C<process()> is called. You may also optionally
 335 pass arguments in an arrayref. The action will receive the arguments in
 336 C<@_> and C<< $c->req->args >>. Upon returning from the function,
 337 C<< $c->req->args >> will be restored to the previous values.
 338
 339 Any data C<return>ed from the action forwarded to, will be returned by the
 340 call to forward.
 341
 342     my $foodata = $c->forward('/foo');
 343     $c->forward('index');
 344     $c->forward(qw/Model::DBIC::Foo do_stuff/);
 345     $c->forward('View::TT');
 346
 347 Note that L<< forward|/"$c->forward( $action [, \@arguments ] )" >> implies
 348 an C<< eval { } >> around the call (actually
 349 L<< execute|/"$c->execute( $class, $coderef )" >> does), thus de-fatalizing
 350 all 'dies' within the called action. If you want C<die> to propagate you
 351 need to do something like:
 352
 353     $c->forward('foo');
 354     die join "\n", @{ $c->error } if @{ $c->error };
 355
 356 Or make sure to always return true values from your actions and write
 357 your code like this:
 358
 359     $c->forward('foo') || return;
 360
 361 Another note is that C<< $c->forward >> always returns a scalar because it
 362 actually returns $c->state which operates in a scalar context.
 363 Thus, something like:
 364
 365     return @array;
 366
 367 in an action that is forwarded to is going to return a scalar,
 368 i.e. how many items are in that array, which is probably not what you want.
 369 If you need to return an array then return a reference to it,
 370 or stash it like so:
 371
 372     $c->stash->{array} = \@array;
 373
 374 and access it from the stash.
 375
 376 Keep in mind that the C<end> method used is that of the caller action. So a C<$c-E<gt>detach> inside a forwarded action would run the C<end> method from the original action requested.
 377
 378 =cut
 379
 380 sub forward { my $c = shift; no warnings 'recursion'; $c->dispatcher->forward( $c, @_ ) }
 381
 382 =head2 $c->detach( $action [, \@arguments ] )
 383
 384 =head2 $c->detach( $class, $method, [, \@arguments ] )
 385
 386 =head2 $c->detach()
 387
 388 The same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, but
 389 doesn't return to the previous action when processing is finished.
 390
 391 When called with no arguments it escapes the processing chain entirely.
 392
 393 =cut
 394
 395 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
 396
 397 =head2 $c->visit( $action [, \@captures, \@arguments ] )
 398
 399 =head2 $c->visit( $class, $method, [, \@captures, \@arguments ] )
 400
 401 Almost the same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>,
 402 but does a full dispatch, instead of just calling the new C<$action> /
 403 C<< $class->$method >>. This means that C<begin>, C<auto> and the method
 404 you go to are called, just like a new request.
 405
 406 In addition both C<< $c->action >> and C<< $c->namespace >> are localized.
 407 This means, for example, that C<< $c->action >> methods such as
 408 L<name|Catalyst::Action/name>, L<class|Catalyst::Action/class> and
 409 L<reverse|Catalyst::Action/reverse> return information for the visited action
 410 when they are invoked within the visited action.  This is different from the
 411 behavior of L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, which
 412 continues to use the $c->action object from the caller action even when
 413 invoked from the callee.
 414
 415 C<< $c->stash >> is kept unchanged.
 416
 417 In effect, L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >>
 418 allows you to "wrap" another action, just as it would have been called by
 419 dispatching from a URL, while the analogous
 420 L<< go|/"$c->go( $action [, \@captures, \@arguments ] )" >> allows you to
 421 transfer control to another action as if it had been reached directly from a URL.
 422
 423 =cut
 424
 425 sub visit { my $c = shift; $c->dispatcher->visit( $c, @_ ) }
 426
 427 =head2 $c->go( $action [, \@captures, \@arguments ] )
 428
 429 =head2 $c->go( $class, $method, [, \@captures, \@arguments ] )
 430
 431 The relationship between C<go> and
 432 L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >> is the same as
 433 the relationship between
 434 L<< forward|/"$c->forward( $class, $method, [, \@arguments ] )" >> and
 435 L<< detach|/"$c->detach( $action [, \@arguments ] )" >>. Like C<< $c->visit >>,
 436 C<< $c->go >> will perform a full dispatch on the specified action or method,
 437 with localized C<< $c->action >> and C<< $c->namespace >>. Like C<detach>,
 438 C<go> escapes the processing of the current request chain on completion, and
 439 does not return to its caller.
 440
 441 @arguments are arguments to the final destination of $action. @captures are
 442 arguments to the intermediate steps, if any, on the way to the final sub of
 443 $action.
 444
 445 =cut
 446
 447 sub go { my $c = shift; $c->dispatcher->go( $c, @_ ) }
 448
 449 =head2 $c->response
 450
 451 =head2 $c->res
 452
 453 Returns the current L<Catalyst::Response> object, see there for details.
 454
 455 =head2 $c->stash
 456
 457 Returns a hashref to the stash, which may be used to store data and pass
 458 it between components during a request. You can also set hash keys by
 459 passing arguments. The stash is automatically sent to the view. The
 460 stash is cleared at the end of a request; it cannot be used for
 461 persistent storage (for this you must use a session; see
 462 L<Catalyst::Plugin::Session> for a complete system integrated with
 463 Catalyst).
 464
 465     $c->stash->{foo} = $bar;
 466     $c->stash( { moose => 'majestic', qux => 0 } );
 467     $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
 468
 469     # stash is automatically passed to the view for use in a template
 470     $c->forward( 'MyApp::View::TT' );
 471
 472 =cut
 473
 474 around stash => sub {
 475     my $orig = shift;
 476     my $c = shift;
 477     my $stash = $orig->($c);
 478     if (@_) {
 479         my $new_stash = @_ > 1 ? {@_} : $_[0];
 480         croak('stash takes a hash or hashref') unless ref $new_stash;
 481         foreach my $key ( keys %$new_stash ) {
 482           $stash->{$key} = $new_stash->{$key};
 483         }
 484     }
 485
 486     return $stash;
 487 };
 488
 489
 490 =head2 $c->error
 491
 492 =head2 $c->error($error, ...)
 493
 494 =head2 $c->error($arrayref)
 495
 496 Returns an arrayref containing error messages.  If Catalyst encounters an
 497 error while processing a request, it stores the error in $c->error.  This
 498 method should only be used to store fatal error messages.
 499
 500     my @error = @{ $c->error };
 501
 502 Add a new error.
 503
 504     $c->error('Something bad happened');
 505
 506 =cut
 507
 508 sub error {
 509     my $c = shift;
 510     if ( $_[0] ) {
 511         my $error = ref $_[0] eq 'ARRAY' ? $_[0] : [@_];
 512         croak @$error unless ref $c;
 513         push @{ $c->{error} }, @$error;
 514     }
 515     elsif ( defined $_[0] ) { $c->{error} = undef }
 516     return $c->{error} || [];
 517 }
 518
 519
 520 =head2 $c->state
 521
 522 Contains the return value of the last executed action.
 523 Note that << $c->state >> operates in a scalar context which means that all
 524 values it returns are scalar.
 525
 526 =head2 $c->clear_errors
 527
 528 Clear errors.  You probably don't want to clear the errors unless you are
 529 implementing a custom error screen.
 530
 531 This is equivalent to running
 532
 533     $c->error(0);
 534
 535 =cut
 536
 537 sub clear_errors {
 538     my $c = shift;
 539     $c->error(0);
 540 }
 541
 542 =head2 COMPONENT ACCESSORS
 543
 544 =head2 $c->controller($name)
 545
 546 Gets a L<Catalyst::Controller> instance by name.
 547
 548     $c->controller('Foo')->do_stuff;
 549
 550 If the name is omitted, will return the controller for the dispatched
 551 action.
 552
 553 If you want to search for controllers, pass in a regexp as the argument.
 554
 555     # find all controllers that start with Foo
 556     my @foo_controllers = $c->controller(qr{^Foo});
 557
 558
 559 =cut
 560
 561 sub controller {
 562     my ( $c, $name, @args ) = @_;
 563
 564 # FIXME: should this be a Catalyst::Utils method?
 565     if (!$name) {
 566         my $class  = $c->action->class;
 567
 568         my $prefix = length Catalyst::Utils::class2classprefix($class);
 569
 570         # MyApp::Controller::Foo becomes Foo
 571         # the + 2 is because of the ::
 572         $name = substr $class, $prefix + 2;
 573     }
 574
 575     return $c->container->get_component_from_sub_container( 'controller', $name, $c, @args);
 576 }
 577
 578 =head2 $c->model($name)
 579
 580 Gets a L<Catalyst::Model> instance by name.
 581
 582     $c->model('Foo')->do_stuff;
 583
 584 Any extra arguments are directly passed to ACCEPT_CONTEXT.
 585
 586 If the name is omitted, it will look for
 587  - a model object in $c->stash->{current_model_instance}, then
 588  - a model name in $c->stash->{current_model}, then
 589  - a config setting 'default_model', or
 590  - check if there is only one model, and return it if that's the case.
 591
 592 If you want to search for models, pass in a regexp as the argument.
 593
 594     # find all models that start with Foo
 595     my @foo_models = $c->model(qr{^Foo});
 596
 597 =cut
 598
 599 sub model {
 600     my ( $c, $name, @args ) = @_;
 601
 602     if (ref $c && !$name) {
 603         return $c->stash->{current_model_instance}
 604             if $c->stash->{current_model_instance};
 605
 606         $name = $c->stash->{current_model}
 607             if $c->stash->{current_model};
 608     }
 609
 610     return $c->container->get_component_from_sub_container( 'model', $name, $c, @args);
 611 }
 612
 613
 614 =head2 $c->view($name)
 615
 616 Gets a L<Catalyst::View> instance by name.
 617
 618     $c->view('Foo')->do_stuff;
 619
 620 Any extra arguments are directly passed to ACCEPT_CONTEXT.
 621
 622 If the name is omitted, it will look for
 623  - a view object in $c->stash->{current_view_instance}, then
 624  - a view name in $c->stash->{current_view}, then
 625  - a config setting 'default_view', or
 626  - check if there is only one view, and return it if that's the case.
 627
 628 If you want to search for views, pass in a regexp as the argument.
 629
 630     # find all views that start with Foo
 631     my @foo_views = $c->view(qr{^Foo});
 632
 633 =cut
 634
 635 sub view {
 636     my ( $c, $name, @args ) = @_;
 637
 638     if (ref $c && !$name) {
 639         return $c->stash->{current_view_instance}
 640             if $c->stash->{current_view_instance};
 641
 642         $name = $c->stash->{current_view}
 643             if $c->stash->{current_view};
 644     }
 645
 646     return $c->container->get_component_from_sub_container( 'view', $name, $c, @args);
 647 }
 648
 649 =head2 $c->controllers
 650
 651 Returns the available names which can be passed to $c->controller
 652
 653 =cut
 654
 655 sub controllers {
 656     my ( $c ) = @_;
 657     return $c->container->get_sub_container('controller')->get_service_list;
 658 }
 659
 660 =head2 $c->models
 661
 662 Returns the available names which can be passed to $c->model
 663
 664 =cut
 665
 666 sub models {
 667     my ( $c ) = @_;
 668     return $c->container->get_sub_container('model')->get_service_list;
 669 }
 670
 671
 672 =head2 $c->views
 673
 674 Returns the available names which can be passed to $c->view
 675
 676 =cut
 677
 678 sub views {
 679     my ( $c ) = @_;
 680     return $c->container->get_sub_container('view')->get_service_list;
 681 }
 682
 683 sub _find_component {
 684     my ($c, $component, @args) = @_;
 685     my @result;
 686
 687     my $query = ref $component
 688               ? $component
 689               : qr{^$component$}
 690               ;
 691
 692     for my $subcontainer_name (qw/model view controller/) {
 693         my $subcontainer = $c->container->get_sub_container($subcontainer_name);
 694         my @components   = $subcontainer->get_service_list;
 695         @result          = grep { m{$component} } @components;
 696
 697         return map { $subcontainer->get_component( $_, $c, @args ) } @result
 698             if @result;
 699     }
 700
 701     # it expects an empty list on failed searches
 702     return @result;
 703 }
 704
 705 =head2 $c->comp($name)
 706
 707 =head2 $c->component($name)
 708
 709 Gets a component object by name. This method is not recommended,
 710 unless you want to get a specific component by full
 711 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
 712 should be used instead.
 713
 714 If C<$name> is a regexp, a list of components matched against the full
 715 component name will be returned.
 716
 717 =cut
 718
 719 sub component {
 720     my ( $c, $component, @args ) = @_;
 721
 722     unless ($component) {
 723         $c->log->warn("Calling \$c->component without args is deprecated");
 724         $c->log->warn("and will be removed in future releases.");
 725         return sort keys %{ $c->components };
 726     }
 727
 728     my ($type, $name) = _get_component_type_name($component);
 729
 730     return $c->container->get_component_from_sub_container(
 731         $type, $name, $c, @args
 732     ) if $type;
 733
 734     my @result = $c->_find_component( $component, @args );
 735
 736     # list context for regexp searches
 737     return @result if ref $component;
 738
 739     # only one component (if it's found) for string searches
 740     return shift @result if @result;
 741
 742     # FIXME: I probably shouldn't be doing this
 743     # I'm keeping it temporarily for things like $c->comp('MyApp')
 744     return $c->components->{$component}
 745         if exists $c->components->{$component} and !@args;
 746
 747     $c->log->warn("Looking for '$component', but nothing was found.");
 748
 749     # I would expect to return an empty list here, but that breaks back-compat
 750     $c->log->warn("Component not found, returning the list of existing");
 751     $c->log->warn("components. This behavior is deprecated, and will be");
 752     $c->log->warn("removed in future releases.");
 753
 754     return sort keys %{ $c->components };
 755 }
 756
 757 =head2 CLASS DATA AND HELPER CLASSES
 758
 759 =head2 $c->config
 760
 761 Returns or takes a hashref containing the application's configuration.
 762
 763     __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
 764
 765 You can also use a C<YAML>, C<XML> or L<Config::General> config file
 766 like C<myapp.conf> in your applications home directory. See
 767 L<Catalyst::Plugin::ConfigLoader>.
 768
 769 =head3 Cascading configuration
 770
 771 The config method is present on all Catalyst components, and configuration
 772 will be merged when an application is started. Configuration loaded with
 773 L<Catalyst::Plugin::ConfigLoader> takes precedence over other configuration,
 774 followed by configuration in your top level C<MyApp> class. These two
 775 configurations are merged, and then configuration data whose hash key matches a
 776 component name is merged with configuration for that component.
 777
 778 The configuration for a component is then passed to the C<new> method when a
 779 component is constructed.
 780
 781 For example:
 782
 783     MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
 784     MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
 785
 786 will mean that C<MyApp::Model::Foo> receives the following data when
 787 constructed:
 788
 789     MyApp::Model::Foo->new({
 790         bar => 'baz',
 791         quux => 'frob',
 792         overrides => 'me',
 793     });
 794
 795 It's common practice to use a Moose attribute
 796 on the receiving component to access the config value.
 797
 798     package MyApp::Model::Foo;
 799
 800     use Moose;
 801
 802     # this attr will receive 'baz' at construction time
 803     has 'bar' => (
 804         is  => 'rw',
 805         isa => 'Str',
 806     );
 807
 808 You can then get the value 'baz' by calling $c->model('Foo')->bar
 809 (or $self->bar inside code in the model).
 810
 811 B<NOTE:> you MUST NOT call C<< $self->config >> or C<< __PACKAGE__->config >>
 812 as a way of reading config within your code, as this B<will not> give you the
 813 correctly merged config back. You B<MUST> take the config values supplied to
 814 the constructor and use those instead.
 815
 816 =cut
 817
 818 around config => sub {
 819     my $orig = shift;
 820     my $c = shift;
 821
 822     croak('Setting config after setup has been run is not allowed.')
 823         if ( @_ and $c->setup_finished );
 824
 825     $c->$orig(@_);
 826 };
 827
 828 =head2 $c->log
 829
 830 Returns the logging object instance. Unless it is already set, Catalyst
 831 sets this up with a L<Catalyst::Log> object. To use your own log class,
 832 set the logger with the C<< __PACKAGE__->log >> method prior to calling
 833 C<< __PACKAGE__->setup >>.
 834
 835  __PACKAGE__->log( MyLogger->new );
 836  __PACKAGE__->setup;
 837
 838 And later:
 839
 840     $c->log->info( 'Now logging with my own logger!' );
 841
 842 Your log class should implement the methods described in
 843 L<Catalyst::Log>.
 844
 845
 846 =head2 $c->debug
 847
 848 Returns 1 if debug mode is enabled, 0 otherwise.
 849
 850 You can enable debug mode in several ways:
 851
 852 =over
 853
 854 =item By calling myapp_server.pl with the -d flag
 855
 856 =item With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
 857
 858 =item The -Debug option in your MyApp.pm
 859
 860 =item By declaring C<sub debug { 1 }> in your MyApp.pm.
 861
 862 =back
 863
 864 The first three also set the log level to 'debug'.
 865
 866 Calling C<< $c->debug(1) >> has no effect.
 867
 868 =cut
 869
 870 sub debug { 0 }
 871
 872 =head2 $c->dispatcher
 873
 874 Returns the dispatcher instance. See L<Catalyst::Dispatcher>.
 875
 876 =head2 $c->engine
 877
 878 Returns the engine instance. See L<Catalyst::Engine>.
 879
 880
 881 =head2 UTILITY METHODS
 882
 883 =head2 $c->path_to(@path)
 884
 885 Merges C<@path> with C<< $c->config->{home} >> and returns a
 886 L<Path::Class::Dir> object. Note you can usually use this object as
 887 a filename, but sometimes you will have to explicitly stringify it
 888 yourself by calling the C<< ->stringify >> method.
 889
 890 For example:
 891
 892     $c->path_to( 'db', 'sqlite.db' );
 893
 894 =cut
 895
 896 sub path_to {
 897     my ( $c, @path ) = @_;
 898     my $path = Path::Class::Dir->new( $c->config->{home}, @path );
 899     if ( -d $path ) { return $path }
 900     else { return Path::Class::File->new( $c->config->{home}, @path ) }
 901 }
 902
 903 =head2 $c->plugin( $name, $class, @args )
 904
 905 Helper method for plugins. It creates a class data accessor/mutator and
 906 loads and instantiates the given class.
 907
 908     MyApp->plugin( 'prototype', 'HTML::Prototype' );
 909
 910     $c->prototype->define_javascript_functions;
 911
 912 B<Note:> This method of adding plugins is deprecated. The ability
 913 to add plugins like this B<will be removed> in a Catalyst 5.81.
 914 Please do not use this functionality in new code.
 915
 916 =cut
 917
 918 sub plugin {
 919     my ( $class, $name, $plugin, @args ) = @_;
 920
 921     # See block comment in t/aggregate/unit_core_plugin.t
 922     $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in Catalyst 5.81/);
 923
 924     $class->_register_plugin( $plugin, 1 );
 925
 926     eval { $plugin->import };
 927     $class->mk_classdata($name);
 928     my $obj;
 929     eval { $obj = $plugin->new(@args) };
 930
 931     if ($@) {
 932         Catalyst::Exception->throw( message =>
 933               qq/Couldn't instantiate instant plugin "$plugin", "$@"/ );
 934     }
 935
 936     $class->$name($obj);
 937     $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
 938       if $class->debug;
 939 }
 940
 941 =head2 MyApp->setup
 942
 943 Initializes the dispatcher and engine, loads any plugins, and loads the
 944 model, view, and controller components. You may also specify an array
 945 of plugins to load here, if you choose to not load them in the C<use
 946 Catalyst> line.
 947
 948     MyApp->setup;
 949     MyApp->setup( qw/-Debug/ );
 950
 951 =cut
 952
 953 sub setup {
 954     my ( $class, @arguments ) = @_;
 955     croak('Running setup more than once')
 956         if ( $class->setup_finished );
 957
 958     unless ( $class->isa('Catalyst') ) {
 959
 960         Catalyst::Exception->throw(
 961             message => qq/'$class' does not inherit from Catalyst/ );
 962     }
 963
 964     if ( $class->arguments ) {
 965         @arguments = ( @arguments, @{ $class->arguments } );
 966     }
 967
 968     # Process options
 969     my $flags = {};
 970
 971     foreach (@arguments) {
 972
 973         if (/^-Debug$/) {
 974             $flags->{log} =
 975               ( $flags->{log} ) ? 'debug,' . $flags->{log} : 'debug';
 976         }
 977         elsif (/^-(\w+)=?(.*)$/) {
 978             $flags->{ lc $1 } = $2;
 979         }
 980         else {
 981             push @{ $flags->{plugins} }, $_;
 982         }
 983     }
 984
 985     $class->setup_config();
 986     $class->setup_home( delete $flags->{home} );
 987
 988     $class->setup_log( delete $flags->{log} );
 989     $class->setup_plugins( delete $flags->{plugins} );
 990     $class->setup_dispatcher( delete $flags->{dispatcher} );
 991     $class->setup_engine( delete $flags->{engine} );
 992     $class->setup_stats( delete $flags->{stats} );
 993
 994     for my $flag ( sort keys %{$flags} ) {
 995
 996         if ( my $code = $class->can( 'setup_' . $flag ) ) {
 997             &$code( $class, delete $flags->{$flag} );
 998         }
 999         else {
1000             $class->log->warn(qq/Unknown flag "$flag"/);
1001         }
1002     }
1003
1004     eval { require Catalyst::Devel; };
1005     if( !$@ && $ENV{CATALYST_SCRIPT_GEN} && ( $ENV{CATALYST_SCRIPT_GEN} < $Catalyst::Devel::CATALYST_SCRIPT_GEN ) ) {
1006         $class->log->warn(<<"EOF");
1007 You are running an old script!
1008
1009   Please update by running (this will overwrite existing files):
1010     catalyst.pl -force -scripts $class
1011
1012   or (this will not overwrite existing files):
1013     catalyst.pl -scripts $class
1014
1015 EOF
1016     }
1017
1018     if ( $class->debug ) {
1019         my @plugins = map { "$_  " . ( $_->VERSION || '' ) } $class->registered_plugins;
1020
1021         if (@plugins) {
1022             my $column_width = Catalyst::Utils::term_width() - 6;
1023             my $t = Text::SimpleTable->new($column_width);
1024             $t->row($_) for @plugins;
1025             $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
1026         }
1027
1028         my $dispatcher = $class->dispatcher;
1029         my $engine     = $class->engine;
1030         my $home       = $class->config->{home};
1031
1032         $class->log->debug(sprintf(q/Loaded dispatcher "%s"/, blessed($dispatcher)));
1033         $class->log->debug(sprintf(q/Loaded engine "%s"/, blessed($engine)));
1034
1035         $home
1036           ? ( -d $home )
1037           ? $class->log->debug(qq/Found home "$home"/)
1038           : $class->log->debug(qq/Home "$home" doesn't exist/)
1039           : $class->log->debug(q/Couldn't find home/);
1040     }
1041
1042     # Call plugins setup, this is stupid and evil.
1043     # Also screws C3 badly on 5.10, hack to avoid.
1044     {
1045         no warnings qw/redefine/;
1046         local *setup = sub { };
1047         $class->setup unless $Catalyst::__AM_RESTARTING;
1048     }
1049
1050     # Initialize our data structure
1051     $class->components( {} ); # XXX - Remove!
1052
1053     $class->setup_components;
1054
1055     if ( $class->debug ) { # XXX - Fixme to be a method on the container? (Or at least get a) data structure back from the container!!
1056         my $column_width = Catalyst::Utils::term_width() - 8 - 9;
1057         my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] );
1058         for my $comp ( sort keys %{ $class->components } ) {
1059             my $type = ref $class->components->{$comp} ? 'instance' : 'class';
1060             $t->row( $comp, $type );
1061         }
1062         $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
1063           if ( keys %{ $class->components } );
1064     }
1065
1066     # Add our self to components, since we are also a component
1067     if( $class->isa('Catalyst::Controller') ){
1068       $class->components->{$class} = $class;
1069     }
1070
1071     $class->setup_actions;
1072
1073     if ( $class->debug ) {
1074         my $name = $class->config->{name} || 'Application';
1075         $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
1076     }
1077
1078     # Make sure that the application class becomes immutable at this point,
1079     B::Hooks::EndOfScope::on_scope_end {
1080         return if $@;
1081         my $meta = Class::MOP::get_metaclass_by_name($class);
1082         if (
1083             $meta->is_immutable
1084             && ! { $meta->immutable_options }->{replace_constructor}
1085             && (
1086                    $class->isa('Class::Accessor::Fast')
1087                 || $class->isa('Class::Accessor')
1088             )
1089         ) {
1090             warn "You made your application class ($class) immutable, "
1091                 . "but did not inline the\nconstructor. "
1092                 . "This will break catalyst, as your app \@ISA "
1093                 . "Class::Accessor(::Fast)?\nPlease pass "
1094                 . "(replace_constructor => 1)\nwhen making your class immutable.\n";
1095         }
1096         $meta->make_immutable(
1097             replace_constructor => 1,
1098         ) unless $meta->is_immutable;
1099     };
1100
1101     if ($class->config->{case_sensitive}) {
1102         $class->log->warn($class . "->config->{case_sensitive} is set.");
1103         $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
1104     }
1105
1106     $class->setup_finalize;
1107     # Should be the last thing we do so that user things hooking
1108     # setup_finalize can log..
1109     $class->log->_flush() if $class->log->can('_flush');
1110     return 1; # Explicit return true as people have __PACKAGE__->setup as the last thing in their class. HATE.
1111 }
1112
1113 =head2 $app->setup_finalize
1114
1115 A hook to attach modifiers to. This method does not do anything except set the
1116 C<setup_finished> accessor.
1117
1118 Applying method modifiers to the C<setup> method doesn't work, because of quirky things done for plugin setup.
1119
1120 Example:
1121
1122     after setup_finalize => sub {
1123         my $app = shift;
1124
1125         ## do stuff here..
1126     };
1127
1128 =cut
1129
1130 sub setup_finalize {
1131     my ($class) = @_;
1132     $class->setup_finished(1);
1133 }
1134
1135 =head2 $c->uri_for( $path?, @args?, \%query_values? )
1136
1137 =head2 $c->uri_for( $action, \@captures?, @args?, \%query_values? )
1138
1139 Constructs an absolute L<URI> object based on the application root, the
1140 provided path, and the additional arguments and query parameters provided.
1141 When used as a string, provides a textual URI.  If you need more flexibility
1142 than this (i.e. the option to provide relative URIs etc.) see
1143 L<Catalyst::Plugin::SmartURI>.
1144
1145 If no arguments are provided, the URI for the current action is returned.
1146 To return the current action and also provide @args, use
1147 C<< $c->uri_for( $c->action, @args ) >>.
1148
1149 If the first argument is a string, it is taken as a public URI path relative
1150 to C<< $c->namespace >> (if it doesn't begin with a forward slash) or
1151 relative to the application root (if it does). It is then merged with
1152 C<< $c->request->base >>; any C<@args> are appended as additional path
1153 components; and any C<%query_values> are appended as C<?foo=bar> parameters.
1154
1155 If the first argument is a L<Catalyst::Action> it represents an action which
1156 will have its path resolved using C<< $c->dispatcher->uri_for_action >>. The
1157 optional C<\@captures> argument (an arrayref) allows passing the captured
1158 variables that are needed to fill in the paths of Chained and Regex actions;
1159 once the path is resolved, C<uri_for> continues as though a path was
1160 provided, appending any arguments or parameters and creating an absolute
1161 URI.
1162
1163 The captures for the current request can be found in
1164 C<< $c->request->captures >>, and actions can be resolved using
1165 C<< Catalyst::Controller->action_for($name) >>. If you have a private action
1166 path, use C<< $c->uri_for_action >> instead.
1167
1168   # Equivalent to $c->req->uri
1169   $c->uri_for($c->action, $c->req->captures,
1170       @{ $c->req->args }, $c->req->params);
1171
1172   # For the Foo action in the Bar controller
1173   $c->uri_for($c->controller('Bar')->action_for('Foo'));
1174
1175   # Path to a static resource
1176   $c->uri_for('/static/images/logo.png');
1177
1178 =cut
1179
1180 sub uri_for {
1181     my ( $c, $path, @args ) = @_;
1182
1183     if (blessed($path) && $path->isa('Catalyst::Controller')) {
1184         $path = $path->path_prefix;
1185         $path =~ s{/+\z}{};
1186         $path .= '/';
1187     }
1188
1189     undef($path) if (defined $path && $path eq '');
1190
1191     my $params =
1192       ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
1193
1194     carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
1195     foreach my $arg (@args) {
1196         utf8::encode($arg) if utf8::is_utf8($arg);
1197         $arg =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1198     }
1199
1200     if ( blessed($path) ) { # action object
1201         s|/|%2F|g for @args;
1202         my $captures = [ map { s|/|%2F|g; $_; }
1203                         ( scalar @args && ref $args[0] eq 'ARRAY'
1204                          ? @{ shift(@args) }
1205                          : ()) ];
1206
1207         foreach my $capture (@$captures) {
1208             utf8::encode($capture) if utf8::is_utf8($capture);
1209             $capture =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1210         }
1211
1212         my $action = $path;
1213         $path = $c->dispatcher->uri_for_action($action, $captures);
1214         if (not defined $path) {
1215             $c->log->debug(qq/Can't find uri_for action '$action' @$captures/)
1216                 if $c->debug;
1217             return undef;
1218         }
1219         $path = '/' if $path eq '';
1220     }
1221
1222     unshift(@args, $path);
1223
1224     unless (defined $path && $path =~ s!^/!!) { # in-place strip
1225         my $namespace = $c->namespace;
1226         if (defined $path) { # cheesy hack to handle path '../foo'
1227            $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
1228         }
1229         unshift(@args, $namespace || '');
1230     }
1231
1232     # join args with '/', or a blank string
1233     my $args = join('/', grep { defined($_) } @args);
1234     $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
1235     $args =~ s!^/+!!;
1236     my $base = $c->req->base;
1237     my $class = ref($base);
1238     $base =~ s{(?<!/)$}{/};
1239
1240     my $query = '';
1241
1242     if (my @keys = keys %$params) {
1243       # somewhat lifted from URI::_query's query_form
1244       $query = '?'.join('&', map {
1245           my $val = $params->{$_};
1246           s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go;
1247           s/ /+/g;
1248           my $key = $_;
1249           $val = '' unless defined $val;
1250           (map {
1251               my $param = "$_";
1252               utf8::encode( $param ) if utf8::is_utf8($param);
1253               # using the URI::Escape pattern here so utf8 chars survive
1254               $param =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1255               $param =~ s/ /+/g;
1256               "${key}=$param"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
1257       } @keys);
1258     }
1259
1260     my $res = bless(\"${base}${args}${query}", $class);
1261     $res;
1262 }
1263
1264 =head2 $c->uri_for_action( $path, \@captures?, @args?, \%query_values? )
1265
1266 =head2 $c->uri_for_action( $action, \@captures?, @args?, \%query_values? )
1267
1268 =over
1269
1270 =item $path
1271
1272 A private path to the Catalyst action you want to create a URI for.
1273
1274 This is a shortcut for calling C<< $c->dispatcher->get_action_by_path($path)
1275 >> and passing the resulting C<$action> and the remaining arguments to C<<
1276 $c->uri_for >>.
1277
1278 You can also pass in a Catalyst::Action object, in which case it is passed to
1279 C<< $c->uri_for >>.
1280
1281 Note that although the path looks like a URI that dispatches to the wanted action, it is not a URI, but an internal path to that action.
1282
1283 For example, if the action looks like:
1284
1285  package MyApp::Controller::Users;
1286
1287  sub lst : Path('the-list') {}
1288
1289 You can use:
1290
1291  $c->uri_for_action('/users/lst')
1292
1293 and it will create the URI /users/the-list.
1294
1295 =back
1296
1297 =cut
1298
1299 sub uri_for_action {
1300     my ( $c, $path, @args ) = @_;
1301     my $action = blessed($path)
1302       ? $path
1303       : $c->dispatcher->get_action_by_path($path);
1304     unless (defined $action) {
1305       croak "Can't find action for path '$path'";
1306     }
1307     return $c->uri_for( $action, @args );
1308 }
1309
1310 =head2 $c->welcome_message
1311
1312 Returns the Catalyst welcome HTML page.
1313
1314 =cut
1315
1316 sub welcome_message {
1317     my $c      = shift;
1318     my $name   = $c->config->{name};
1319     my $logo   = $c->uri_for('/static/images/catalyst_logo.png');
1320     my $prefix = Catalyst::Utils::appprefix( ref $c );
1321     $c->response->content_type('text/html; charset=utf-8');
1322     return <<"EOF";
1323 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1324     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1325 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1326     <head>
1327     <meta http-equiv="Content-Language" content="en" />
1328     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1329         <title>$name on Catalyst $VERSION</title>
1330         <style type="text/css">
1331             body {
1332                 color: #000;
1333                 background-color: #eee;
1334             }
1335             div#content {
1336                 width: 640px;
1337                 margin-left: auto;
1338                 margin-right: auto;
1339                 margin-top: 10px;
1340                 margin-bottom: 10px;
1341                 text-align: left;
1342                 background-color: #ccc;
1343                 border: 1px solid #aaa;
1344             }
1345             p, h1, h2 {
1346                 margin-left: 20px;
1347                 margin-right: 20px;
1348                 font-family: verdana, tahoma, sans-serif;
1349             }
1350             a {
1351                 font-family: verdana, tahoma, sans-serif;
1352             }
1353             :link, :visited {
1354                     text-decoration: none;
1355                     color: #b00;
1356                     border-bottom: 1px dotted #bbb;
1357             }
1358             :link:hover, :visited:hover {
1359                     color: #555;
1360             }
1361             div#topbar {
1362                 margin: 0px;
1363             }
1364             pre {
1365                 margin: 10px;
1366                 padding: 8px;
1367             }
1368             div#answers {
1369                 padding: 8px;
1370                 margin: 10px;
1371                 background-color: #fff;
1372                 border: 1px solid #aaa;
1373             }
1374             h1 {
1375                 font-size: 0.9em;
1376                 font-weight: normal;
1377                 text-align: center;
1378             }
1379             h2 {
1380                 font-size: 1.0em;
1381             }
1382             p {
1383                 font-size: 0.9em;
1384             }
1385             p img {
1386                 float: right;
1387                 margin-left: 10px;
1388             }
1389             span#appname {
1390                 font-weight: bold;
1391                 font-size: 1.6em;
1392             }
1393         </style>
1394     </head>
1395     <body>
1396         <div id="content">
1397             <div id="topbar">
1398                 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1399                     $VERSION</h1>
1400              </div>
1401              <div id="answers">
1402                  <p>
1403                  <img src="$logo" alt="Catalyst Logo" />
1404                  </p>
1405                  <p>Welcome to the  world of Catalyst.
1406                     This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1407                     framework will make web development something you had
1408                     never expected it to be: Fun, rewarding, and quick.</p>
1409                  <h2>What to do now?</h2>
1410                  <p>That really depends  on what <b>you</b> want to do.
1411                     We do, however, provide you with a few starting points.</p>
1412                  <p>If you want to jump right into web development with Catalyst
1413                     you might want to start with a tutorial.</p>
1414 <pre>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Tutorial.pod">Catalyst::Manual::Tutorial</a></code>
1415 </pre>
1416 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1417 <pre>
1418 <code>perldoc <a href="http://cpansearch.perl.org/dist/Catalyst-Manual/lib/Catalyst/Manual/Intro.pod">Catalyst::Manual::Intro</a>
1419 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1420 </code></pre>
1421                  <h2>What to do next?</h2>
1422                  <p>Next it's time to write an actual application. Use the
1423                     helper scripts to generate <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AController%3A%3A&amp;mode=all">controllers</a>,
1424                     <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AModel%3A%3A&amp;mode=all">models</a>, and
1425                     <a href="http://cpansearch.perl.org/search?query=Catalyst%3A%3AView%3A%3A&amp;mode=all">views</a>;
1426                     they can save you a lot of work.</p>
1427                     <pre><code>script/${prefix}_create.pl --help</code></pre>
1428                     <p>Also, be sure to check out the vast and growing
1429                     collection of <a href="http://search.cpan.org/search?query=Catalyst">plugins for Catalyst on CPAN</a>;
1430                     you are likely to find what you need there.
1431                     </p>
1432
1433                  <h2>Need help?</h2>
1434                  <p>Catalyst has a very active community. Here are the main places to
1435                     get in touch with us.</p>
1436                  <ul>
1437                      <li>
1438                          <a href="http://dev.catalyst.perl.org">Wiki</a>
1439                      </li>
1440                      <li>
1441                          <a href="http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst">Mailing-List</a>
1442                      </li>
1443                      <li>
1444                          <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1445                      </li>
1446                  </ul>
1447                  <h2>In conclusion</h2>
1448                  <p>The Catalyst team hopes you will enjoy using Catalyst as much
1449                     as we enjoyed making it. Please contact us if you have ideas
1450                     for improvement or other feedback.</p>
1451              </div>
1452          </div>
1453     </body>
1454 </html>
1455 EOF
1456 }
1457
1458 =head1 INTERNAL METHODS
1459
1460 These methods are not meant to be used by end users.
1461
1462 =head2 $c->components
1463
1464 Returns a hash of components.
1465
1466 =cut
1467
1468 # FIXME - We deal with ->components({'Foo' => 'Bar'})
1469 #         however we DO NOT deal with ->components->{Foo} = 'Bar'
1470 #         We should return a locked hash back to the user? So that if they try the latter, they
1471 #         get breakage, rather than their addition being silently ignored?
1472 around components => sub {
1473     my $orig  = shift;
1474     my $class = shift;
1475     my $comps = shift;
1476
1477     return $class->$orig if ( !$comps );
1478
1479 # FIXME: should this ugly kludge exist?
1480     $class->setup_config unless defined $class->container;
1481
1482 # FIXME: should there be a warning here, not to use this accessor to create the components?
1483     my $components = {};
1484
1485     my $containers;
1486     $containers->{$_} = $class->container->get_sub_container($_) for qw(model view controller);
1487
1488     for my $component ( keys %$comps ) {
1489         $components->{ $component } = $comps->{$component};
1490
1491         my ($type, $name) = _get_component_type_name($component);
1492
1493         $containers->{$type}->add_service(Catalyst::IOC::BlockInjection->new( name => $name, block => sub { return $class->setup_component($component) } ));
1494     }
1495
1496     return $class->$orig($components);
1497 };
1498
1499 =head2 $c->context_class
1500
1501 Returns or sets the context class.
1502
1503 =head2 $c->counter
1504
1505 Returns a hashref containing coderefs and execution counts (needed for
1506 deep recursion detection).
1507
1508 =head2 $c->depth
1509
1510 Returns the number of actions on the current internal execution stack.
1511
1512 =head2 $c->dispatch
1513
1514 Dispatches a request to actions.
1515
1516 =cut
1517
1518 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
1519
1520 =head2 $c->dispatcher_class
1521
1522 Returns or sets the dispatcher class.
1523
1524 =head2 $c->dump_these
1525
1526 Returns a list of 2-element array references (name, structure) pairs
1527 that will be dumped on the error page in debug mode.
1528
1529 =cut
1530
1531 sub dump_these {
1532     my $c = shift;
1533     [ Request => $c->req ],
1534     [ Response => $c->res ],
1535     [ Stash => $c->stash ],
1536     [ Config => $c->config ];
1537 }
1538
1539 =head2 $c->engine_class
1540
1541 Returns or sets the engine class.
1542
1543 =head2 $c->execute( $class, $coderef )
1544
1545 Execute a coderef in given class and catch exceptions. Errors are available
1546 via $c->error.
1547
1548 =cut
1549
1550 sub execute {
1551     my ( $c, $class, $code ) = @_;
1552     $class = $c->component($class) || $class;
1553     $c->state(0);
1554
1555     if ( $c->depth >= $RECURSION ) {
1556         my $action = $code->reverse();
1557         $action = "/$action" unless $action =~ /->/;
1558         my $error = qq/Deep recursion detected calling "${action}"/;
1559         $c->log->error($error);
1560         $c->error($error);
1561         $c->state(0);
1562         return $c->state;
1563     }
1564
1565     my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
1566
1567     push( @{ $c->stack }, $code );
1568
1569     no warnings 'recursion';
1570     # N.B. This used to be combined, but I have seen $c get clobbered if so, and
1571     #      I have no idea how, ergo $ret (which appears to fix the issue)
1572     eval { my $ret = $code->execute( $class, $c, @{ $c->req->args } ) || 0; $c->state( $ret ) };
1573
1574     $c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
1575
1576     my $last = pop( @{ $c->stack } );
1577
1578     if ( my $error = $@ ) {
1579         if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) {
1580             $error->rethrow if $c->depth > 1;
1581         }
1582         elsif ( blessed($error) and $error->isa('Catalyst::Exception::Go') ) {
1583             $error->rethrow if $c->depth > 0;
1584         }
1585         else {
1586             unless ( ref $error ) {
1587                 no warnings 'uninitialized';
1588                 chomp $error;
1589                 my $class = $last->class;
1590                 my $name  = $last->name;
1591                 $error = qq/Caught exception in $class->$name "$error"/;
1592             }
1593             $c->error($error);
1594         }
1595         $c->state(0);
1596     }
1597     return $c->state;
1598 }
1599
1600 sub _stats_start_execute {
1601     my ( $c, $code ) = @_;
1602     my $appclass = ref($c) || $c;
1603     return if ( ( $code->name =~ /^_.*/ )
1604         && ( !$appclass->config->{show_internal_actions} ) );
1605
1606     my $action_name = $code->reverse();
1607     $c->counter->{$action_name}++;
1608
1609     my $action = $action_name;
1610     $action = "/$action" unless $action =~ /->/;
1611
1612     # determine if the call was the result of a forward
1613     # this is done by walking up the call stack and looking for a calling
1614     # sub of Catalyst::forward before the eval
1615     my $callsub = q{};
1616     for my $index ( 2 .. 11 ) {
1617         last
1618         if ( ( caller($index) )[0] eq 'Catalyst'
1619             && ( caller($index) )[3] eq '(eval)' );
1620
1621         if ( ( caller($index) )[3] =~ /forward$/ ) {
1622             $callsub = ( caller($index) )[3];
1623             $action  = "-> $action";
1624             last;
1625         }
1626     }
1627
1628     my $uid = $action_name . $c->counter->{$action_name};
1629
1630     # is this a root-level call or a forwarded call?
1631     if ( $callsub =~ /forward$/ ) {
1632         my $parent = $c->stack->[-1];
1633
1634         # forward, locate the caller
1635         if ( defined $parent && exists $c->counter->{"$parent"} ) {
1636             $c->stats->profile(
1637                 begin  => $action,
1638                 parent => "$parent" . $c->counter->{"$parent"},
1639                 uid    => $uid,
1640             );
1641         }
1642         else {
1643
1644             # forward with no caller may come from a plugin
1645             $c->stats->profile(
1646                 begin => $action,
1647                 uid   => $uid,
1648             );
1649         }
1650     }
1651     else {
1652
1653         # root-level call
1654         $c->stats->profile(
1655             begin => $action,
1656             uid   => $uid,
1657         );
1658     }
1659     return $action;
1660
1661 }
1662
1663 sub _stats_finish_execute {
1664     my ( $c, $info ) = @_;
1665     $c->stats->profile( end => $info );
1666 }
1667
1668 =head2 $c->finalize
1669
1670 Finalizes the request.
1671
1672 =cut
1673
1674 sub finalize {
1675     my $c = shift;
1676
1677     for my $error ( @{ $c->error } ) {
1678         $c->log->error($error);
1679     }
1680
1681     # Allow engine to handle finalize flow (for POE)
1682     my $engine = $c->engine;
1683     if ( my $code = $engine->can('finalize') ) {
1684         $engine->$code($c);
1685     }
1686     else {
1687
1688         $c->finalize_uploads;
1689
1690         # Error
1691         if ( $#{ $c->error } >= 0 ) {
1692             $c->finalize_error;
1693         }
1694
1695         $c->finalize_headers;
1696
1697         # HEAD request
1698         if ( $c->request->method eq 'HEAD' ) {
1699             $c->response->body('');
1700         }
1701
1702         $c->finalize_body;
1703     }
1704
1705     $c->log_response;
1706
1707     if ($c->use_stats) {
1708         my $elapsed = sprintf '%f', $c->stats->elapsed;
1709         my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
1710         $c->log->info(
1711             "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
1712     }
1713
1714     return $c->response->status;
1715 }
1716
1717 =head2 $c->finalize_body
1718
1719 Finalizes body.
1720
1721 =cut
1722
1723 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
1724
1725 =head2 $c->finalize_cookies
1726
1727 Finalizes cookies.
1728
1729 =cut
1730
1731 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
1732
1733 =head2 $c->finalize_error
1734
1735 Finalizes error.
1736
1737 =cut
1738
1739 sub finalize_error { my $c = shift; $c->engine->finalize_error( $c, @_ ) }
1740
1741 =head2 $c->finalize_headers
1742
1743 Finalizes headers.
1744
1745 =cut
1746
1747 sub finalize_headers {
1748     my $c = shift;
1749
1750     my $response = $c->response; #accessor calls can add up?
1751
1752     # Check if we already finalized headers
1753     return if $response->finalized_headers;
1754
1755     # Handle redirects
1756     if ( my $location = $response->redirect ) {
1757         $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
1758         $response->header( Location => $location );
1759
1760         if ( !$response->has_body ) {
1761             # Add a default body if none is already present
1762             $response->body(
1763                 qq{<html><body><p>This item has moved <a href="$location">here</a>.</p></body></html>}
1764             );
1765         }
1766     }
1767
1768     # Content-Length
1769     if ( defined $response->body && length $response->body && !$response->content_length ) {
1770
1771         # get the length from a filehandle
1772         if ( blessed( $response->body ) && $response->body->can('read') || ref( $response->body ) eq 'GLOB' )
1773         {
1774             my $stat = stat $response->body;
1775             if ( $stat && $stat->size > 0 ) {
1776                 $response->content_length( $stat->size );
1777             }
1778             else {
1779                 $c->log->warn('Serving filehandle without a content-length');
1780             }
1781         }
1782         else {
1783             # everything should be bytes at this point, but just in case
1784             $response->content_length( length( $response->body ) );
1785         }
1786     }
1787
1788     # Errors
1789     if ( $response->status =~ /^(1\d\d|[23]04)$/ ) {
1790         $response->headers->remove_header("Content-Length");
1791         $response->body('');
1792     }
1793
1794     $c->finalize_cookies;
1795
1796     $c->engine->finalize_headers( $c, @_ );
1797
1798     # Done
1799     $response->finalized_headers(1);
1800 }
1801
1802 =head2 $c->finalize_output
1803
1804 An alias for finalize_body.
1805
1806 =head2 $c->finalize_read
1807
1808 Finalizes the input after reading is complete.
1809
1810 =cut
1811
1812 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
1813
1814 =head2 $c->finalize_uploads
1815
1816 Finalizes uploads. Cleans up any temporary files.
1817
1818 =cut
1819
1820 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
1821
1822 =head2 $c->get_action( $action, $namespace )
1823
1824 Gets an action in a given namespace.
1825
1826 =cut
1827
1828 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
1829
1830 =head2 $c->get_actions( $action, $namespace )
1831
1832 Gets all actions of a given name in a namespace and all parent
1833 namespaces.
1834
1835 =cut
1836
1837 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
1838
1839 =head2 $app->handle_request( @arguments )
1840
1841 Called to handle each HTTP request.
1842
1843 =cut
1844
1845 sub handle_request {
1846     my ( $class, @arguments ) = @_;
1847
1848     # Always expect worst case!
1849     my $status = -1;
1850     eval {
1851         if ($class->debug) {
1852             my $secs = time - $START || 1;
1853             my $av = sprintf '%.3f', $COUNT / $secs;
1854             my $time = localtime time;
1855             $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
1856         }
1857
1858         my $c = $class->prepare(@arguments);
1859         $c->dispatch;
1860         $status = $c->finalize;
1861     };
1862
1863     if ( my $error = $@ ) {
1864         chomp $error;
1865         $class->log->error(qq/Caught exception in engine "$error"/);
1866     }
1867
1868     $COUNT++;
1869
1870     if(my $coderef = $class->log->can('_flush')){
1871         $class->log->$coderef();
1872     }
1873     return $status;
1874 }
1875
1876 =head2 $c->prepare( @arguments )
1877
1878 Creates a Catalyst context from an engine-specific request (Apache, CGI,
1879 etc.).
1880
1881 =cut
1882
1883 sub prepare {
1884     my ( $class, @arguments ) = @_;
1885
1886     # XXX
1887     # After the app/ctxt split, this should become an attribute based on something passed
1888     # into the application.
1889     $class->context_class( ref $class || $class ) unless $class->context_class;
1890
1891     my $c = $class->context_class->new({});
1892
1893     # For on-demand data
1894     $c->request->_context($c);
1895     $c->response->_context($c);
1896
1897     #surely this is not the most efficient way to do things...
1898     $c->stats($class->stats_class->new)->enable($c->use_stats);
1899     if ( $c->debug || $c->config->{enable_catalyst_header} ) {
1900         $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
1901     }
1902
1903     #XXX reuse coderef from can
1904     # Allow engine to direct the prepare flow (for POE)
1905     if ( $c->engine->can('prepare') ) {
1906         $c->engine->prepare( $c, @arguments );
1907     }
1908     else {
1909         $c->prepare_request(@arguments);
1910         $c->prepare_connection;
1911         $c->prepare_query_parameters;
1912         $c->prepare_headers;
1913         $c->prepare_cookies;
1914         $c->prepare_path;
1915
1916         # Prepare the body for reading, either by prepare_body
1917         # or the user, if they are using $c->read
1918         $c->prepare_read;
1919
1920         # Parse the body unless the user wants it on-demand
1921         unless ( ref($c)->config->{parse_on_demand} ) {
1922             $c->prepare_body;
1923         }
1924     }
1925
1926     my $method  = $c->req->method  || '';
1927     my $path    = $c->req->path;
1928     $path       = '/' unless length $path;
1929     my $address = $c->req->address || '';
1930
1931     $c->log_request;
1932
1933     $c->prepare_action;
1934
1935     return $c;
1936 }
1937
1938 =head2 $c->prepare_action
1939
1940 Prepares action. See L<Catalyst::Dispatcher>.
1941
1942 =cut
1943
1944 sub prepare_action { my $c = shift; $c->dispatcher->prepare_action( $c, @_ ) }
1945
1946 =head2 $c->prepare_body
1947
1948 Prepares message body.
1949
1950 =cut
1951
1952 sub prepare_body {
1953     my $c = shift;
1954
1955     return if $c->request->_has_body;
1956
1957     # Initialize on-demand data
1958     $c->engine->prepare_body( $c, @_ );
1959     $c->prepare_parameters;
1960     $c->prepare_uploads;
1961 }
1962
1963 =head2 $c->prepare_body_chunk( $chunk )
1964
1965 Prepares a chunk of data before sending it to L<HTTP::Body>.
1966
1967 See L<Catalyst::Engine>.
1968
1969 =cut
1970
1971 sub prepare_body_chunk {
1972     my $c = shift;
1973     $c->engine->prepare_body_chunk( $c, @_ );
1974 }
1975
1976 =head2 $c->prepare_body_parameters
1977
1978 Prepares body parameters.
1979
1980 =cut
1981
1982 sub prepare_body_parameters {
1983     my $c = shift;
1984     $c->engine->prepare_body_parameters( $c, @_ );
1985 }
1986
1987 =head2 $c->prepare_connection
1988
1989 Prepares connection.
1990
1991 =cut
1992
1993 sub prepare_connection {
1994     my $c = shift;
1995     $c->engine->prepare_connection( $c, @_ );
1996 }
1997
1998 =head2 $c->prepare_cookies
1999
2000 Prepares cookies.
2001
2002 =cut
2003
2004 sub prepare_cookies { my $c = shift; $c->engine->prepare_cookies( $c, @_ ) }
2005
2006 =head2 $c->prepare_headers
2007
2008 Prepares headers.
2009
2010 =cut
2011
2012 sub prepare_headers { my $c = shift; $c->engine->prepare_headers( $c, @_ ) }
2013
2014 =head2 $c->prepare_parameters
2015
2016 Prepares parameters.
2017
2018 =cut
2019
2020 sub prepare_parameters {
2021     my $c = shift;
2022     $c->prepare_body_parameters;
2023     $c->engine->prepare_parameters( $c, @_ );
2024 }
2025
2026 =head2 $c->prepare_path
2027
2028 Prepares path and base.
2029
2030 =cut
2031
2032 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2033
2034 =head2 $c->prepare_query_parameters
2035
2036 Prepares query parameters.
2037
2038 =cut
2039
2040 sub prepare_query_parameters {
2041     my $c = shift;
2042
2043     $c->engine->prepare_query_parameters( $c, @_ );
2044 }
2045
2046 =head2 $c->log_request
2047
2048 Writes information about the request to the debug logs.  This includes:
2049
2050 =over 4
2051
2052 =item * Request method, path, and remote IP address
2053
2054 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2055
2056 =item * Request parameters
2057
2058 =item * File uploads
2059
2060 =back
2061
2062 =cut
2063
2064 sub log_request {
2065     my $c = shift;
2066
2067     return unless $c->debug;
2068
2069     my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2070     my $request = $dump->[1];
2071
2072     my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2073     $method ||= '';
2074     $path = '/' unless length $path;
2075     $address ||= '';
2076     $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2077
2078     $c->log_request_headers($request->headers);
2079
2080     if ( my $keywords = $request->query_keywords ) {
2081         $c->log->debug("Query keywords are: $keywords");
2082     }
2083
2084     $c->log_request_parameters( query => $request->query_parameters, $request->_has_body ? (body => $request->body_parameters) : () );
2085
2086     $c->log_request_uploads($request);
2087 }
2088
2089 =head2 $c->log_response
2090
2091 Writes information about the response to the debug logs by calling
2092 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2093
2094 =cut
2095
2096 sub log_response {
2097     my $c = shift;
2098
2099     return unless $c->debug;
2100
2101     my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2102     my $response = $dump->[1];
2103
2104     $c->log_response_status_line($response);
2105     $c->log_response_headers($response->headers);
2106 }
2107
2108 =head2 $c->log_response_status_line($response)
2109
2110 Writes one line of information about the response to the debug logs.  This includes:
2111
2112 =over 4
2113
2114 =item * Response status code
2115
2116 =item * Content-Type header (if present)
2117
2118 =item * Content-Length header (if present)
2119
2120 =back
2121
2122 =cut
2123
2124 sub log_response_status_line {
2125     my ($c, $response) = @_;
2126
2127     $c->log->debug(
2128         sprintf(
2129             'Response Code: %s; Content-Type: %s; Content-Length: %s',
2130             $response->status                            || 'unknown',
2131             $response->headers->header('Content-Type')   || 'unknown',
2132             $response->headers->header('Content-Length') || 'unknown'
2133         )
2134     );
2135 }
2136
2137 =head2 $c->log_response_headers($headers);
2138
2139 Hook method which can be wrapped by plugins to log the responseheaders.
2140 No-op in the default implementation.
2141
2142 =cut
2143
2144 sub log_response_headers {}
2145
2146 =head2 $c->log_request_parameters( query => {}, body => {} )
2147
2148 Logs request parameters to debug logs
2149
2150 =cut
2151
2152 sub log_request_parameters {
2153     my $c          = shift;
2154     my %all_params = @_;
2155
2156     return unless $c->debug;
2157
2158     my $column_width = Catalyst::Utils::term_width() - 44;
2159     foreach my $type (qw(query body)) {
2160         my $params = $all_params{$type};
2161         next if ! keys %$params;
2162         my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2163         for my $key ( sort keys %$params ) {
2164             my $param = $params->{$key};
2165             my $value = defined($param) ? $param : '';
2166             $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2167         }
2168         $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2169     }
2170 }
2171
2172 =head2 $c->log_request_uploads
2173
2174 Logs file uploads included in the request to the debug logs.
2175 The parameter name, filename, file type, and file size are all included in
2176 the debug logs.
2177
2178 =cut
2179
2180 sub log_request_uploads {
2181     my $c = shift;
2182     my $request = shift;
2183     return unless $c->debug;
2184     my $uploads = $request->uploads;
2185     if ( keys %$uploads ) {
2186         my $t = Text::SimpleTable->new(
2187             [ 12, 'Parameter' ],
2188             [ 26, 'Filename' ],
2189             [ 18, 'Type' ],
2190             [ 9,  'Size' ]
2191         );
2192         for my $key ( sort keys %$uploads ) {
2193             my $upload = $uploads->{$key};
2194             for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2195                 $t->row( $key, $u->filename, $u->type, $u->size );
2196             }
2197         }
2198         $c->log->debug( "File Uploads are:\n" . $t->draw );
2199     }
2200 }
2201
2202 =head2 $c->log_request_headers($headers);
2203
2204 Hook method which can be wrapped by plugins to log the request headers.
2205 No-op in the default implementation.
2206
2207 =cut
2208
2209 sub log_request_headers {}
2210
2211 =head2 $c->log_headers($type => $headers)
2212
2213 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2214
2215 =cut
2216
2217 sub log_headers {
2218     my $c       = shift;
2219     my $type    = shift;
2220     my $headers = shift;    # an HTTP::Headers instance
2221
2222     return unless $c->debug;
2223
2224     my $column_width = Catalyst::Utils::term_width() - 28;
2225     my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2226     $headers->scan(
2227         sub {
2228             my ( $name, $value ) = @_;
2229             $t->row( $name, $value );
2230         }
2231     );
2232     $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2233 }
2234
2235
2236 =head2 $c->prepare_read
2237
2238 Prepares the input for reading.
2239
2240 =cut
2241
2242 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2243
2244 =head2 $c->prepare_request
2245
2246 Prepares the engine request.
2247
2248 =cut
2249
2250 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2251
2252 =head2 $c->prepare_uploads
2253
2254 Prepares uploads.
2255
2256 =cut
2257
2258 sub prepare_uploads {
2259     my $c = shift;
2260
2261     $c->engine->prepare_uploads( $c, @_ );
2262 }
2263
2264 =head2 $c->prepare_write
2265
2266 Prepares the output for writing.
2267
2268 =cut
2269
2270 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2271
2272 =head2 $c->request_class
2273
2274 Returns or sets the request class. Defaults to L<Catalyst::Request>.
2275
2276 =head2 $c->response_class
2277
2278 Returns or sets the response class. Defaults to L<Catalyst::Response>.
2279
2280 =head2 $c->read( [$maxlength] )
2281
2282 Reads a chunk of data from the request body. This method is designed to
2283 be used in a while loop, reading C<$maxlength> bytes on every call.
2284 C<$maxlength> defaults to the size of the request if not specified.
2285
2286 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2287 directly.
2288
2289 Warning: If you use read(), Catalyst will not process the body,
2290 so you will not be able to access POST parameters or file uploads via
2291 $c->request.  You must handle all body parsing yourself.
2292
2293 =cut
2294
2295 sub read { my $c = shift; return $c->engine->read( $c, @_ ) }
2296
2297 =head2 $c->run
2298
2299 Starts the engine.
2300
2301 =cut
2302
2303 sub run { my $c = shift; return $c->engine->run( $c, @_ ) }
2304
2305 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2306
2307 Sets an action in a given namespace.
2308
2309 =cut
2310
2311 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2312
2313 =head2 $c->setup_actions($component)
2314
2315 Sets up actions for a component.
2316
2317 =cut
2318
2319 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2320
2321 =head2 $c->setup_config
2322
2323 =cut
2324
2325 sub setup_config {
2326     my $class = shift;
2327
2328     my %args = %{ $class->config || {} };
2329
2330     my @container_classes = ( "${class}::Container", 'Catalyst::IOC::Container');
2331     unshift @container_classes, delete $args{container_class} if exists $args{container_class};
2332
2333     my $container_class = Class::MOP::load_first_existing_class(@container_classes);
2334
2335     my $container = $container_class->new( %args, name => "$class" );
2336     $class->container($container);
2337
2338     my $config = $container->resolve(service => 'config');
2339     $class->config($config);
2340     $class->finalize_config; # back-compat
2341 }
2342
2343 =head2 $c->finalize_config
2344
2345 =cut
2346
2347 sub finalize_config { }
2348
2349 =head2 $c->setup_components
2350
2351 This method is called internally to set up the application's components.
2352
2353 It finds modules by calling the L<locate_components> method, expands them to
2354 package names with the L<expand_component_module> method, and then installs
2355 each component into the application.
2356
2357 The C<setup_components> config option is passed to both of the above methods.
2358
2359 Installation of each component is performed by the L<setup_component> method,
2360 below.
2361
2362 =cut
2363
2364 sub setup_components {
2365     my $class = shift;
2366
2367     my $config  = $class->config->{ setup_components };
2368     my $search_extra = $config->{ search_extra };
2369
2370     my @comps = $class->locate_components($config);
2371     my %comps = map { $_ => 1 } @comps;
2372
2373     my $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @comps;
2374     $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
2375         qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
2376     ) if $deprecatedcatalyst_component_names;
2377
2378     for my $component ( @comps ) {
2379
2380         # We pass ignore_loaded here so that overlay files for (e.g.)
2381         # Model::DBI::Schema sub-classes are loaded - if it's in @comps
2382         # we know M::P::O found a file on disk so this is safe
2383
2384         Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
2385     }
2386
2387     my $containers;
2388     $containers->{$_} = $class->container->get_sub_container($_) for qw(model view controller);
2389
2390     for my $component (@comps) {
2391         my $instance = $class->components->{ $component } = $class->setup_component($component);
2392         if ( my ($type, $name) = _get_component_type_name($component, $search_extra) ) {
2393             $containers->{$type}->add_service(Catalyst::IOC::BlockInjection->new( name => $name, block => sub { return $instance } ));
2394         }
2395         my @expanded_components = $instance->can('expand_modules')
2396             ? $instance->expand_modules( $component, $config )
2397             : $class->expand_component_module( $component, $config );
2398         for my $component (@expanded_components) {
2399             next if $comps{$component};
2400
2401             $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @expanded_components;
2402             $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
2403                 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
2404             ) if $deprecatedcatalyst_component_names;
2405
2406             if (my ($type, $name) = _get_component_type_name($component, $search_extra)) {
2407                 $containers->{$type}->add_service(Catalyst::IOC::BlockInjection->new( name => $name, block => sub { return $class->setup_component($component) } ));
2408             }
2409
2410             # FIXME - Remove this!!
2411             $class->components->{ $component } = $class->setup_component($component);
2412         }
2413     }
2414
2415     $containers->{model}->make_single_default;
2416     $containers->{view}->make_single_default;
2417 }
2418
2419 # FIXME: should this sub exist?
2420 # should it be moved to Catalyst::Utils,
2421 # or replaced by something already existing there?
2422 sub _get_component_type_name {
2423     my ( $component, $search_extra) = @_;
2424     $search_extra ||= [];
2425     my @search_extra = map { s/^:://; lc $_ } @$search_extra;
2426
2427     my @parts = split /::/, $component;
2428
2429     if (scalar @parts == 1) {
2430         return (undef, $component);
2431     }
2432
2433     while (my $type = shift @parts) {
2434         return ('controller', join '::', @parts)
2435             if $type =~ /^(c|controller)$/i;
2436
2437         return ('model', join '::', @parts)
2438             if $type =~ /^(m|model)$/i;
2439
2440         return ('view', join '::', @parts)
2441             if $type =~ /^(v|view)$/i;
2442
2443         return (_get_component_type($component), join '::', @parts)
2444             if @search_extra and ( grep { lc $type eq $_ } @search_extra );
2445     }
2446 }
2447
2448 sub _get_component_type {
2449     my ( $instance ) = @_;
2450
2451     return 'controller' if $instance->isa('Catalyst::Controller');
2452     return 'model'      if $instance->isa('Catalyst::Model');
2453     return 'view'       if $instance->isa('Catalyst::View');
2454 }
2455
2456 =head2 $c->locate_components( $setup_component_config )
2457
2458 This method is meant to provide a list of component modules that should be
2459 setup for the application.  By default, it will use L<Module::Pluggable>.
2460
2461 Specify a C<setup_components> config option to pass additional options directly
2462 to L<Module::Pluggable>. To add additional search paths, specify a key named
2463 C<search_extra> as an array reference. Items in the array beginning with C<::>
2464 will have the application class name prepended to them.
2465
2466 =cut
2467
2468 sub locate_components {
2469     my $class  = shift;
2470     my $config = shift;
2471
2472     my @paths   = qw( ::Controller ::C ::Model ::M ::View ::V );
2473     my $extra   = delete $config->{ search_extra } || [];
2474
2475     push @paths, @$extra;
2476
2477     my $locator = Module::Pluggable::Object->new(
2478         search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
2479         %$config
2480     );
2481
2482     # XXX think about ditching this sort entirely
2483     my @comps = sort { length $a <=> length $b } $locator->plugins;
2484
2485     return @comps;
2486 }
2487
2488 =head2 $c->expand_component_module( $component, $setup_component_config )
2489
2490 Components found by C<locate_components> will be passed to this method, which
2491 is expected to return a list of component (package) names to be set up.
2492
2493 =cut
2494
2495 sub expand_component_module {
2496     my ($class, $module) = @_;
2497     return Devel::InnerPackage::list_packages( $module );
2498 }
2499
2500 =head2 $c->setup_component
2501
2502 =cut
2503
2504 ## FIXME - Why the hell do we try calling the ->COMPONENT method twice, this is madness!?!
2505 sub setup_component {
2506     my( $class, $component ) = @_;
2507
2508     unless ( $component->can( 'COMPONENT' ) ) {
2509         return $component;
2510     }
2511
2512     my $suffix = Catalyst::Utils::class2classsuffix( $component );
2513     my $config = $class->config->{ $suffix } || {};
2514     # Stash catalyst_component_name in the config here, so that custom COMPONENT
2515     # methods also pass it. local to avoid pointlessly shitting in config
2516     # for the debug screen, as $component is already the key name.
2517     local $config->{catalyst_component_name} = $component;
2518
2519     my $instance = eval { $component->COMPONENT( $class, $config ); };
2520
2521     if ( my $error = $@ ) {
2522         chomp $error;
2523         Catalyst::Exception->throw(
2524             message => qq/Couldn't instantiate component "$component", "$error"/
2525         );
2526     }
2527     elsif (!blessed $instance) {
2528         my $metaclass = Moose::Util::find_meta($component);
2529         my $method_meta = $metaclass->find_method_by_name('COMPONENT');
2530         my $component_method_from = $method_meta->associated_metaclass->name;
2531         my $value = defined($instance) ? $instance : 'undef';
2532         Catalyst::Exception->throw(
2533             message =>
2534             qq/Couldn't instantiate component "$component", COMPONENT() method (from $component_method_from) didn't return an object-like value (value was $value)./
2535         );
2536     }
2537
2538     return $instance;
2539 }
2540
2541 =head2 $c->setup_dispatcher
2542
2543 Sets up dispatcher.
2544
2545 =cut
2546
2547 sub setup_dispatcher {
2548     my ( $class, $dispatcher ) = @_;
2549
2550     if ($dispatcher) {
2551         $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
2552     }
2553
2554     if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
2555         $dispatcher = 'Catalyst::Dispatcher::' . $env;
2556     }
2557
2558     unless ($dispatcher) {
2559         $dispatcher = $class->dispatcher_class;
2560     }
2561
2562     Class::MOP::load_class($dispatcher);
2563
2564     # dispatcher instance
2565     $class->dispatcher( $dispatcher->new );
2566 }
2567
2568 =head2 $c->setup_engine
2569
2570 Sets up engine.
2571
2572 =cut
2573
2574 sub setup_engine {
2575     my ( $class, $engine ) = @_;
2576
2577     if ($engine) {
2578         $engine = 'Catalyst::Engine::' . $engine;
2579     }
2580
2581     if ( my $env = Catalyst::Utils::env_value( $class, 'ENGINE' ) ) {
2582         $engine = 'Catalyst::Engine::' . $env;
2583     }
2584
2585     if ( $ENV{MOD_PERL} ) {
2586         my $meta = Class::MOP::get_metaclass_by_name($class);
2587
2588         # create the apache method
2589         $meta->add_method('apache' => sub { shift->engine->apache });
2590
2591         my ( $software, $version ) =
2592           $ENV{MOD_PERL} =~ /^(\S+)\/(\d+(?:[\.\_]\d+)+)/;
2593
2594         $version =~ s/_//g;
2595         $version =~ s/(\.[^.]+)\./$1/g;
2596
2597         if ( $software eq 'mod_perl' ) {
2598
2599             if ( !$engine ) {
2600
2601                 if ( $version >= 1.99922 ) {
2602                     $engine = 'Catalyst::Engine::Apache2::MP20';
2603                 }
2604
2605                 elsif ( $version >= 1.9901 ) {
2606                     $engine = 'Catalyst::Engine::Apache2::MP19';
2607                 }
2608
2609                 elsif ( $version >= 1.24 ) {
2610                     $engine = 'Catalyst::Engine::Apache::MP13';
2611                 }
2612
2613                 else {
2614                     Catalyst::Exception->throw( message =>
2615                           qq/Unsupported mod_perl version: $ENV{MOD_PERL}/ );
2616                 }
2617
2618             }
2619
2620             # install the correct mod_perl handler
2621             if ( $version >= 1.9901 ) {
2622                 *handler = sub  : method {
2623                     shift->handle_request(@_);
2624                 };
2625             }
2626             else {
2627                 *handler = sub ($$) { shift->handle_request(@_) };
2628             }
2629
2630         }
2631
2632         elsif ( $software eq 'Zeus-Perl' ) {
2633             $engine = 'Catalyst::Engine::Zeus';
2634         }
2635
2636         else {
2637             Catalyst::Exception->throw(
2638                 message => qq/Unsupported mod_perl: $ENV{MOD_PERL}/ );
2639         }
2640     }
2641
2642     unless ($engine) {
2643         $engine = $class->engine_class;
2644     }
2645
2646     Class::MOP::load_class($engine);
2647
2648     # check for old engines that are no longer compatible
2649     my $old_engine;
2650     if ( $engine->isa('Catalyst::Engine::Apache')
2651         && !Catalyst::Engine::Apache->VERSION )
2652     {
2653         $old_engine = 1;
2654     }
2655
2656     elsif ( $engine->isa('Catalyst::Engine::Server::Base')
2657         && Catalyst::Engine::Server->VERSION le '0.02' )
2658     {
2659         $old_engine = 1;
2660     }
2661
2662     elsif ($engine->isa('Catalyst::Engine::HTTP::POE')
2663         && $engine->VERSION eq '0.01' )
2664     {
2665         $old_engine = 1;
2666     }
2667
2668     elsif ($engine->isa('Catalyst::Engine::Zeus')
2669         && $engine->VERSION eq '0.01' )
2670     {
2671         $old_engine = 1;
2672     }
2673
2674     if ($old_engine) {
2675         Catalyst::Exception->throw( message =>
2676               qq/Engine "$engine" is not supported by this version of Catalyst/
2677         );
2678     }
2679
2680     # engine instance
2681     $class->engine( $engine->new );
2682 }
2683
2684 =head2 $c->setup_home
2685
2686 Sets up the home directory.
2687
2688 =cut
2689
2690 sub setup_home {
2691     my ( $class, $home ) = @_;
2692
2693     if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
2694         $home = $env;
2695     }
2696
2697     $home ||= Catalyst::Utils::home($class);
2698
2699     if ($home) {
2700         #I remember recently being scolded for assigning config values like this
2701         $class->config->{home} ||= $home;
2702         $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
2703     }
2704 }
2705
2706 =head2 $c->setup_log
2707
2708 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
2709 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
2710 log to.
2711
2712 This method also installs a C<debug> method that returns a true value into the
2713 catalyst subclass if the "debug" level is passed in the comma-delimited list,
2714 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
2715
2716 Note that if the log has already been setup, by either a previous call to
2717 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
2718 that this method won't actually set up the log object.
2719
2720 =cut
2721
2722 sub setup_log {
2723     my ( $class, $levels ) = @_;
2724
2725     $levels ||= '';
2726     $levels =~ s/^\s+//;
2727     $levels =~ s/\s+$//;
2728     my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
2729
2730     my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
2731     if ( defined $env_debug ) {
2732         $levels{debug} = 1 if $env_debug; # Ugly!
2733         delete($levels{debug}) unless $env_debug;
2734     }
2735
2736     unless ( $class->log ) {
2737         $class->log( Catalyst::Log->new(keys %levels) );
2738     }
2739
2740     if ( $levels{debug} ) {
2741         Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
2742         $class->log->debug('Debug messages enabled');
2743     }
2744 }
2745
2746 =head2 $c->setup_plugins
2747
2748 Sets up plugins.
2749
2750 =cut
2751
2752 =head2 $c->setup_stats
2753
2754 Sets up timing statistics class.
2755
2756 =cut
2757
2758 sub setup_stats {
2759     my ( $class, $stats ) = @_;
2760
2761     Catalyst::Utils::ensure_class_loaded($class->stats_class);
2762
2763     my $env = Catalyst::Utils::env_value( $class, 'STATS' );
2764     if ( defined($env) ? $env : ($stats || $class->debug ) ) {
2765         Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
2766         $class->log->debug('Statistics enabled');
2767     }
2768 }
2769
2770
2771 =head2 $c->registered_plugins
2772
2773 Returns a sorted list of the plugins which have either been stated in the
2774 import list or which have been added via C<< MyApp->plugin(@args); >>.
2775
2776 If passed a given plugin name, it will report a boolean value indicating
2777 whether or not that plugin is loaded.  A fully qualified name is required if
2778 the plugin name does not begin with C<Catalyst::Plugin::>.
2779
2780  if ($c->registered_plugins('Some::Plugin')) {
2781      ...
2782  }
2783
2784 =cut
2785
2786 {
2787
2788     sub registered_plugins {
2789         my $proto = shift;
2790         return sort keys %{ $proto->_plugins } unless @_;
2791         my $plugin = shift;
2792         return 1 if exists $proto->_plugins->{$plugin};
2793         return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
2794     }
2795
2796     sub _register_plugin {
2797         my ( $proto, $plugin, $instant ) = @_;
2798         my $class = ref $proto || $proto;
2799
2800         Class::MOP::load_class( $plugin );
2801         $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
2802             if $plugin->isa( 'Catalyst::Component' );
2803         $proto->_plugins->{$plugin} = 1;
2804         unless ($instant) {
2805             my $meta = Class::MOP::get_metaclass_by_name($class);
2806             $meta->superclasses($plugin, $meta->superclasses);
2807         }
2808         return $class;
2809     }
2810
2811     sub setup_plugins {
2812         my ( $class, $plugins ) = @_;
2813
2814         $class->_plugins( {} ) unless $class->_plugins;
2815         $plugins = Data::OptList::mkopt($plugins || []);
2816
2817         my @plugins = map {
2818             [ Catalyst::Utils::resolve_namespace(
2819                   $class . '::Plugin',
2820                   'Catalyst::Plugin', $_->[0]
2821               ),
2822               $_->[1],
2823             ]
2824          } @{ $plugins };
2825
2826         for my $plugin ( reverse @plugins ) {
2827             Class::MOP::load_class($plugin->[0], $plugin->[1]);
2828             my $meta = find_meta($plugin->[0]);
2829             next if $meta && $meta->isa('Moose::Meta::Role');
2830
2831             $class->_register_plugin($plugin->[0]);
2832         }
2833
2834         my @roles =
2835             map  { $_->[0]->name, $_->[1] }
2836             grep { blessed($_->[0]) && $_->[0]->isa('Moose::Meta::Role') }
2837             map  { [find_meta($_->[0]), $_->[1]] }
2838             @plugins;
2839
2840         Moose::Util::apply_all_roles(
2841             $class => @roles
2842         ) if @roles;
2843     }
2844 }
2845
2846 =head2 $c->stack
2847
2848 Returns an arrayref of the internal execution stack (actions that are
2849 currently executing).
2850
2851 =head2 $c->stats
2852
2853 Returns the current timing statistics object. By default Catalyst uses
2854 L<Catalyst::Stats|Catalyst::Stats>, but can be set otherwise with
2855 L<< stats_class|/"$c->stats_class" >>.
2856
2857 Even if L<< -Stats|/"-Stats" >> is not enabled, the stats object is still
2858 available. By enabling it with C< $c->stats->enabled(1) >, it can be used to
2859 profile explicitly, although MyApp.pm still won't profile nor output anything
2860 by itself.
2861
2862 =head2 $c->stats_class
2863
2864 Returns or sets the stats (timing statistics) class. L<Catalyst::Stats|Catalyst::Stats> is used by default.
2865
2866 =head2 $c->use_stats
2867
2868 Returns 1 when L<< stats collection|/"-Stats" >> is enabled.
2869
2870 Note that this is a static method, not an accessor and should be overridden
2871 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
2872
2873 =cut
2874
2875 sub use_stats { 0 }
2876
2877
2878 =head2 $c->write( $data )
2879
2880 Writes $data to the output stream. When using this method directly, you
2881 will need to manually set the C<Content-Length> header to the length of
2882 your output data, if known.
2883
2884 =cut
2885
2886 sub write {
2887     my $c = shift;
2888
2889     # Finalize headers if someone manually writes output
2890     $c->finalize_headers;
2891
2892     return $c->engine->write( $c, @_ );
2893 }
2894
2895 =head2 version
2896
2897 Returns the Catalyst version number. Mostly useful for "powered by"
2898 messages in template systems.
2899
2900 =cut
2901
2902 sub version { return $Catalyst::VERSION }
2903
2904 =head1 CONFIGURATION
2905
2906 There are a number of 'base' config variables which can be set:
2907
2908 =over
2909
2910 =item *
2911
2912 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
2913
2914 =item *
2915
2916 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
2917
2918 =item *
2919
2920 C<home> - The application home directory. In an uninstalled application,
2921 this is the top level application directory. In an installed application,
2922 this will be the directory containing C<< MyApp.pm >>.
2923
2924 =item *
2925
2926 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
2927
2928 =item *
2929
2930 C<name> - The name of the application in debug messages and the debug and
2931 welcome screens
2932
2933 =item *
2934
2935 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
2936 until it is accessed. This allows you to (for example) check authentication (and reject
2937 the upload) before actually recieving all the data. See L</ON-DEMAND PARSER>
2938
2939 =item *
2940
2941 C<root> - The root directory for templates. Usually this is just a
2942 subdirectory of the home directory, but you can set it to change the
2943 templates to a different directory.
2944
2945 =item *
2946
2947 C<search_extra> - Array reference passed to Module::Pluggable to for additional
2948 namespaces from which components will be loaded (and constructed and stored in
2949 C<< $c->components >>).
2950
2951 =item *
2952
2953 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
2954 to be shown in hit debug tables in the test server.
2955
2956 =item *
2957
2958 C<use_request_uri_for_path> - Controlls if the C<REQUEST_URI> or C<PATH_INFO> environment
2959 variable should be used for determining the request path. See L<Catalyst::Engine::CGI/PATH DECODING>
2960 for more information.
2961
2962 =item *
2963
2964 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
2965
2966 =back
2967
2968 =head1 INTERNAL ACTIONS
2969
2970 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
2971 C<_ACTION>, and C<_END>. These are by default not shown in the private
2972 action table, but you can make them visible with a config parameter.
2973
2974     MyApp->config(show_internal_actions => 1);
2975
2976 =head1 ON-DEMAND PARSER
2977
2978 The request body is usually parsed at the beginning of a request,
2979 but if you want to handle input yourself, you can enable on-demand
2980 parsing with a config parameter.
2981
2982     MyApp->config(parse_on_demand => 1);
2983
2984 =head1 PROXY SUPPORT
2985
2986 Many production servers operate using the common double-server approach,
2987 with a lightweight frontend web server passing requests to a larger
2988 backend server. An application running on the backend server must deal
2989 with two problems: the remote user always appears to be C<127.0.0.1> and
2990 the server's hostname will appear to be C<localhost> regardless of the
2991 virtual host that the user connected through.
2992
2993 Catalyst will automatically detect this situation when you are running
2994 the frontend and backend servers on the same machine. The following
2995 changes are made to the request.
2996
2997     $c->req->address is set to the user's real IP address, as read from
2998     the HTTP X-Forwarded-For header.
2999
3000     The host value for $c->req->base and $c->req->uri is set to the real
3001     host, as read from the HTTP X-Forwarded-Host header.
3002
3003 Additionally, you may be running your backend application on an insecure
3004 connection (port 80) while your frontend proxy is running under SSL.  If there
3005 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
3006 tell Catalyst what port the frontend listens on.  This will allow all URIs to
3007 be created properly.
3008
3009 In the case of passing in:
3010
3011     X-Forwarded-Port: 443
3012
3013 All calls to C<uri_for> will result in an https link, as is expected.
3014
3015 Obviously, your web server must support these headers for this to work.
3016
3017 In a more complex server farm environment where you may have your
3018 frontend proxy server(s) on different machines, you will need to set a
3019 configuration option to tell Catalyst to read the proxied data from the
3020 headers.
3021
3022     MyApp->config(using_frontend_proxy => 1);
3023
3024 If you do not wish to use the proxy support at all, you may set:
3025
3026     MyApp->config(ignore_frontend_proxy => 1);
3027
3028 =head1 THREAD SAFETY
3029
3030 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
3031 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
3032 believe the Catalyst core to be thread-safe.
3033
3034 If you plan to operate in a threaded environment, remember that all other
3035 modules you are using must also be thread-safe. Some modules, most notably
3036 L<DBD::SQLite>, are not thread-safe.
3037
3038 =head1 SUPPORT
3039
3040 IRC:
3041
3042     Join #catalyst on irc.perl.org.
3043
3044 Mailing Lists:
3045
3046     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
3047     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
3048
3049 Web:
3050
3051     http://catalyst.perl.org
3052
3053 Wiki:
3054
3055     http://dev.catalyst.perl.org
3056
3057 =head1 SEE ALSO
3058
3059 =head2 L<Task::Catalyst> - All you need to start with Catalyst
3060
3061 =head2 L<Catalyst::Manual> - The Catalyst Manual
3062
3063 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
3064
3065 =head2 L<Catalyst::Engine> - Core engine
3066
3067 =head2 L<Catalyst::Log> - Log class.
3068
3069 =head2 L<Catalyst::Request> - Request object
3070
3071 =head2 L<Catalyst::Response> - Response object
3072
3073 =head2 L<Catalyst::Test> - The test suite.
3074
3075 =head1 PROJECT FOUNDER
3076
3077 sri: Sebastian Riedel <sri@cpan.org>
3078
3079 =head1 CONTRIBUTORS
3080
3081 abw: Andy Wardley
3082
3083 acme: Leon Brocard <leon@astray.com>
3084
3085 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
3086
3087 Andrew Bramble
3088
3089 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
3090
3091 Andrew Ruthven
3092
3093 André Walker
3094
3095 andyg: Andy Grundman <andy@hybridized.org>
3096
3097 audreyt: Audrey Tang
3098
3099 bricas: Brian Cassidy <bricas@cpan.org>
3100
3101 Caelum: Rafael Kitover <rkitover@io.com>
3102
3103 chansen: Christian Hansen
3104
3105 chicks: Christopher Hicks
3106
3107 Chisel Wright C<pause@herlpacker.co.uk>
3108
3109 Danijel Milicevic C<me@danijel.de>
3110
3111 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
3112
3113 David Naughton, C<naughton@umn.edu>
3114
3115 David E. Wheeler
3116
3117 dhoss: Devin Austin <dhoss@cpan.org>
3118
3119 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
3120
3121 Drew Taylor
3122
3123 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
3124
3125 esskar: Sascha Kiefer
3126
3127 fireartist: Carl Franks <cfranks@cpan.org>
3128
3129 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
3130
3131 gabb: Danijel Milicevic
3132
3133 Gary Ashton Jones
3134
3135 Gavin Henry C<ghenry@perl.me.uk>
3136
3137 Geoff Richards
3138
3139 groditi: Guillermo Roditi <groditi@gmail.com>
3140
3141 hobbs: Andrew Rodland <andrew@cleverdomain.org>
3142
3143 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
3144
3145 jcamacho: Juan Camacho
3146
3147 jester: Jesse Sheidlower C<jester@panix.com>
3148
3149 jhannah: Jay Hannah <jay@jays.net>
3150
3151 Jody Belka
3152
3153 Johan Lindstrom
3154
3155 jon: Jon Schutz <jjschutz@cpan.org>
3156
3157 Jonathan Rockway C<< <jrockway@cpan.org> >>
3158
3159 Kieren Diment C<kd@totaldatasolution.com>
3160
3161 konobi: Scott McWhirter <konobi@cpan.org>
3162
3163 marcus: Marcus Ramberg <mramberg@cpan.org>
3164
3165 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
3166
3167 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
3168
3169 mugwump: Sam Vilain
3170
3171 naughton: David Naughton
3172
3173 ningu: David Kamholz <dkamholz@cpan.org>
3174
3175 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
3176
3177 numa: Dan Sully <daniel@cpan.org>
3178
3179 obra: Jesse Vincent
3180
3181 Octavian Rasnita
3182
3183 omega: Andreas Marienborg
3184
3185 Oleg Kostyuk <cub.uanic@gmail.com>
3186
3187 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
3188
3189 rafl: Florian Ragwitz <rafl@debian.org>
3190
3191 random: Roland Lammel <lammel@cpan.org>
3192
3193 Robert Sedlacek C<< <rs@474.at> >>
3194
3195 SpiceMan: Marcel Montes
3196
3197 sky: Arthur Bergman
3198
3199 szbalint: Balint Szilakszi <szbalint@cpan.org>
3200
3201 t0m: Tomas Doran <bobtfish@bobtfish.net>
3202
3203 Ulf Edvinsson
3204
3205 Viljo Marrandi C<vilts@yahoo.com>
3206
3207 Will Hawes C<info@whawes.co.uk>
3208
3209 willert: Sebastian Willert <willert@cpan.org>
3210
3211 wreis: Wallace Reis <wallace@reis.org.br>
3212
3213 Yuval Kogman, C<nothingmuch@woobling.org>
3214
3215 rainboxx: Matthias Dietrich, C<perl@rainboxx.de>
3216
3217 dd070: Dhaval Dhanani <dhaval070@gmail.com>
3218
3219 =head1 COPYRIGHT
3220
3221 Copyright (c) 2005, the above named PROJECT FOUNDER and CONTRIBUTORS.
3222
3223 =head1 LICENSE
3224
3225 This library is free software. You can redistribute it and/or modify it under
3226 the same terms as Perl itself.
3227
3228 =cut
3229
3230 no Moose;
3231
3232 __PACKAGE__->meta->make_immutable;
3233
3234 1;