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