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 namespace::clean -except => 'meta';
   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 Module::Pluggable::Object ();
  20 use Text::SimpleTable ();
  21 use Path::Class::Dir ();
  22 use Path::Class::File ();
  23 use URI ();
  24 use URI::http;
  25 use URI::https;
  26 use HTML::Entities;
  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 String::RewritePrefix;
  33 use Catalyst::EngineLoader;
  34 use utf8;
  35 use Carp qw/croak carp shortmess/;
  36 use Try::Tiny;
  37 use Safe::Isa;
  38 use Moose::Util 'find_meta';
  39 use Plack::Middleware::Conditional;
  40 use Plack::Middleware::ReverseProxy;
  41 use Plack::Middleware::IIS6ScriptNameFix;
  42 use Plack::Middleware::IIS7KeepAliveFix;
  43 use Plack::Middleware::LighttpdScriptNameFix;
  44 use Plack::Middleware::ContentLength;
  45 use Plack::Middleware::Head;
  46 use Plack::Middleware::HTTPExceptions;
  47 use Plack::Middleware::FixMissingBodyInRedirect;
  48 use Plack::Middleware::MethodOverride;
  49 use Plack::Middleware::RemoveRedundantBody;
  50 use Catalyst::Middleware::Stash;
  51 use Plack::Util;
  52 use Class::Load 'load_class';
  53
  54 BEGIN { require 5.008003; }
  55
  56 has stack => (is => 'ro', default => sub { [] });
  57 has state => (is => 'rw', default => 0);
  58 has stats => (is => 'rw');
  59 has action => (is => 'rw');
  60 has counter => (is => 'rw', default => sub { {} });
  61 has request => (
  62     is => 'rw',
  63     default => sub {
  64         my $self = shift;
  65         $self->request_class->new($self->_build_request_constructor_args);
  66     },
  67     lazy => 1,
  68 );
  69 sub _build_request_constructor_args {
  70     my $self = shift;
  71     my %p = ( _log => $self->log );
  72     $p{_uploadtmp} = $self->_uploadtmp if $self->_has_uploadtmp;
  73     $p{data_handlers} = {$self->registered_data_handlers};
  74     $p{_use_hash_multivalue} = $self->config->{use_hash_multivalue_in_request}
  75       if $self->config->{use_hash_multivalue_in_request};
  76     \%p;
  77 }
  78
  79 has response => (
  80     is => 'rw',
  81     default => sub {
  82         my $self = shift;
  83         $self->response_class->new($self->_build_response_constructor_args);
  84     },
  85     lazy => 1,
  86 );
  87 sub _build_response_constructor_args {
  88     my $self = shift;
  89     { _log => $self->log };
  90 }
  91
  92 has namespace => (is => 'rw');
  93
  94 sub depth { scalar @{ shift->stack || [] }; }
  95 sub comp { shift->component(@_) }
  96
  97 sub req {
  98     my $self = shift; return $self->request(@_);
  99 }
 100 sub res {
 101     my $self = shift; return $self->response(@_);
 102 }
 103
 104 # For backwards compatibility
 105 sub finalize_output { shift->finalize_body(@_) };
 106
 107 # For statistics
 108 our $COUNT     = 1;
 109 our $START     = time;
 110 our $RECURSION = 1000;
 111 our $DETACH    = Catalyst::Exception::Detach->new;
 112 our $GO        = Catalyst::Exception::Go->new;
 113
 114 #I imagine that very few of these really need to be class variables. if any.
 115 #maybe we should just make them attributes with a default?
 116 __PACKAGE__->mk_classdata($_)
 117   for qw/components arguments dispatcher engine log dispatcher_class
 118   engine_loader context_class request_class response_class stats_class
 119   setup_finished _psgi_app loading_psgi_file run_options _psgi_middleware
 120   _data_handlers trace_level trace_logger/;
 121
 122 __PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
 123 __PACKAGE__->request_class('Catalyst::Request');
 124 __PACKAGE__->response_class('Catalyst::Response');
 125 __PACKAGE__->stats_class('Catalyst::Stats');
 126
 127 # Remember to update this in Catalyst::Runtime as well!
 128
 129 our $VERSION = '5.90069_002';
 130
 131 sub import {
 132     my ( $class, @arguments ) = @_;
 133
 134     # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
 135     # callers @ISA.
 136     return unless $class eq 'Catalyst';
 137
 138     my $caller = caller();
 139     return if $caller eq 'main';
 140
 141     my $meta = Moose::Meta::Class->initialize($caller);
 142     unless ( $caller->isa('Catalyst') ) {
 143         my @superclasses = ($meta->superclasses, $class, 'Catalyst::Controller');
 144         $meta->superclasses(@superclasses);
 145     }
 146     # Avoid possible C3 issues if 'Moose::Object' is already on RHS of MyApp
 147     $meta->superclasses(grep { $_ ne 'Moose::Object' } $meta->superclasses);
 148
 149     unless( $meta->has_method('meta') ){
 150         if ($Moose::VERSION >= 1.15) {
 151             $meta->_add_meta_method('meta');
 152         }
 153         else {
 154             $meta->add_method(meta => sub { Moose::Meta::Class->initialize("${caller}") } );
 155         }
 156     }
 157
 158     $caller->arguments( [@arguments] );
 159     $caller->setup_home;
 160 }
 161
 162 sub _application { $_[0] }
 163
 164 =encoding UTF-8
 165
 166 =head1 NAME
 167
 168 Catalyst - The Elegant MVC Web Application Framework
 169
 170 =head1 SYNOPSIS
 171
 172 See the L<Catalyst::Manual> distribution for comprehensive
 173 documentation and tutorials.
 174
 175     # Install Catalyst::Devel for helpers and other development tools
 176     # use the helper to create a new application
 177     catalyst.pl MyApp
 178
 179     # add models, views, controllers
 180     script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
 181     script/myapp_create.pl view MyTemplate TT
 182     script/myapp_create.pl controller Search
 183
 184     # built in testserver -- use -r to restart automatically on changes
 185     # --help to see all available options
 186     script/myapp_server.pl
 187
 188     # command line testing interface
 189     script/myapp_test.pl /yada
 190
 191     ### in lib/MyApp.pm
 192     use Catalyst qw/-Debug/; # include plugins here as well
 193
 194     ### In lib/MyApp/Controller/Root.pm (autocreated)
 195     sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
 196         my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
 197         $c->stash->{template} = 'foo.tt'; # set the template
 198         # lookup something from db -- stash vars are passed to TT
 199         $c->stash->{data} =
 200           $c->model('Database::Foo')->search( { country => $args[0] } );
 201         if ( $c->req->params->{bar} ) { # access GET or POST parameters
 202             $c->forward( 'bar' ); # process another action
 203             # do something else after forward returns
 204         }
 205     }
 206
 207     # The foo.tt TT template can use the stash data from the database
 208     [% WHILE (item = data.next) %]
 209         [% item.foo %]
 210     [% END %]
 211
 212     # called for /bar/of/soap, /bar/of/soap/10, etc.
 213     sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
 214
 215     # called after all actions are finished
 216     sub end : Action {
 217         my ( $self, $c ) = @_;
 218         if ( scalar @{ $c->error } ) { ... } # handle errors
 219         return if $c->res->body; # already have a response
 220         $c->forward( 'MyApp::View::TT' ); # render template
 221     }
 222
 223 See L<Catalyst::Manual::Intro> for additional information.
 224
 225 =head1 DESCRIPTION
 226
 227 Catalyst is a modern framework for making web applications without the
 228 pain usually associated with this process. This document is a reference
 229 to the main Catalyst application. If you are a new user, we suggest you
 230 start with L<Catalyst::Manual::Tutorial> or L<Catalyst::Manual::Intro>.
 231
 232 See L<Catalyst::Manual> for more documentation.
 233
 234 Catalyst plugins can be loaded by naming them as arguments to the "use
 235 Catalyst" statement. Omit the C<Catalyst::Plugin::> prefix from the
 236 plugin name, i.e., C<Catalyst::Plugin::My::Module> becomes
 237 C<My::Module>.
 238
 239     use Catalyst qw/My::Module/;
 240
 241 If your plugin starts with a name other than C<Catalyst::Plugin::>, you can
 242 fully qualify the name by using a unary plus:
 243
 244     use Catalyst qw/
 245         My::Module
 246         +Fully::Qualified::Plugin::Name
 247     /;
 248
 249 Special flags like C<-Debug> can also be specified as
 250 arguments when Catalyst is loaded:
 251
 252     use Catalyst qw/-Debug My::Module/;
 253
 254 The position of plugins and flags in the chain is important, because
 255 they are loaded in the order in which they appear.
 256
 257 The following flags are supported:
 258
 259 =head2 -Debug
 260
 261 Enables debug output. You can also force this setting from the system
 262 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
 263 settings override the application, with <MYAPP>_DEBUG having the highest
 264 priority.
 265
 266 This sets the log level to 'debug' and enables full debug output on the
 267 error screen. If you only want the latter, see L<< $c->debug >>.
 268
 269 =head2 -Home
 270
 271 Forces Catalyst to use a specific home directory, e.g.:
 272
 273     use Catalyst qw[-Home=/usr/mst];
 274
 275 This can also be done in the shell environment by setting either the
 276 C<CATALYST_HOME> environment variable or C<MYAPP_HOME>; where C<MYAPP>
 277 is replaced with the uppercased name of your application, any "::" in
 278 the name will be replaced with underscores, e.g. MyApp::Web should use
 279 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.
 280
 281 If none of these are set, Catalyst will attempt to automatically detect the
 282 home directory. If you are working in a development environment, Catalyst
 283 will try and find the directory containing either Makefile.PL, Build.PL,
 284 dist.ini, or cpanfile. If the application has been installed into the system
 285 (i.e. you have done C<make install>), then Catalyst will use the path to your
 286 application module, without the .pm extension (e.g., /foo/MyApp if your
 287 application was installed at /foo/MyApp.pm)
 288
 289 =head2 -Log
 290
 291     use Catalyst '-Log=warn,fatal,error';
 292
 293 Specifies a comma-delimited list of log levels.
 294
 295 =head2 -Stats
 296
 297 Enables statistics collection and reporting.
 298
 299    use Catalyst qw/-Stats=1/;
 300
 301 You can also force this setting from the system environment with CATALYST_STATS
 302 or <MYAPP>_STATS. The environment settings override the application, with
 303 <MYAPP>_STATS having the highest priority.
 304
 305 Stats are also enabled if L<< debugging |/"-Debug" >> is enabled.
 306
 307 =head1 METHODS
 308
 309 =head2 INFORMATION ABOUT THE CURRENT REQUEST
 310
 311 =head2 $c->action
 312
 313 Returns a L<Catalyst::Action> object for the current action, which
 314 stringifies to the action name. See L<Catalyst::Action>.
 315
 316 =head2 $c->namespace
 317
 318 Returns the namespace of the current action, i.e., the URI prefix
 319 corresponding to the controller of the current action. For example:
 320
 321     # in Controller::Foo::Bar
 322     $c->namespace; # returns 'foo/bar';
 323
 324 =head2 $c->request
 325
 326 =head2 $c->req
 327
 328 Returns the current L<Catalyst::Request> object, giving access to
 329 information about the current client request (including parameters,
 330 cookies, HTTP headers, etc.). See L<Catalyst::Request>.
 331
 332 =head2 REQUEST FLOW HANDLING
 333
 334 =head2 $c->forward( $action [, \@arguments ] )
 335
 336 =head2 $c->forward( $class, $method, [, \@arguments ] )
 337
 338 This is one way of calling another action (method) in the same or
 339 a different controller. You can also use C<< $self->my_method($c, @args) >>
 340 in the same controller or C<< $c->controller('MyController')->my_method($c, @args) >>
 341 in a different controller.
 342 The main difference is that 'forward' uses some of the Catalyst request
 343 cycle overhead, including debugging, which may be useful to you. On the
 344 other hand, there are some complications to using 'forward', restrictions
 345 on values returned from 'forward', and it may not handle errors as you prefer.
 346 Whether you use 'forward' or not is up to you; it is not considered superior to
 347 the other ways to call a method.
 348
 349 'forward' calls  another action, by its private name. If you give a
 350 class name but no method, C<process()> is called. You may also optionally
 351 pass arguments in an arrayref. The action will receive the arguments in
 352 C<@_> and C<< $c->req->args >>. Upon returning from the function,
 353 C<< $c->req->args >> will be restored to the previous values.
 354
 355 Any data C<return>ed from the action forwarded to, will be returned by the
 356 call to forward.
 357
 358     my $foodata = $c->forward('/foo');
 359     $c->forward('index');
 360     $c->forward(qw/Model::DBIC::Foo do_stuff/);
 361     $c->forward('View::TT');
 362
 363 Note that L<< forward|/"$c->forward( $action [, \@arguments ] )" >> implies
 364 an C<< eval { } >> around the call (actually
 365 L<< execute|/"$c->execute( $class, $coderef )" >> does), thus rendering all
 366 exceptions thrown by the called action non-fatal and pushing them onto
 367 $c->error instead. If you want C<die> to propagate you need to do something
 368 like:
 369
 370     $c->forward('foo');
 371     die join "\n", @{ $c->error } if @{ $c->error };
 372
 373 Or make sure to always return true values from your actions and write
 374 your code like this:
 375
 376     $c->forward('foo') || return;
 377
 378 Another note is that C<< $c->forward >> always returns a scalar because it
 379 actually returns $c->state which operates in a scalar context.
 380 Thus, something like:
 381
 382     return @array;
 383
 384 in an action that is forwarded to is going to return a scalar,
 385 i.e. how many items are in that array, which is probably not what you want.
 386 If you need to return an array then return a reference to it,
 387 or stash it like so:
 388
 389     $c->stash->{array} = \@array;
 390
 391 and access it from the stash.
 392
 393 Keep in mind that the C<end> method used is that of the caller action. So a C<$c-E<gt>detach> inside a forwarded action would run the C<end> method from the original action requested.
 394
 395 =cut
 396
 397 sub forward { my $c = shift; no warnings 'recursion'; $c->dispatcher->forward( $c, @_ ) }
 398
 399 =head2 $c->detach( $action [, \@arguments ] )
 400
 401 =head2 $c->detach( $class, $method, [, \@arguments ] )
 402
 403 =head2 $c->detach()
 404
 405 The same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, but
 406 doesn't return to the previous action when processing is finished.
 407
 408 When called with no arguments it escapes the processing chain entirely.
 409
 410 =cut
 411
 412 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
 413
 414 =head2 $c->visit( $action [, \@arguments ] )
 415
 416 =head2 $c->visit( $action [, \@captures, \@arguments ] )
 417
 418 =head2 $c->visit( $class, $method, [, \@arguments ] )
 419
 420 =head2 $c->visit( $class, $method, [, \@captures, \@arguments ] )
 421
 422 Almost the same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>,
 423 but does a full dispatch, instead of just calling the new C<$action> /
 424 C<< $class->$method >>. This means that C<begin>, C<auto> and the method
 425 you go to are called, just like a new request.
 426
 427 In addition both C<< $c->action >> and C<< $c->namespace >> are localized.
 428 This means, for example, that C<< $c->action >> methods such as
 429 L<name|Catalyst::Action/name>, L<class|Catalyst::Action/class> and
 430 L<reverse|Catalyst::Action/reverse> return information for the visited action
 431 when they are invoked within the visited action.  This is different from the
 432 behavior of L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, which
 433 continues to use the $c->action object from the caller action even when
 434 invoked from the called action.
 435
 436 C<< $c->stash >> is kept unchanged.
 437
 438 In effect, L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >>
 439 allows you to "wrap" another action, just as it would have been called by
 440 dispatching from a URL, while the analogous
 441 L<< go|/"$c->go( $action [, \@captures, \@arguments ] )" >> allows you to
 442 transfer control to another action as if it had been reached directly from a URL.
 443
 444 =cut
 445
 446 sub visit { my $c = shift; $c->dispatcher->visit( $c, @_ ) }
 447
 448 =head2 $c->go( $action [, \@arguments ] )
 449
 450 =head2 $c->go( $action [, \@captures, \@arguments ] )
 451
 452 =head2 $c->go( $class, $method, [, \@arguments ] )
 453
 454 =head2 $c->go( $class, $method, [, \@captures, \@arguments ] )
 455
 456 The relationship between C<go> and
 457 L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >> is the same as
 458 the relationship between
 459 L<< forward|/"$c->forward( $class, $method, [, \@arguments ] )" >> and
 460 L<< detach|/"$c->detach( $action [, \@arguments ] )" >>. Like C<< $c->visit >>,
 461 C<< $c->go >> will perform a full dispatch on the specified action or method,
 462 with localized C<< $c->action >> and C<< $c->namespace >>. Like C<detach>,
 463 C<go> escapes the processing of the current request chain on completion, and
 464 does not return to its caller.
 465
 466 @arguments are arguments to the final destination of $action. @captures are
 467 arguments to the intermediate steps, if any, on the way to the final sub of
 468 $action.
 469
 470 =cut
 471
 472 sub go { my $c = shift; $c->dispatcher->go( $c, @_ ) }
 473
 474 =head2 $c->response
 475
 476 =head2 $c->res
 477
 478 Returns the current L<Catalyst::Response> object, see there for details.
 479
 480 =head2 $c->stash
 481
 482 Returns a hashref to the stash, which may be used to store data and pass
 483 it between components during a request. You can also set hash keys by
 484 passing arguments. The stash is automatically sent to the view. The
 485 stash is cleared at the end of a request; it cannot be used for
 486 persistent storage (for this you must use a session; see
 487 L<Catalyst::Plugin::Session> for a complete system integrated with
 488 Catalyst).
 489
 490     $c->stash->{foo} = $bar;
 491     $c->stash( { moose => 'majestic', qux => 0 } );
 492     $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
 493
 494     # stash is automatically passed to the view for use in a template
 495     $c->forward( 'MyApp::View::TT' );
 496
 497 =cut
 498
 499 sub stash {
 500   my $c = shift;
 501   my $stash = Catalyst::Middleware::Stash->get($c->req->env);
 502   if(@_) {
 503     my $new_stash = @_ > 1 ? {@_} : $_[0];
 504     croak('stash takes a hash or hashref') unless ref $new_stash;
 505     foreach my $key ( keys %$new_stash ) {
 506       $stash->{$key} = $new_stash->{$key};
 507     }
 508   }
 509   return $stash;
 510 }
 511
 512 =head2 $c->error
 513
 514 =head2 $c->error($error, ...)
 515
 516 =head2 $c->error($arrayref)
 517
 518 Returns an arrayref containing error messages.  If Catalyst encounters an
 519 error while processing a request, it stores the error in $c->error.  This
 520 method should only be used to store fatal error messages.
 521
 522     my @error = @{ $c->error };
 523
 524 Add a new error.
 525
 526     $c->error('Something bad happened');
 527
 528 =cut
 529
 530 sub error {
 531     my $c = shift;
 532     if ( $_[0] ) {
 533         my $error = ref $_[0] eq 'ARRAY' ? $_[0] : [@_];
 534         croak @$error unless ref $c;
 535         push @{ $c->{error} }, @$error;
 536     }
 537     elsif ( defined $_[0] ) { $c->{error} = undef }
 538     return $c->{error} || [];
 539 }
 540
 541
 542 =head2 $c->state
 543
 544 Contains the return value of the last executed action.
 545 Note that << $c->state >> operates in a scalar context which means that all
 546 values it returns are scalar.
 547
 548 =head2 $c->clear_errors
 549
 550 Clear errors.  You probably don't want to clear the errors unless you are
 551 implementing a custom error screen.
 552
 553 This is equivalent to running
 554
 555     $c->error(0);
 556
 557 =cut
 558
 559 sub clear_errors {
 560     my $c = shift;
 561     $c->error(0);
 562 }
 563
 564 =head2 $c->has_errors
 565
 566 Returns true if you have errors
 567
 568 =cut
 569
 570 sub has_errors { scalar(@{shift->error}) ? 1:0 }
 571
 572 sub _comp_search_prefixes {
 573     my $c = shift;
 574     return map $c->components->{ $_ }, $c->_comp_names_search_prefixes(@_);
 575 }
 576
 577 # search components given a name and some prefixes
 578 sub _comp_names_search_prefixes {
 579     my ( $c, $name, @prefixes ) = @_;
 580     my $appclass = ref $c || $c;
 581     my $filter   = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
 582     $filter = qr/$filter/; # Compile regex now rather than once per loop
 583
 584     # map the original component name to the sub part that we will search against
 585     my %eligible = map { my $n = $_; $n =~ s{^$appclass\::[^:]+::}{}; $_ => $n; }
 586         grep { /$filter/ } keys %{ $c->components };
 587
 588     # undef for a name will return all
 589     return keys %eligible if !defined $name;
 590
 591     my $query  = $name->$_isa('Regexp') ? $name : qr/^$name$/i;
 592     my @result = grep { $eligible{$_} =~ m{$query} } keys %eligible;
 593
 594     return @result if @result;
 595
 596     # if we were given a regexp to search against, we're done.
 597     return if $name->$_isa('Regexp');
 598
 599     # skip regexp fallback if configured
 600     return
 601         if $appclass->config->{disable_component_resolution_regex_fallback};
 602
 603     # regexp fallback
 604     $query  = qr/$name/i;
 605     @result = grep { $eligible{ $_ } =~ m{$query} } keys %eligible;
 606
 607     # no results? try against full names
 608     if( !@result ) {
 609         @result = grep { m{$query} } keys %eligible;
 610     }
 611
 612     # don't warn if we didn't find any results, it just might not exist
 613     if( @result ) {
 614         # Disgusting hack to work out correct method name
 615         my $warn_for = lc $prefixes[0];
 616         my $msg = "Used regexp fallback for \$c->${warn_for}('${name}'), which found '" .
 617            (join '", "', @result) . "'. Relying on regexp fallback behavior for " .
 618            "component resolution is unreliable and unsafe.";
 619         my $short = $result[0];
 620         # remove the component namespace prefix
 621         $short =~ s/.*?(Model|Controller|View):://;
 622         my $shortmess = Carp::shortmess('');
 623         if ($shortmess =~ m#Catalyst/Plugin#) {
 624            $msg .= " You probably need to set '$short' instead of '${name}' in this " .
 625               "plugin's config";
 626         } elsif ($shortmess =~ m#Catalyst/lib/(View|Controller)#) {
 627            $msg .= " You probably need to set '$short' instead of '${name}' in this " .
 628               "component's config";
 629         } else {
 630            $msg .= " You probably meant \$c->${warn_for}('$short') instead of \$c->${warn_for}('${name}'), " .
 631               "but if you really wanted to search, pass in a regexp as the argument " .
 632               "like so: \$c->${warn_for}(qr/${name}/)";
 633         }
 634         $c->log->warn( "${msg}$shortmess" );
 635     }
 636
 637     return @result;
 638 }
 639
 640 # Find possible names for a prefix
 641 sub _comp_names {
 642     my ( $c, @prefixes ) = @_;
 643     my $appclass = ref $c || $c;
 644
 645     my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
 646
 647     my @names = map { s{$filter}{}; $_; }
 648         $c->_comp_names_search_prefixes( undef, @prefixes );
 649
 650     return @names;
 651 }
 652
 653 # Filter a component before returning by calling ACCEPT_CONTEXT if available
 654 sub _filter_component {
 655     my ( $c, $comp, @args ) = @_;
 656
 657     if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
 658         return $comp->ACCEPT_CONTEXT( $c, @args );
 659     }
 660
 661     return $comp;
 662 }
 663
 664 =head2 COMPONENT ACCESSORS
 665
 666 =head2 $c->controller($name)
 667
 668 Gets a L<Catalyst::Controller> instance by name.
 669
 670     $c->controller('Foo')->do_stuff;
 671
 672 If the name is omitted, will return the controller for the dispatched
 673 action.
 674
 675 If you want to search for controllers, pass in a regexp as the argument.
 676
 677     # find all controllers that start with Foo
 678     my @foo_controllers = $c->controller(qr{^Foo});
 679
 680
 681 =cut
 682
 683 sub controller {
 684     my ( $c, $name, @args ) = @_;
 685
 686     my $appclass = ref($c) || $c;
 687     if( $name ) {
 688         unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
 689             my $comps = $c->components;
 690             my $check = $appclass."::Controller::".$name;
 691             return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
 692         }
 693         my @result = $c->_comp_search_prefixes( $name, qw/Controller C/ );
 694         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 695         return $c->_filter_component( $result[ 0 ], @args );
 696     }
 697
 698     return $c->component( $c->action->class );
 699 }
 700
 701 =head2 $c->model($name)
 702
 703 Gets a L<Catalyst::Model> instance by name.
 704
 705     $c->model('Foo')->do_stuff;
 706
 707 Any extra arguments are directly passed to ACCEPT_CONTEXT.
 708
 709 If the name is omitted, it will look for
 710  - a model object in $c->stash->{current_model_instance}, then
 711  - a model name in $c->stash->{current_model}, then
 712  - a config setting 'default_model', or
 713  - check if there is only one model, and return it if that's the case.
 714
 715 If you want to search for models, pass in a regexp as the argument.
 716
 717     # find all models that start with Foo
 718     my @foo_models = $c->model(qr{^Foo});
 719
 720 =cut
 721
 722 sub model {
 723     my ( $c, $name, @args ) = @_;
 724     my $appclass = ref($c) || $c;
 725     if( $name ) {
 726         unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
 727             my $comps = $c->components;
 728             my $check = $appclass."::Model::".$name;
 729             return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
 730         }
 731         my @result = $c->_comp_search_prefixes( $name, qw/Model M/ );
 732         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 733         return $c->_filter_component( $result[ 0 ], @args );
 734     }
 735
 736     if (ref $c) {
 737         return $c->stash->{current_model_instance}
 738           if $c->stash->{current_model_instance};
 739         return $c->model( $c->stash->{current_model} )
 740           if $c->stash->{current_model};
 741     }
 742     return $c->model( $appclass->config->{default_model} )
 743       if $appclass->config->{default_model};
 744
 745     my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/Model M/);
 746
 747     if( $rest ) {
 748         $c->log->warn( Carp::shortmess('Calling $c->model() will return a random model unless you specify one of:') );
 749         $c->log->warn( '* $c->config(default_model => "the name of the default model to use")' );
 750         $c->log->warn( '* $c->stash->{current_model} # the name of the model to use for this request' );
 751         $c->log->warn( '* $c->stash->{current_model_instance} # the instance of the model to use for this request' );
 752         $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
 753     }
 754
 755     return $c->_filter_component( $comp );
 756 }
 757
 758
 759 =head2 $c->view($name)
 760
 761 Gets a L<Catalyst::View> instance by name.
 762
 763     $c->view('Foo')->do_stuff;
 764
 765 Any extra arguments are directly passed to ACCEPT_CONTEXT.
 766
 767 If the name is omitted, it will look for
 768  - a view object in $c->stash->{current_view_instance}, then
 769  - a view name in $c->stash->{current_view}, then
 770  - a config setting 'default_view', or
 771  - check if there is only one view, and return it if that's the case.
 772
 773 If you want to search for views, pass in a regexp as the argument.
 774
 775     # find all views that start with Foo
 776     my @foo_views = $c->view(qr{^Foo});
 777
 778 =cut
 779
 780 sub view {
 781     my ( $c, $name, @args ) = @_;
 782
 783     my $appclass = ref($c) || $c;
 784     if( $name ) {
 785         unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
 786             my $comps = $c->components;
 787             my $check = $appclass."::View::".$name;
 788             if( exists $comps->{$check} ) {
 789                 return $c->_filter_component( $comps->{$check}, @args );
 790             }
 791             else {
 792                 $c->log->warn( "Attempted to use view '$check', but does not exist" );
 793             }
 794         }
 795         my @result = $c->_comp_search_prefixes( $name, qw/View V/ );
 796         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 797         return $c->_filter_component( $result[ 0 ], @args );
 798     }
 799
 800     if (ref $c) {
 801         return $c->stash->{current_view_instance}
 802           if $c->stash->{current_view_instance};
 803         return $c->view( $c->stash->{current_view} )
 804           if $c->stash->{current_view};
 805     }
 806     return $c->view( $appclass->config->{default_view} )
 807       if $appclass->config->{default_view};
 808
 809     my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/View V/);
 810
 811     if( $rest ) {
 812         $c->log->warn( 'Calling $c->view() will return a random view unless you specify one of:' );
 813         $c->log->warn( '* $c->config(default_view => "the name of the default view to use")' );
 814         $c->log->warn( '* $c->stash->{current_view} # the name of the view to use for this request' );
 815         $c->log->warn( '* $c->stash->{current_view_instance} # the instance of the view to use for this request' );
 816         $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
 817     }
 818
 819     return $c->_filter_component( $comp );
 820 }
 821
 822 =head2 $c->controllers
 823
 824 Returns the available names which can be passed to $c->controller
 825
 826 =cut
 827
 828 sub controllers {
 829     my ( $c ) = @_;
 830     return $c->_comp_names(qw/Controller C/);
 831 }
 832
 833 =head2 $c->models
 834
 835 Returns the available names which can be passed to $c->model
 836
 837 =cut
 838
 839 sub models {
 840     my ( $c ) = @_;
 841     return $c->_comp_names(qw/Model M/);
 842 }
 843
 844
 845 =head2 $c->views
 846
 847 Returns the available names which can be passed to $c->view
 848
 849 =cut
 850
 851 sub views {
 852     my ( $c ) = @_;
 853     return $c->_comp_names(qw/View V/);
 854 }
 855
 856 =head2 $c->comp($name)
 857
 858 =head2 $c->component($name)
 859
 860 Gets a component object by name. This method is not recommended,
 861 unless you want to get a specific component by full
 862 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
 863 should be used instead.
 864
 865 If C<$name> is a regexp, a list of components matched against the full
 866 component name will be returned.
 867
 868 If Catalyst can't find a component by name, it will fallback to regex
 869 matching by default. To disable this behaviour set
 870 disable_component_resolution_regex_fallback to a true value.
 871
 872     __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
 873
 874 =cut
 875
 876 sub component {
 877     my ( $c, $name, @args ) = @_;
 878
 879     if( $name ) {
 880         my $comps = $c->components;
 881
 882         if( !ref $name ) {
 883             # is it the exact name?
 884             return $c->_filter_component( $comps->{ $name }, @args )
 885                        if exists $comps->{ $name };
 886
 887             # perhaps we just omitted "MyApp"?
 888             my $composed = ( ref $c || $c ) . "::${name}";
 889             return $c->_filter_component( $comps->{ $composed }, @args )
 890                        if exists $comps->{ $composed };
 891
 892             # search all of the models, views and controllers
 893             my( $comp ) = $c->_comp_search_prefixes( $name, qw/Model M Controller C View V/ );
 894             return $c->_filter_component( $comp, @args ) if $comp;
 895         }
 896
 897         return
 898             if $c->config->{disable_component_resolution_regex_fallback};
 899
 900         # This is here so $c->comp( '::M::' ) works
 901         my $query = ref $name ? $name : qr{$name}i;
 902
 903         my @result = grep { m{$query} } keys %{ $c->components };
 904         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 905
 906         if( $result[ 0 ] ) {
 907             $c->log->warn( Carp::shortmess(qq(Found results for "${name}" using regexp fallback)) );
 908             $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
 909             $c->log->warn( 'is unreliable and unsafe. You have been warned' );
 910             return $c->_filter_component( $result[ 0 ], @args );
 911         }
 912
 913         # I would expect to return an empty list here, but that breaks back-compat
 914     }
 915
 916     # fallback
 917     return sort keys %{ $c->components };
 918 }
 919
 920 =head2 CLASS DATA AND HELPER CLASSES
 921
 922 =head2 $c->config
 923
 924 Returns or takes a hashref containing the application's configuration.
 925
 926     __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
 927
 928 You can also use a C<YAML>, C<XML> or L<Config::General> config file
 929 like C<myapp.conf> in your applications home directory. See
 930 L<Catalyst::Plugin::ConfigLoader>.
 931
 932 =head3 Cascading configuration
 933
 934 The config method is present on all Catalyst components, and configuration
 935 will be merged when an application is started. Configuration loaded with
 936 L<Catalyst::Plugin::ConfigLoader> takes precedence over other configuration,
 937 followed by configuration in your top level C<MyApp> class. These two
 938 configurations are merged, and then configuration data whose hash key matches a
 939 component name is merged with configuration for that component.
 940
 941 The configuration for a component is then passed to the C<new> method when a
 942 component is constructed.
 943
 944 For example:
 945
 946     MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
 947     MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
 948
 949 will mean that C<MyApp::Model::Foo> receives the following data when
 950 constructed:
 951
 952     MyApp::Model::Foo->new({
 953         bar => 'baz',
 954         quux => 'frob',
 955         overrides => 'me',
 956     });
 957
 958 It's common practice to use a Moose attribute
 959 on the receiving component to access the config value.
 960
 961     package MyApp::Model::Foo;
 962
 963     use Moose;
 964
 965     # this attr will receive 'baz' at construction time
 966     has 'bar' => (
 967         is  => 'rw',
 968         isa => 'Str',
 969     );
 970
 971 You can then get the value 'baz' by calling $c->model('Foo')->bar
 972 (or $self->bar inside code in the model).
 973
 974 B<NOTE:> you MUST NOT call C<< $self->config >> or C<< __PACKAGE__->config >>
 975 as a way of reading config within your code, as this B<will not> give you the
 976 correctly merged config back. You B<MUST> take the config values supplied to
 977 the constructor and use those instead.
 978
 979 =cut
 980
 981 around config => sub {
 982     my $orig = shift;
 983     my $c = shift;
 984
 985     croak('Setting config after setup has been run is not allowed.')
 986         if ( @_ and $c->setup_finished );
 987
 988     $c->$orig(@_);
 989 };
 990
 991 =head2 $c->log
 992
 993 Returns the logging object instance. Unless it is already set, Catalyst
 994 sets this up with a L<Catalyst::Log> object. To use your own log class,
 995 set the logger with the C<< __PACKAGE__->log >> method prior to calling
 996 C<< __PACKAGE__->setup >>.
 997
 998  __PACKAGE__->log( MyLogger->new );
 999  __PACKAGE__->setup;
1000
1001 And later:
1002
1003     $c->log->info( 'Now logging with my own logger!' );
1004
1005 Your log class should implement the methods described in
1006 L<Catalyst::Log>.
1007
1008
1009 =head2 $c->debug
1010
1011 Returns 1 if debug mode is enabled, 0 otherwise.
1012
1013 You can enable debug mode in several ways:
1014
1015 =over
1016
1017 =item By calling myapp_server.pl with the -d flag
1018
1019 =item With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
1020
1021 =item The -Debug option in your MyApp.pm
1022
1023 =item By declaring C<sub debug { 1 }> in your MyApp.pm.
1024
1025 =back
1026
1027 The first three also set the log level to 'debug'.
1028
1029 Calling C<< $c->debug(1) >> has no effect.
1030
1031 =cut
1032
1033 sub debug { 0 }
1034
1035 =head2 $c->dispatcher
1036
1037 Returns the dispatcher instance. See L<Catalyst::Dispatcher>.
1038
1039 =head2 $c->engine
1040
1041 Returns the engine instance. See L<Catalyst::Engine>.
1042
1043
1044 =head2 UTILITY METHODS
1045
1046 =head2 $c->path_to(@path)
1047
1048 Merges C<@path> with C<< $c->config->{home} >> and returns a
1049 L<Path::Class::Dir> object. Note you can usually use this object as
1050 a filename, but sometimes you will have to explicitly stringify it
1051 yourself by calling the C<< ->stringify >> method.
1052
1053 For example:
1054
1055     $c->path_to( 'db', 'sqlite.db' );
1056
1057 =cut
1058
1059 sub path_to {
1060     my ( $c, @path ) = @_;
1061     my $path = Path::Class::Dir->new( $c->config->{home}, @path );
1062     if ( -d $path ) { return $path }
1063     else { return Path::Class::File->new( $c->config->{home}, @path ) }
1064 }
1065
1066 sub plugin {
1067     my ( $class, $name, $plugin, @args ) = @_;
1068
1069     # See block comment in t/unit_core_plugin.t
1070     $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in a future release/);
1071
1072     $class->_register_plugin( $plugin, 1 );
1073
1074     eval { $plugin->import };
1075     $class->mk_classdata($name);
1076     my $obj;
1077     eval { $obj = $plugin->new(@args) };
1078
1079     if ($@) {
1080         Catalyst::Exception->throw( message =>
1081               qq/Couldn't instantiate instant plugin "$plugin", "$@"/ );
1082     }
1083
1084     $class->$name($obj);
1085     $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
1086       if $class->debug;
1087 }
1088
1089 =head2 MyApp->setup
1090
1091 Initializes the dispatcher and engine, loads any plugins, and loads the
1092 model, view, and controller components. You may also specify an array
1093 of plugins to load here, if you choose to not load them in the C<use
1094 Catalyst> line.
1095
1096     MyApp->setup;
1097     MyApp->setup( qw/-Debug/ );
1098
1099 B<Note:> You B<should not> wrap this method with method modifiers
1100 or bad things will happen - wrap the C<setup_finalize> method instead.
1101
1102 =cut
1103
1104 sub setup {
1105     my ( $class, @arguments ) = @_;
1106     croak('Running setup more than once')
1107         if ( $class->setup_finished );
1108
1109     unless ( $class->isa('Catalyst') ) {
1110
1111         Catalyst::Exception->throw(
1112             message => qq/'$class' does not inherit from Catalyst/ );
1113     }
1114
1115     if ( $class->arguments ) {
1116         @arguments = ( @arguments, @{ $class->arguments } );
1117     }
1118
1119     # Process options
1120     my $flags = {};
1121
1122     foreach (@arguments) {
1123
1124         if (/^-Debug$/) {
1125             $flags->{log} =
1126               ( $flags->{log} ) ? 'debug,' . $flags->{log} : 'debug';
1127         }
1128         elsif (/^-(\w+)=?(.*)$/) {
1129             $flags->{ lc $1 } = $2;
1130         }
1131         else {
1132             push @{ $flags->{plugins} }, $_;
1133         }
1134     }
1135
1136     $class->setup_home( delete $flags->{home} );
1137
1138     $class->setup_log( delete $flags->{log} );
1139     $class->setup_plugins( delete $flags->{plugins} );
1140     $class->setup_trace();
1141
1142     $class->setup_data_handlers();
1143     $class->setup_dispatcher( delete $flags->{dispatcher} );
1144     if (my $engine = delete $flags->{engine}) {
1145         $class->log->warn("Specifying the engine in ->setup is no longer supported, see Catalyst::Upgrading");
1146     }
1147     $class->setup_engine();
1148     $class->setup_stats( delete $flags->{stats} );
1149
1150     for my $flag ( sort keys %{$flags} ) {
1151
1152         if ( my $code = $class->can( 'setup_' . $flag ) ) {
1153             &$code( $class, delete $flags->{$flag} );
1154         }
1155         else {
1156             $class->log->warn(qq/Unknown flag "$flag"/);
1157         }
1158     }
1159
1160     eval { require Catalyst::Devel; };
1161     if( !$@ && $ENV{CATALYST_SCRIPT_GEN} && ( $ENV{CATALYST_SCRIPT_GEN} < $Catalyst::Devel::CATALYST_SCRIPT_GEN ) ) {
1162         $class->log->warn(<<"EOF");
1163 You are running an old script!
1164
1165   Please update by running (this will overwrite existing files):
1166     catalyst.pl -force -scripts $class
1167
1168   or (this will not overwrite existing files):
1169     catalyst.pl -scripts $class
1170
1171 EOF
1172     }
1173
1174     # Call plugins setup, this is stupid and evil.
1175     # Also screws C3 badly on 5.10, hack to avoid.
1176     {
1177         no warnings qw/redefine/;
1178         local *setup = sub { };
1179         $class->setup unless $Catalyst::__AM_RESTARTING;
1180     }
1181
1182     $class->setup_middleware();
1183
1184     # Initialize our data structure
1185     $class->components( {} );
1186
1187     $class->setup_components;
1188
1189     if ( $class->debug ) {
1190         my @plugins = map { "$_  " . ( $_->VERSION || '' ) } $class->registered_plugins;
1191
1192         if (@plugins) {
1193             my $column_width = Catalyst::Utils::term_width() - 6;
1194             my $t = Text::SimpleTable->new($column_width);
1195             $t->row($_) for @plugins;
1196             $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
1197         }
1198
1199         my @middleware = map {
1200           ref $_ eq 'CODE' ?
1201             "Inline Coderef" :
1202               (ref($_) .'  '. ($_->can('VERSION') ? $_->VERSION || '' : '')
1203                 || '')  } $class->registered_middlewares;
1204
1205         if (@middleware) {
1206             my $column_width = Catalyst::Utils::term_width() - 6;
1207             my $t = Text::SimpleTable->new($column_width);
1208             $t->row($_) for @middleware;
1209             $class->log->debug( "Loaded PSGI Middleware:\n" . $t->draw . "\n" );
1210         }
1211
1212         my %dh = $class->registered_data_handlers;
1213         if (my @data_handlers = keys %dh) {
1214             my $column_width = Catalyst::Utils::term_width() - 6;
1215             my $t = Text::SimpleTable->new($column_width);
1216             $t->row($_) for @data_handlers;
1217             $class->log->debug( "Loaded Request Data Handlers:\n" . $t->draw . "\n" );
1218         }
1219
1220         my $dispatcher = $class->dispatcher;
1221         my $engine     = $class->engine;
1222         my $home       = $class->config->{home};
1223
1224         $class->log->debug(sprintf(q/Loaded dispatcher "%s"/, blessed($dispatcher)));
1225         $class->log->debug(sprintf(q/Loaded engine "%s"/, blessed($engine)));
1226
1227         $home
1228           ? ( -d $home )
1229           ? $class->log->debug(qq/Found home "$home"/)
1230           : $class->log->debug(qq/Home "$home" doesn't exist/)
1231           : $class->log->debug(q/Couldn't find home/);
1232
1233         my $column_width = Catalyst::Utils::term_width() - 8 - 9;
1234         my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] );
1235         for my $comp ( sort keys %{ $class->components } ) {
1236             my $type = ref $class->components->{$comp} ? 'instance' : 'class';
1237             $t->row( $comp, $type );
1238         }
1239         $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
1240           if ( keys %{ $class->components } );
1241     }
1242
1243     # Add our self to components, since we are also a component
1244     if( $class->isa('Catalyst::Controller') ){
1245       $class->components->{$class} = $class;
1246     }
1247
1248     $class->setup_actions;
1249
1250     if ( $class->debug ) {
1251         my $name = $class->config->{name} || 'Application';
1252         $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
1253     }
1254
1255     if ($class->config->{case_sensitive}) {
1256         $class->log->warn($class . "->config->{case_sensitive} is set.");
1257         $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
1258     }
1259
1260     $class->setup_finalize;
1261
1262     # Flush the log for good measure (in case something turned off 'autoflush' early)
1263     $class->log->_flush() if $class->log->can('_flush');
1264
1265     return $class || 1; # Just in case someone named their Application 0...
1266 }
1267
1268 =head2 $app->setup_finalize
1269
1270 A hook to attach modifiers to. This method does not do anything except set the
1271 C<setup_finished> accessor.
1272
1273 Applying method modifiers to the C<setup> method doesn't work, because of quirky things done for plugin setup.
1274
1275 Example:
1276
1277     after setup_finalize => sub {
1278         my $app = shift;
1279
1280         ## do stuff here..
1281     };
1282
1283 =cut
1284
1285 sub setup_finalize {
1286     my ($class) = @_;
1287     $class->setup_finished(1);
1288 }
1289
1290 =head2 $c->uri_for( $path?, @args?, \%query_values? )
1291
1292 =head2 $c->uri_for( $action, \@captures?, @args?, \%query_values? )
1293
1294 Constructs an absolute L<URI> object based on the application root, the
1295 provided path, and the additional arguments and query parameters provided.
1296 When used as a string, provides a textual URI.  If you need more flexibility
1297 than this (i.e. the option to provide relative URIs etc.) see
1298 L<Catalyst::Plugin::SmartURI>.
1299
1300 If no arguments are provided, the URI for the current action is returned.
1301 To return the current action and also provide @args, use
1302 C<< $c->uri_for( $c->action, @args ) >>.
1303
1304 If the first argument is a string, it is taken as a public URI path relative
1305 to C<< $c->namespace >> (if it doesn't begin with a forward slash) or
1306 relative to the application root (if it does). It is then merged with
1307 C<< $c->request->base >>; any C<@args> are appended as additional path
1308 components; and any C<%query_values> are appended as C<?foo=bar> parameters.
1309
1310 If the first argument is a L<Catalyst::Action> it represents an action which
1311 will have its path resolved using C<< $c->dispatcher->uri_for_action >>. The
1312 optional C<\@captures> argument (an arrayref) allows passing the captured
1313 variables that are needed to fill in the paths of Chained and Regex actions;
1314 once the path is resolved, C<uri_for> continues as though a path was
1315 provided, appending any arguments or parameters and creating an absolute
1316 URI.
1317
1318 The captures for the current request can be found in
1319 C<< $c->request->captures >>, and actions can be resolved using
1320 C<< Catalyst::Controller->action_for($name) >>. If you have a private action
1321 path, use C<< $c->uri_for_action >> instead.
1322
1323   # Equivalent to $c->req->uri
1324   $c->uri_for($c->action, $c->req->captures,
1325       @{ $c->req->args }, $c->req->params);
1326
1327   # For the Foo action in the Bar controller
1328   $c->uri_for($c->controller('Bar')->action_for('Foo'));
1329
1330   # Path to a static resource
1331   $c->uri_for('/static/images/logo.png');
1332
1333 =cut
1334
1335 sub uri_for {
1336     my ( $c, $path, @args ) = @_;
1337
1338     if ( $path->$_isa('Catalyst::Controller') ) {
1339         $path = $path->path_prefix;
1340         $path =~ s{/+\z}{};
1341         $path .= '/';
1342     }
1343
1344     undef($path) if (defined $path && $path eq '');
1345
1346     my $params =
1347       ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
1348
1349     carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
1350     foreach my $arg (@args) {
1351         utf8::encode($arg) if utf8::is_utf8($arg);
1352         $arg =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1353     }
1354
1355     if ( $path->$_isa('Catalyst::Action') ) { # action object
1356         s|/|%2F|g for @args;
1357         my $captures = [ map { s|/|%2F|g; $_; }
1358                         ( scalar @args && ref $args[0] eq 'ARRAY'
1359                          ? @{ shift(@args) }
1360                          : ()) ];
1361
1362         foreach my $capture (@$captures) {
1363             utf8::encode($capture) if utf8::is_utf8($capture);
1364             $capture =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1365         }
1366
1367         my $action = $path;
1368         # ->uri_for( $action, \@captures_and_args, \%query_values? )
1369         if( !@args && $action->number_of_args ) {
1370             my $expanded_action = $c->dispatcher->expand_action( $action );
1371
1372             my $num_captures = $expanded_action->number_of_captures;
1373             unshift @args, splice @$captures, $num_captures;
1374         }
1375
1376        $path = $c->dispatcher->uri_for_action($action, $captures);
1377         if (not defined $path) {
1378             $c->log->debug(qq/Can't find uri_for action '$action' @$captures/)
1379                 if $c->debug;
1380             return undef;
1381         }
1382         $path = '/' if $path eq '';
1383     }
1384
1385     unshift(@args, $path);
1386
1387     unless (defined $path && $path =~ s!^/!!) { # in-place strip
1388         my $namespace = $c->namespace;
1389         if (defined $path) { # cheesy hack to handle path '../foo'
1390            $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
1391         }
1392         unshift(@args, $namespace || '');
1393     }
1394
1395     # join args with '/', or a blank string
1396     my $args = join('/', grep { defined($_) } @args);
1397     $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
1398     $args =~ s!^/+!!;
1399
1400     my ($base, $class) = ('/', 'URI::_generic');
1401     if(blessed($c)) {
1402       $base = $c->req->base;
1403       $class = ref($base);
1404       $base =~ s{(?<!/)$}{/};
1405     }
1406
1407     my $query = '';
1408
1409     if (my @keys = keys %$params) {
1410       # somewhat lifted from URI::_query's query_form
1411       $query = '?'.join('&', map {
1412           my $val = $params->{$_};
1413           s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go;
1414           s/ /+/g;
1415           my $key = $_;
1416           $val = '' unless defined $val;
1417           (map {
1418               my $param = "$_";
1419               utf8::encode( $param ) if utf8::is_utf8($param);
1420               # using the URI::Escape pattern here so utf8 chars survive
1421               $param =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1422               $param =~ s/ /+/g;
1423               "${key}=$param"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
1424       } @keys);
1425     }
1426
1427     my $res = bless(\"${base}${args}${query}", $class);
1428     $res;
1429 }
1430
1431 =head2 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
1432
1433 =head2 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values? )
1434
1435 =over
1436
1437 =item $path
1438
1439 A private path to the Catalyst action you want to create a URI for.
1440
1441 This is a shortcut for calling C<< $c->dispatcher->get_action_by_path($path)
1442 >> and passing the resulting C<$action> and the remaining arguments to C<<
1443 $c->uri_for >>.
1444
1445 You can also pass in a Catalyst::Action object, in which case it is passed to
1446 C<< $c->uri_for >>.
1447
1448 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.
1449
1450 For example, if the action looks like:
1451
1452  package MyApp::Controller::Users;
1453
1454  sub lst : Path('the-list') {}
1455
1456 You can use:
1457
1458  $c->uri_for_action('/users/lst')
1459
1460 and it will create the URI /users/the-list.
1461
1462 =item \@captures_and_args?
1463
1464 Optional array reference of Captures (i.e. C<<CaptureArgs or $c->req->captures>)
1465 and arguments to the request. Usually used with L<Catalyst::DispatchType::Chained>
1466 to interpolate all the parameters in the URI.
1467
1468 =item @args?
1469
1470 Optional list of extra arguments - can be supplied in the
1471 C<< \@captures_and_args? >> array ref, or here - whichever is easier for your
1472 code.
1473
1474 Your action can have zero, a fixed or a variable number of args (e.g.
1475 C<< Args(1) >> for a fixed number or C<< Args() >> for a variable number)..
1476
1477 =item \%query_values?
1478
1479 Optional array reference of query parameters to append. E.g.
1480
1481   { foo => 'bar' }
1482
1483 will generate
1484
1485   /rest/of/your/uri?foo=bar
1486
1487 =back
1488
1489 =cut
1490
1491 sub uri_for_action {
1492     my ( $c, $path, @args ) = @_;
1493     my $action = blessed($path)
1494       ? $path
1495       : $c->dispatcher->get_action_by_path($path);
1496     unless (defined $action) {
1497       croak "Can't find action for path '$path'";
1498     }
1499     return $c->uri_for( $action, @args );
1500 }
1501
1502 =head2 $c->welcome_message
1503
1504 Returns the Catalyst welcome HTML page.
1505
1506 =cut
1507
1508 sub welcome_message {
1509     my $c      = shift;
1510     my $name   = $c->config->{name};
1511     my $logo   = $c->uri_for('/static/images/catalyst_logo.png');
1512     my $prefix = Catalyst::Utils::appprefix( ref $c );
1513     $c->response->content_type('text/html; charset=utf-8');
1514     return <<"EOF";
1515 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1516     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1517 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1518     <head>
1519     <meta http-equiv="Content-Language" content="en" />
1520     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1521         <title>$name on Catalyst $VERSION</title>
1522         <style type="text/css">
1523             body {
1524                 color: #000;
1525                 background-color: #eee;
1526             }
1527             div#content {
1528                 width: 640px;
1529                 margin-left: auto;
1530                 margin-right: auto;
1531                 margin-top: 10px;
1532                 margin-bottom: 10px;
1533                 text-align: left;
1534                 background-color: #ccc;
1535                 border: 1px solid #aaa;
1536             }
1537             p, h1, h2 {
1538                 margin-left: 20px;
1539                 margin-right: 20px;
1540                 font-family: verdana, tahoma, sans-serif;
1541             }
1542             a {
1543                 font-family: verdana, tahoma, sans-serif;
1544             }
1545             :link, :visited {
1546                     text-decoration: none;
1547                     color: #b00;
1548                     border-bottom: 1px dotted #bbb;
1549             }
1550             :link:hover, :visited:hover {
1551                     color: #555;
1552             }
1553             div#topbar {
1554                 margin: 0px;
1555             }
1556             pre {
1557                 margin: 10px;
1558                 padding: 8px;
1559             }
1560             div#answers {
1561                 padding: 8px;
1562                 margin: 10px;
1563                 background-color: #fff;
1564                 border: 1px solid #aaa;
1565             }
1566             h1 {
1567                 font-size: 0.9em;
1568                 font-weight: normal;
1569                 text-align: center;
1570             }
1571             h2 {
1572                 font-size: 1.0em;
1573             }
1574             p {
1575                 font-size: 0.9em;
1576             }
1577             p img {
1578                 float: right;
1579                 margin-left: 10px;
1580             }
1581             span#appname {
1582                 font-weight: bold;
1583                 font-size: 1.6em;
1584             }
1585         </style>
1586     </head>
1587     <body>
1588         <div id="content">
1589             <div id="topbar">
1590                 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1591                     $VERSION</h1>
1592              </div>
1593              <div id="answers">
1594                  <p>
1595                  <img src="$logo" alt="Catalyst Logo" />
1596                  </p>
1597                  <p>Welcome to the  world of Catalyst.
1598                     This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1599                     framework will make web development something you had
1600                     never expected it to be: Fun, rewarding, and quick.</p>
1601                  <h2>What to do now?</h2>
1602                  <p>That really depends  on what <b>you</b> want to do.
1603                     We do, however, provide you with a few starting points.</p>
1604                  <p>If you want to jump right into web development with Catalyst
1605                     you might want to start with a tutorial.</p>
1606 <pre>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Tutorial">Catalyst::Manual::Tutorial</a></code>
1607 </pre>
1608 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1609 <pre>
1610 <code>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Intro">Catalyst::Manual::Intro</a>
1611 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1612 </code></pre>
1613                  <h2>What to do next?</h2>
1614                  <p>Next it's time to write an actual application. Use the
1615                     helper scripts to generate <a href="https://metacpan.org/search?q=Catalyst%3A%3AController">controllers</a>,
1616                     <a href="https://metacpan.org/search?q=Catalyst%3A%3AModel">models</a>, and
1617                     <a href="https://metacpan.org/search?q=Catalyst%3A%3AView">views</a>;
1618                     they can save you a lot of work.</p>
1619                     <pre><code>script/${prefix}_create.pl --help</code></pre>
1620                     <p>Also, be sure to check out the vast and growing
1621                     collection of <a href="http://search.cpan.org/search?query=Catalyst">plugins for Catalyst on CPAN</a>;
1622                     you are likely to find what you need there.
1623                     </p>
1624
1625                  <h2>Need help?</h2>
1626                  <p>Catalyst has a very active community. Here are the main places to
1627                     get in touch with us.</p>
1628                  <ul>
1629                      <li>
1630                          <a href="http://dev.catalyst.perl.org">Wiki</a>
1631                      </li>
1632                      <li>
1633                          <a href="http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst">Mailing-List</a>
1634                      </li>
1635                      <li>
1636                          <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1637                      </li>
1638                  </ul>
1639                  <h2>In conclusion</h2>
1640                  <p>The Catalyst team hopes you will enjoy using Catalyst as much
1641                     as we enjoyed making it. Please contact us if you have ideas
1642                     for improvement or other feedback.</p>
1643              </div>
1644          </div>
1645     </body>
1646 </html>
1647 EOF
1648 }
1649
1650 =head2 run_options
1651
1652 Contains a hash of options passed from the application script, including
1653 the original ARGV the script received, the processed values from that
1654 ARGV and any extra arguments to the script which were not processed.
1655
1656 This can be used to add custom options to your application's scripts
1657 and setup your application differently depending on the values of these
1658 options.
1659
1660 =head1 INTERNAL METHODS
1661
1662 These methods are not meant to be used by end users.
1663
1664 =head2 $c->components
1665
1666 Returns a hash of components.
1667
1668 =head2 $c->context_class
1669
1670 Returns or sets the context class.
1671
1672 =head2 $c->counter
1673
1674 Returns a hashref containing coderefs and execution counts (needed for
1675 deep recursion detection).
1676
1677 =head2 $c->depth
1678
1679 Returns the number of actions on the current internal execution stack.
1680
1681 =head2 $c->dispatch
1682
1683 Dispatches a request to actions.
1684
1685 =cut
1686
1687 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
1688
1689 =head2 $c->dispatcher_class
1690
1691 Returns or sets the dispatcher class.
1692
1693 =head2 $c->dump_these
1694
1695 Returns a list of 2-element array references (name, structure) pairs
1696 that will be dumped on the error page in debug mode.
1697
1698 =cut
1699
1700 sub dump_these {
1701     my $c = shift;
1702     [ Request => $c->req ],
1703     [ Response => $c->res ],
1704     [ Stash => $c->stash ],
1705     [ Config => $c->config ];
1706 }
1707
1708 =head2 $c->engine_class
1709
1710 Returns or sets the engine class.
1711
1712 =head2 $c->execute( $class, $coderef )
1713
1714 Execute a coderef in given class and catch exceptions. Errors are available
1715 via $c->error.
1716
1717 =cut
1718
1719 sub execute {
1720     my ( $c, $class, $code ) = @_;
1721     $class = $c->component($class) || $class;
1722     $c->state(0);
1723
1724     if ( $c->depth >= $RECURSION ) {
1725         my $action = $code->reverse();
1726         $action = "/$action" unless $action =~ /->/;
1727         my $error = qq/Deep recursion detected calling "${action}"/;
1728         $c->log->error($error);
1729         $c->error($error);
1730         $c->state(0);
1731         return $c->state;
1732     }
1733
1734     my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
1735
1736     push( @{ $c->stack }, $code );
1737
1738     no warnings 'recursion';
1739     # N.B. This used to be combined, but I have seen $c get clobbered if so, and
1740     #      I have no idea how, ergo $ret (which appears to fix the issue)
1741     eval { my $ret = $code->execute( $class, $c, @{ $c->req->args } ) || 0; $c->state( $ret ) };
1742
1743     $c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
1744
1745     my $last = pop( @{ $c->stack } );
1746
1747     if ( my $error = $@ ) {
1748         #rethow if this can be handled by middleware
1749         if(blessed $error && ($error->can('as_psgi') || $error->can('code'))) {
1750             foreach my $err (@{$c->error}) {
1751                 $c->log->error($err);
1752             }
1753             $c->clear_errors;
1754             $c->log->_flush if $c->log->can('_flush');
1755
1756             $error->can('rethrow') ? $error->rethrow : croak $error;
1757         }
1758         if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) {
1759             $error->rethrow if $c->depth > 1;
1760         }
1761         elsif ( blessed($error) and $error->isa('Catalyst::Exception::Go') ) {
1762             $error->rethrow if $c->depth > 0;
1763         }
1764         else {
1765             unless ( ref $error ) {
1766                 no warnings 'uninitialized';
1767                 chomp $error;
1768                 my $class = $last->class;
1769                 my $name  = $last->name;
1770                 $error = qq/Caught exception in $class->$name "$error"/;
1771             }
1772             $c->error($error);
1773         }
1774         $c->state(0);
1775     }
1776     return $c->state;
1777 }
1778
1779 sub _stats_start_execute {
1780     my ( $c, $code ) = @_;
1781     my $appclass = ref($c) || $c;
1782     return if ( ( $code->name =~ /^_.*/ )
1783         && ( !$appclass->config->{show_internal_actions} ) );
1784
1785     my $action_name = $code->reverse();
1786     $c->counter->{$action_name}++;
1787
1788     my $action = $action_name;
1789     $action = "/$action" unless $action =~ /->/;
1790
1791     # determine if the call was the result of a forward
1792     # this is done by walking up the call stack and looking for a calling
1793     # sub of Catalyst::forward before the eval
1794     my $callsub = q{};
1795     for my $index ( 2 .. 11 ) {
1796         last
1797         if ( ( caller($index) )[0] eq 'Catalyst'
1798             && ( caller($index) )[3] eq '(eval)' );
1799
1800         if ( ( caller($index) )[3] =~ /forward$/ ) {
1801             $callsub = ( caller($index) )[3];
1802             $action  = "-> $action";
1803             last;
1804         }
1805     }
1806
1807     my $uid = $action_name . $c->counter->{$action_name};
1808
1809     # is this a root-level call or a forwarded call?
1810     if ( $callsub =~ /forward$/ ) {
1811         my $parent = $c->stack->[-1];
1812
1813         # forward, locate the caller
1814         if ( defined $parent && exists $c->counter->{"$parent"} ) {
1815             $c->stats->profile(
1816                 begin  => $action,
1817                 parent => "$parent" . $c->counter->{"$parent"},
1818                 uid    => $uid,
1819             );
1820         }
1821         else {
1822
1823             # forward with no caller may come from a plugin
1824             $c->stats->profile(
1825                 begin => $action,
1826                 uid   => $uid,
1827             );
1828         }
1829     }
1830     else {
1831
1832         # root-level call
1833         $c->stats->profile(
1834             begin => $action,
1835             uid   => $uid,
1836         );
1837     }
1838     return $action;
1839
1840 }
1841
1842 sub _stats_finish_execute {
1843     my ( $c, $info ) = @_;
1844     $c->stats->profile( end => $info );
1845 }
1846
1847 =head2 $c->finalize
1848
1849 Finalizes the request.
1850
1851 =cut
1852
1853 sub finalize {
1854     my $c = shift;
1855
1856     for my $error ( @{ $c->error } ) {
1857         $c->log->error($error);
1858     }
1859
1860     # Support skipping finalize for psgix.io style 'jailbreak'.  Used to support
1861     # stuff like cometd and websockets
1862
1863     if($c->request->_has_io_fh) {
1864       $c->log_response;
1865       return;
1866     }
1867
1868     # Allow engine to handle finalize flow (for POE)
1869     my $engine = $c->engine;
1870     if ( my $code = $engine->can('finalize') ) {
1871         $engine->$code($c);
1872     }
1873     else {
1874
1875         $c->finalize_uploads;
1876
1877         # Error
1878         if ( $#{ $c->error } >= 0 ) {
1879             $c->finalize_error;
1880         }
1881
1882         $c->finalize_headers unless $c->response->finalized_headers;
1883
1884         $c->finalize_body;
1885     }
1886
1887     $c->log_response;
1888
1889     if ($c->use_stats) {
1890         my $elapsed = $c->stats->elapsed;
1891         my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
1892         $c->log->info(
1893             "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
1894     }
1895
1896     return $c->response->status;
1897 }
1898
1899 =head2 $c->finalize_body
1900
1901 Finalizes body.
1902
1903 =cut
1904
1905 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
1906
1907 =head2 $c->finalize_cookies
1908
1909 Finalizes cookies.
1910
1911 =cut
1912
1913 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
1914
1915 =head2 $c->finalize_error
1916
1917 Finalizes error.  If there is only one error in L</error> and it is an object that
1918 does C<as_psgi> or C<code> we rethrow the error and presume it caught by middleware
1919 up the ladder.  Otherwise we return the debugging error page (in debug mode) or we
1920 return the default error page (production mode).
1921
1922 =cut
1923
1924 sub finalize_error {
1925     my $c = shift;
1926     if($#{$c->error} > 0) {
1927         $c->engine->finalize_error( $c, @_ );
1928     } else {
1929         my ($error) = @{$c->error};
1930         if(
1931           blessed $error &&
1932           ($error->can('as_psgi') || $error->can('code'))
1933         ) {
1934             # In the case where the error 'knows what it wants', becauses its PSGI
1935             # aware, just rethow and let middleware catch it
1936             $error->can('rethrow') ? $error->rethrow : croak $error;
1937         } else {
1938             $c->engine->finalize_error( $c, @_ )
1939         }
1940     }
1941 }
1942
1943 =head2 $c->finalize_headers
1944
1945 Finalizes headers.
1946
1947 =cut
1948
1949 sub finalize_headers {
1950     my $c = shift;
1951
1952     my $response = $c->response; #accessor calls can add up?
1953
1954     # Check if we already finalized headers
1955     return if $response->finalized_headers;
1956
1957     # Handle redirects
1958     if ( my $location = $response->redirect ) {
1959         $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
1960         $response->header( Location => $location );
1961     }
1962
1963     # Remove incorrectly added body and content related meta data when returning
1964     # an information response, or a response the is required to not include a body
1965
1966     $c->finalize_cookies;
1967
1968     $c->response->finalize_headers();
1969
1970     # Done
1971     $response->finalized_headers(1);
1972 }
1973
1974 =head2 $c->finalize_output
1975
1976 An alias for finalize_body.
1977
1978 =head2 $c->finalize_read
1979
1980 Finalizes the input after reading is complete.
1981
1982 =cut
1983
1984 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
1985
1986 =head2 $c->finalize_uploads
1987
1988 Finalizes uploads. Cleans up any temporary files.
1989
1990 =cut
1991
1992 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
1993
1994 =head2 $c->get_action( $action, $namespace )
1995
1996 Gets an action in a given namespace.
1997
1998 =cut
1999
2000 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
2001
2002 =head2 $c->get_actions( $action, $namespace )
2003
2004 Gets all actions of a given name in a namespace and all parent
2005 namespaces.
2006
2007 =cut
2008
2009 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
2010
2011 =head2 $app->handle_request( @arguments )
2012
2013 Called to handle each HTTP request.
2014
2015 =cut
2016
2017 sub handle_request {
2018     my ( $class, @arguments ) = @_;
2019
2020     # Always expect worst case!
2021     my $status = -1;
2022     try {
2023         if ($class->debug) {
2024             my $secs = time - $START || 1;
2025             my $av = sprintf '%.3f', $COUNT / $secs;
2026             my $time = localtime time;
2027             $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
2028         }
2029
2030         my $c = $class->prepare(@arguments);
2031         $c->dispatch;
2032         $status = $c->finalize;
2033     } catch {
2034         #rethow if this can be handled by middleware
2035         if(blessed $_ && ($_->can('as_psgi') || $_->can('code'))) {
2036             $_->can('rethrow') ? $_->rethrow : croak $_;
2037         }
2038         chomp(my $error = $_);
2039         $class->log->error(qq/Caught exception in engine "$error"/);
2040     };
2041
2042     $COUNT++;
2043
2044     if(my $coderef = $class->log->can('_flush')){
2045         $class->log->$coderef();
2046     }
2047     return $status;
2048 }
2049
2050 =head2 $class->prepare( @arguments )
2051
2052 Creates a Catalyst context from an engine-specific request (Apache, CGI,
2053 etc.).
2054
2055 =cut
2056
2057 has _uploadtmp => (
2058     is => 'ro',
2059     predicate => '_has_uploadtmp',
2060 );
2061
2062 sub prepare {
2063     my ( $class, @arguments ) = @_;
2064
2065     # XXX
2066     # After the app/ctxt split, this should become an attribute based on something passed
2067     # into the application.
2068     $class->context_class( ref $class || $class ) unless $class->context_class;
2069
2070     my $uploadtmp = $class->config->{uploadtmp};
2071     my $c = $class->context_class->new({ $uploadtmp ? (_uploadtmp => $uploadtmp) : ()});
2072
2073     $c->response->_context($c);
2074
2075     #surely this is not the most efficient way to do things...
2076     $c->stats($class->stats_class->new)->enable($c->use_stats);
2077     if ( $c->debug || $c->config->{enable_catalyst_header} ) {
2078         $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
2079     }
2080
2081     try {
2082         # Allow engine to direct the prepare flow (for POE)
2083         if ( my $prepare = $c->engine->can('prepare') ) {
2084             $c->engine->$prepare( $c, @arguments );
2085         }
2086         else {
2087             $c->prepare_request(@arguments);
2088             $c->prepare_connection;
2089             $c->prepare_query_parameters;
2090             $c->prepare_headers; # Just hooks, no longer needed - they just
2091             $c->prepare_cookies; # cause the lazy attribute on req to build
2092             $c->prepare_path;
2093
2094             # Prepare the body for reading, either by prepare_body
2095             # or the user, if they are using $c->read
2096             $c->prepare_read;
2097
2098             # Parse the body unless the user wants it on-demand
2099             unless ( ref($c)->config->{parse_on_demand} ) {
2100                 $c->prepare_body;
2101             }
2102         }
2103         $c->prepare_action;
2104     }
2105     # VERY ugly and probably shouldn't rely on ->finalize actually working
2106     catch {
2107         # failed prepare is always due to an invalid request, right?
2108         $c->response->status(400);
2109         $c->response->content_type('text/plain');
2110         $c->response->body('Bad Request');
2111         # Note we call finalize and then die here, which escapes
2112         # finalize being called in the enclosing block..
2113         # It in fact couldn't be called, as we don't return $c..
2114         # This is a mess - but I'm unsure you can fix this without
2115         # breaking compat for people doing crazy things (we should set
2116         # the 400 and just return the ctx here IMO, letting finalize get called
2117         # above...
2118         $c->finalize;
2119         die $_;
2120     };
2121
2122     $c->log_request;
2123
2124     return $c;
2125 }
2126
2127 =head2 $c->prepare_action
2128
2129 Prepares action. See L<Catalyst::Dispatcher>.
2130
2131 =cut
2132
2133 sub prepare_action { my $c = shift; $c->dispatcher->prepare_action( $c, @_ ) }
2134
2135 =head2 $c->prepare_body
2136
2137 Prepares message body.
2138
2139 =cut
2140
2141 sub prepare_body {
2142     my $c = shift;
2143
2144     return if $c->request->_has_body;
2145
2146     # Initialize on-demand data
2147     $c->engine->prepare_body( $c, @_ );
2148     $c->prepare_parameters;
2149     $c->prepare_uploads;
2150 }
2151
2152 =head2 $c->prepare_body_chunk( $chunk )
2153
2154 Prepares a chunk of data before sending it to L<HTTP::Body>.
2155
2156 See L<Catalyst::Engine>.
2157
2158 =cut
2159
2160 sub prepare_body_chunk {
2161     my $c = shift;
2162     $c->engine->prepare_body_chunk( $c, @_ );
2163 }
2164
2165 =head2 $c->prepare_body_parameters
2166
2167 Prepares body parameters.
2168
2169 =cut
2170
2171 sub prepare_body_parameters {
2172     my $c = shift;
2173     $c->engine->prepare_body_parameters( $c, @_ );
2174 }
2175
2176 =head2 $c->prepare_connection
2177
2178 Prepares connection.
2179
2180 =cut
2181
2182 sub prepare_connection {
2183     my $c = shift;
2184     # XXX - This is called on the engine (not the request) to maintain
2185     #       Engine::PSGI back compat.
2186     $c->engine->prepare_connection($c);
2187 }
2188
2189 =head2 $c->prepare_cookies
2190
2191 Prepares cookies by ensuring that the attribute on the request
2192 object has been built.
2193
2194 =cut
2195
2196 sub prepare_cookies { my $c = shift; $c->request->cookies }
2197
2198 =head2 $c->prepare_headers
2199
2200 Prepares request headers by ensuring that the attribute on the request
2201 object has been built.
2202
2203 =cut
2204
2205 sub prepare_headers { my $c = shift; $c->request->headers }
2206
2207 =head2 $c->prepare_parameters
2208
2209 Prepares parameters.
2210
2211 =cut
2212
2213 sub prepare_parameters {
2214     my $c = shift;
2215     $c->prepare_body_parameters;
2216     $c->engine->prepare_parameters( $c, @_ );
2217 }
2218
2219 =head2 $c->prepare_path
2220
2221 Prepares path and base.
2222
2223 =cut
2224
2225 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2226
2227 =head2 $c->prepare_query_parameters
2228
2229 Prepares query parameters.
2230
2231 =cut
2232
2233 sub prepare_query_parameters {
2234     my $c = shift;
2235
2236     $c->engine->prepare_query_parameters( $c, @_ );
2237 }
2238
2239 =head2 $c->log_request
2240
2241 Writes information about the request to the debug logs.  This includes:
2242
2243 =over 4
2244
2245 =item * Request method, path, and remote IP address
2246
2247 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2248
2249 =item * Request parameters
2250
2251 =item * File uploads
2252
2253 =back
2254
2255 =cut
2256
2257 sub log_request {
2258     my $c = shift;
2259
2260     return unless $c->debug;
2261
2262     my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2263     my $request = $dump->[1];
2264
2265     my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2266     $method ||= '';
2267     $path = '/' unless length $path;
2268     $address ||= '';
2269     $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2270
2271     $c->log_request_headers($request->headers);
2272
2273     if ( my $keywords = $request->query_keywords ) {
2274         $c->log->debug("Query keywords are: $keywords");
2275     }
2276
2277     $c->log_request_parameters( query => $request->query_parameters, $request->_has_body ? (body => $request->body_parameters) : () );
2278
2279     $c->log_request_uploads($request);
2280 }
2281
2282 =head2 $c->log_response
2283
2284 Writes information about the response to the debug logs by calling
2285 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2286
2287 =cut
2288
2289 sub log_response {
2290     my $c = shift;
2291
2292     return unless $c->debug;
2293
2294     my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2295     my $response = $dump->[1];
2296
2297     $c->log_response_status_line($response);
2298     $c->log_response_headers($response->headers);
2299 }
2300
2301 =head2 $c->log_response_status_line($response)
2302
2303 Writes one line of information about the response to the debug logs.  This includes:
2304
2305 =over 4
2306
2307 =item * Response status code
2308
2309 =item * Content-Type header (if present)
2310
2311 =item * Content-Length header (if present)
2312
2313 =back
2314
2315 =cut
2316
2317 sub log_response_status_line {
2318     my ($c, $response) = @_;
2319
2320     $c->log->debug(
2321         sprintf(
2322             'Response Code: %s; Content-Type: %s; Content-Length: %s',
2323             $response->status                            || 'unknown',
2324             $response->headers->header('Content-Type')   || 'unknown',
2325             $response->headers->header('Content-Length') || 'unknown'
2326         )
2327     );
2328 }
2329
2330 =head2 $c->log_response_headers($headers);
2331
2332 Hook method which can be wrapped by plugins to log the response headers.
2333 No-op in the default implementation.
2334
2335 =cut
2336
2337 sub log_response_headers {}
2338
2339 =head2 $c->log_request_parameters( query => {}, body => {} )
2340
2341 Logs request parameters to debug logs
2342
2343 =cut
2344
2345 sub log_request_parameters {
2346     my $c          = shift;
2347     my %all_params = @_;
2348
2349     return unless $c->debug;
2350
2351     my $column_width = Catalyst::Utils::term_width() - 44;
2352     foreach my $type (qw(query body)) {
2353         my $params = $all_params{$type};
2354         next if ! keys %$params;
2355         my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2356         for my $key ( sort keys %$params ) {
2357             my $param = $params->{$key};
2358             my $value = defined($param) ? $param : '';
2359             $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2360         }
2361         $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2362     }
2363 }
2364
2365 =head2 $c->log_request_uploads
2366
2367 Logs file uploads included in the request to the debug logs.
2368 The parameter name, filename, file type, and file size are all included in
2369 the debug logs.
2370
2371 =cut
2372
2373 sub log_request_uploads {
2374     my $c = shift;
2375     my $request = shift;
2376     return unless $c->debug;
2377     my $uploads = $request->uploads;
2378     if ( keys %$uploads ) {
2379         my $t = Text::SimpleTable->new(
2380             [ 12, 'Parameter' ],
2381             [ 26, 'Filename' ],
2382             [ 18, 'Type' ],
2383             [ 9,  'Size' ]
2384         );
2385         for my $key ( sort keys %$uploads ) {
2386             my $upload = $uploads->{$key};
2387             for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2388                 $t->row( $key, $u->filename, $u->type, $u->size );
2389             }
2390         }
2391         $c->log->debug( "File Uploads are:\n" . $t->draw );
2392     }
2393 }
2394
2395 =head2 $c->log_request_headers($headers);
2396
2397 Hook method which can be wrapped by plugins to log the request headers.
2398 No-op in the default implementation.
2399
2400 =cut
2401
2402 sub log_request_headers {}
2403
2404 =head2 $c->log_headers($type => $headers)
2405
2406 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2407
2408 =cut
2409
2410 sub log_headers {
2411     my $c       = shift;
2412     my $type    = shift;
2413     my $headers = shift;    # an HTTP::Headers instance
2414
2415     return unless $c->debug;
2416
2417     my $column_width = Catalyst::Utils::term_width() - 28;
2418     my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2419     $headers->scan(
2420         sub {
2421             my ( $name, $value ) = @_;
2422             $t->row( $name, $value );
2423         }
2424     );
2425     $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2426 }
2427
2428
2429 =head2 $c->prepare_read
2430
2431 Prepares the input for reading.
2432
2433 =cut
2434
2435 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2436
2437 =head2 $c->prepare_request
2438
2439 Prepares the engine request.
2440
2441 =cut
2442
2443 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2444
2445 =head2 $c->prepare_uploads
2446
2447 Prepares uploads.
2448
2449 =cut
2450
2451 sub prepare_uploads {
2452     my $c = shift;
2453
2454     $c->engine->prepare_uploads( $c, @_ );
2455 }
2456
2457 =head2 $c->prepare_write
2458
2459 Prepares the output for writing.
2460
2461 =cut
2462
2463 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2464
2465 =head2 $c->request_class
2466
2467 Returns or sets the request class. Defaults to L<Catalyst::Request>.
2468
2469 =head2 $c->response_class
2470
2471 Returns or sets the response class. Defaults to L<Catalyst::Response>.
2472
2473 =head2 $c->read( [$maxlength] )
2474
2475 Reads a chunk of data from the request body. This method is designed to
2476 be used in a while loop, reading C<$maxlength> bytes on every call.
2477 C<$maxlength> defaults to the size of the request if not specified.
2478
2479 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2480 directly.
2481
2482 Warning: If you use read(), Catalyst will not process the body,
2483 so you will not be able to access POST parameters or file uploads via
2484 $c->request.  You must handle all body parsing yourself.
2485
2486 =cut
2487
2488 sub read { my $c = shift; return $c->request->read( @_ ) }
2489
2490 =head2 $c->run
2491
2492 Starts the engine.
2493
2494 =cut
2495
2496 sub run {
2497   my $app = shift;
2498   $app->_make_immutable_if_needed;
2499   $app->engine_loader->needs_psgi_engine_compat_hack ?
2500     $app->engine->run($app, @_) :
2501       $app->engine->run( $app, $app->_finalized_psgi_app, @_ );
2502 }
2503
2504 sub _make_immutable_if_needed {
2505     my $class = shift;
2506     my $meta = find_meta($class);
2507     my $isa_ca = $class->isa('Class::Accessor::Fast') || $class->isa('Class::Accessor');
2508     if (
2509         $meta->is_immutable
2510         && ! { $meta->immutable_options }->{replace_constructor}
2511         && $isa_ca
2512     ) {
2513         warn("You made your application class ($class) immutable, "
2514             . "but did not inline the\nconstructor. "
2515             . "This will break catalyst, as your app \@ISA "
2516             . "Class::Accessor(::Fast)?\nPlease pass "
2517             . "(replace_constructor => 1)\nwhen making your class immutable.\n");
2518     }
2519     unless ($meta->is_immutable) {
2520         # XXX - FIXME warning here as you should make your app immutable yourself.
2521         $meta->make_immutable(
2522             replace_constructor => 1,
2523         );
2524     }
2525 }
2526
2527 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2528
2529 Sets an action in a given namespace.
2530
2531 =cut
2532
2533 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2534
2535 =head2 $c->setup_actions($component)
2536
2537 Sets up actions for a component.
2538
2539 =cut
2540
2541 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2542
2543 =head2 $c->setup_components
2544
2545 This method is called internally to set up the application's components.
2546
2547 It finds modules by calling the L<locate_components> method, expands them to
2548 package names with the L<expand_component_module> method, and then installs
2549 each component into the application.
2550
2551 The C<setup_components> config option is passed to both of the above methods.
2552
2553 Installation of each component is performed by the L<setup_component> method,
2554 below.
2555
2556 =cut
2557
2558 sub setup_components {
2559     my $class = shift;
2560
2561     my $config  = $class->config->{ setup_components };
2562
2563     my @comps = $class->locate_components($config);
2564     my %comps = map { $_ => 1 } @comps;
2565
2566     my $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @comps;
2567     $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
2568         qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
2569     ) if $deprecatedcatalyst_component_names;
2570
2571     for my $component ( @comps ) {
2572
2573         # We pass ignore_loaded here so that overlay files for (e.g.)
2574         # Model::DBI::Schema sub-classes are loaded - if it's in @comps
2575         # we know M::P::O found a file on disk so this is safe
2576
2577         Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
2578     }
2579
2580     for my $component (@comps) {
2581         my $instance = $class->components->{ $component } = $class->setup_component($component);
2582         my @expanded_components = $instance->can('expand_modules')
2583             ? $instance->expand_modules( $component, $config )
2584             : $class->expand_component_module( $component, $config );
2585         for my $component (@expanded_components) {
2586             next if $comps{$component};
2587             $class->components->{ $component } = $class->setup_component($component);
2588         }
2589     }
2590 }
2591
2592 =head2 $c->locate_components( $setup_component_config )
2593
2594 This method is meant to provide a list of component modules that should be
2595 setup for the application.  By default, it will use L<Module::Pluggable>.
2596
2597 Specify a C<setup_components> config option to pass additional options directly
2598 to L<Module::Pluggable>. To add additional search paths, specify a key named
2599 C<search_extra> as an array reference. Items in the array beginning with C<::>
2600 will have the application class name prepended to them.
2601
2602 =cut
2603
2604 sub locate_components {
2605     my $class  = shift;
2606     my $config = shift;
2607
2608     my @paths   = qw( ::M ::Model ::V ::View ::C ::Controller );
2609     my $extra   = delete $config->{ search_extra } || [];
2610
2611     unshift @paths, @$extra;
2612
2613     my @comps = map { sort { length($a) <=> length($b) } Module::Pluggable::Object->new(
2614       search_path => [ map { s/^(?=::)/$class/; $_; } ($_) ],
2615       %$config
2616     )->plugins } @paths;
2617
2618     return @comps;
2619 }
2620
2621 =head2 $c->expand_component_module( $component, $setup_component_config )
2622
2623 Components found by C<locate_components> will be passed to this method, which
2624 is expected to return a list of component (package) names to be set up.
2625
2626 =cut
2627
2628 sub expand_component_module {
2629     my ($class, $module) = @_;
2630     return Devel::InnerPackage::list_packages( $module );
2631 }
2632
2633 =head2 $c->setup_component
2634
2635 =cut
2636
2637 sub setup_component {
2638     my( $class, $component ) = @_;
2639
2640     unless ( $component->can( 'COMPONENT' ) ) {
2641         return $component;
2642     }
2643
2644     my $suffix = Catalyst::Utils::class2classsuffix( $component );
2645     my $config = $class->config->{ $suffix } || {};
2646     # Stash catalyst_component_name in the config here, so that custom COMPONENT
2647     # methods also pass it. local to avoid pointlessly shitting in config
2648     # for the debug screen, as $component is already the key name.
2649     local $config->{catalyst_component_name} = $component;
2650
2651     my $instance = eval { $component->COMPONENT( $class, $config ); };
2652
2653     if ( my $error = $@ ) {
2654         chomp $error;
2655         Catalyst::Exception->throw(
2656             message => qq/Couldn't instantiate component "$component", "$error"/
2657         );
2658     }
2659
2660     unless (blessed $instance) {
2661         my $metaclass = Moose::Util::find_meta($component);
2662         my $method_meta = $metaclass->find_method_by_name('COMPONENT');
2663         my $component_method_from = $method_meta->associated_metaclass->name;
2664         my $value = defined($instance) ? $instance : 'undef';
2665         Catalyst::Exception->throw(
2666             message =>
2667             qq/Couldn't instantiate component "$component", COMPONENT() method (from $component_method_from) didn't return an object-like value (value was $value)./
2668         );
2669     }
2670     return $instance;
2671 }
2672
2673 =head2 $c->setup_dispatcher
2674
2675 Sets up dispatcher.
2676
2677 =cut
2678
2679 sub setup_dispatcher {
2680     my ( $class, $dispatcher ) = @_;
2681
2682     if ($dispatcher) {
2683         $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
2684     }
2685
2686     if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
2687         $dispatcher = 'Catalyst::Dispatcher::' . $env;
2688     }
2689
2690     unless ($dispatcher) {
2691         $dispatcher = $class->dispatcher_class;
2692     }
2693
2694     load_class($dispatcher);
2695
2696     # dispatcher instance
2697     $class->dispatcher( $dispatcher->new );
2698 }
2699
2700 =head2 $c->setup_engine
2701
2702 Sets up engine.
2703
2704 =cut
2705
2706 sub engine_class {
2707     my ($class, $requested_engine) = @_;
2708
2709     if (!$class->engine_loader || $requested_engine) {
2710         $class->engine_loader(
2711             Catalyst::EngineLoader->new({
2712                 application_name => $class,
2713                 (defined $requested_engine
2714                      ? (catalyst_engine_class => $requested_engine) : ()),
2715             }),
2716         );
2717     }
2718
2719     $class->engine_loader->catalyst_engine_class;
2720 }
2721
2722 sub setup_engine {
2723     my ($class, $requested_engine) = @_;
2724
2725     my $engine = do {
2726         my $loader = $class->engine_loader;
2727
2728         if (!$loader || $requested_engine) {
2729             $loader = Catalyst::EngineLoader->new({
2730                 application_name => $class,
2731                 (defined $requested_engine
2732                      ? (requested_engine => $requested_engine) : ()),
2733             }),
2734
2735             $class->engine_loader($loader);
2736         }
2737
2738         $loader->catalyst_engine_class;
2739     };
2740
2741     # Don't really setup_engine -- see _setup_psgi_app for explanation.
2742     return if $class->loading_psgi_file;
2743
2744     load_class($engine);
2745
2746     if ($ENV{MOD_PERL}) {
2747         my $apache = $class->engine_loader->auto;
2748
2749         my $meta = find_meta($class);
2750         my $was_immutable = $meta->is_immutable;
2751         my %immutable_options = $meta->immutable_options;
2752         $meta->make_mutable if $was_immutable;
2753
2754         $meta->add_method(handler => sub {
2755             my $r = shift;
2756             my $psgi_app = $class->_finalized_psgi_app;
2757             $apache->call_app($r, $psgi_app);
2758         });
2759
2760         $meta->make_immutable(%immutable_options) if $was_immutable;
2761     }
2762
2763     $class->engine( $engine->new );
2764
2765     return;
2766 }
2767
2768 ## This exists just to supply a prebuild psgi app for mod_perl and for the
2769 ## build in server support (back compat support for pre psgi port behavior).
2770 ## This is so that we don't build a new psgi app for each request when using
2771 ## the mod_perl handler or the built in servers (http and fcgi, etc).
2772
2773 sub _finalized_psgi_app {
2774     my ($app) = @_;
2775
2776     unless ($app->_psgi_app) {
2777         my $psgi_app = $app->_setup_psgi_app;
2778         $app->_psgi_app($psgi_app);
2779     }
2780
2781     return $app->_psgi_app;
2782 }
2783
2784 ## Look for a psgi file like 'myapp_web.psgi' (if the app is MyApp::Web) in the
2785 ## home directory and load that and return it (just assume it is doing the
2786 ## right thing :) ).  If that does not exist, call $app->psgi_app, wrap that
2787 ## in default_middleware and return it ( this is for backward compatibility
2788 ## with pre psgi port behavior ).
2789
2790 sub _setup_psgi_app {
2791     my ($app) = @_;
2792
2793     for my $home (Path::Class::Dir->new($app->config->{home})) {
2794         my $psgi_file = $home->file(
2795             Catalyst::Utils::appprefix($app) . '.psgi',
2796         );
2797
2798         next unless -e $psgi_file;
2799
2800         # If $psgi_file calls ->setup_engine, it's doing so to load
2801         # Catalyst::Engine::PSGI. But if it does that, we're only going to
2802         # throw away the loaded PSGI-app and load the 5.9 Catalyst::Engine
2803         # anyway. So set a flag (ick) that tells setup_engine not to populate
2804         # $c->engine or do any other things we might regret.
2805
2806         $app->loading_psgi_file(1);
2807         my $psgi_app = Plack::Util::load_psgi($psgi_file);
2808         $app->loading_psgi_file(0);
2809
2810         return $psgi_app
2811             unless $app->engine_loader->needs_psgi_engine_compat_hack;
2812
2813         warn <<"EOW";
2814 Found a legacy Catalyst::Engine::PSGI .psgi file at ${psgi_file}.
2815
2816 Its content has been ignored. Please consult the Catalyst::Upgrading
2817 documentation on how to upgrade from Catalyst::Engine::PSGI.
2818 EOW
2819     }
2820
2821     return $app->apply_default_middlewares($app->psgi_app);
2822 }
2823
2824 =head2 $c->apply_default_middlewares
2825
2826 Adds the following L<Plack> middlewares to your application, since they are
2827 useful and commonly needed:
2828
2829 L<Plack::Middleware::ReverseProxy>, (conditionally added based on the status
2830 of your $ENV{REMOTE_ADDR}, and can be forced on with C<using_frontend_proxy>
2831 or forced off with C<ignore_frontend_proxy>), L<Plack::Middleware::LighttpdScriptNameFix>
2832 (if you are using Lighttpd), L<Plack::Middleware::IIS6ScriptNameFix> (always
2833 applied since this middleware is smart enough to conditionally apply itself).
2834
2835 Additionally if we detect we are using Nginx, we add a bit of custom middleware
2836 to solve some problems with the way that server handles $ENV{PATH_INFO} and
2837 $ENV{SCRIPT_NAME}
2838
2839 =cut
2840
2841
2842 sub apply_default_middlewares {
2843     my ($app, $psgi_app) = @_;
2844
2845     $psgi_app = Plack::Middleware::Conditional->wrap(
2846         $psgi_app,
2847         builder   => sub { Plack::Middleware::ReverseProxy->wrap($_[0]) },
2848         condition => sub {
2849             my ($env) = @_;
2850             return if $app->config->{ignore_frontend_proxy};
2851             return $env->{REMOTE_ADDR} eq '127.0.0.1'
2852                 || $app->config->{using_frontend_proxy};
2853         },
2854     );
2855
2856     # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
2857     # http://lists.scsys.co.uk/pipermail/catalyst/2006-June/008361.html
2858     $psgi_app = Plack::Middleware::Conditional->wrap(
2859         $psgi_app,
2860         builder   => sub { Plack::Middleware::LighttpdScriptNameFix->wrap($_[0]) },
2861         condition => sub {
2862             my ($env) = @_;
2863             return unless $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!lighttpd[-/]1\.(\d+\.\d+)!;
2864             return unless $1 < 4.23;
2865             1;
2866         },
2867     );
2868
2869     # we're applying this unconditionally as the middleware itself already makes
2870     # sure it doesn't fuck things up if it's not running under one of the right
2871     # IIS versions
2872     $psgi_app = Plack::Middleware::IIS6ScriptNameFix->wrap($psgi_app);
2873
2874     # And another IIS issue, this time with IIS7.
2875     $psgi_app = Plack::Middleware::Conditional->wrap(
2876         $psgi_app,
2877         builder => sub { Plack::Middleware::IIS7KeepAliveFix->wrap($_[0]) },
2878         condition => sub {
2879             my ($env) = @_;
2880             return $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!IIS/7\.[0-9]!;
2881         },
2882     );
2883
2884     return $psgi_app;
2885 }
2886
2887 =head2 $c->psgi_app
2888
2889 Returns a PSGI application code reference for the catalyst application
2890 C<$c>. This is the bare application without any middlewares
2891 applied. C<${myapp}.psgi> is not taken into account.
2892
2893 This is what you want to be using to retrieve the PSGI application code
2894 reference of your Catalyst application for use in F<.psgi> files.
2895
2896 =cut
2897
2898 sub psgi_app {
2899     my ($app) = @_;
2900     my $psgi = $app->engine->build_psgi_app($app);
2901     return $app->Catalyst::Utils::apply_registered_middleware($psgi);
2902 }
2903
2904
2905 =head2 trace_level
2906
2907 Class attribute which is a positive number and defines the noiseness of the
2908 application trace.  See L</TRACING>.
2909
2910 =head2 trace_logger
2911
2912 Class attribute which is a handler for reporting your traces.  See L</TRACING>.
2913
2914 =head2 $c->setup_trace
2915
2916 Examples your %ENV, configuation and application settings to setup how and if
2917 application tracing is enabled.  See L</TRACING>.
2918
2919 =head2 $c->trace
2920
2921 Accepts a string $message and level for a trace message.  The configured
2922 trace level must equal or exceed the level given.  Level is required and should
2923 be a positive integer. For more see L</TRACING>.
2924
2925 =cut
2926
2927 sub setup_trace {
2928   my ($app, @args) = @_;
2929
2930   # first we look for %ENV
2931   if(my $trace = Catalyst::Utils::env_value( $app, 'TRACE' )) {
2932     # extract a file path if it exists;
2933     my ($level,$op, $path) = ($trace=~m/^(.+)(\=|\+\=)(.+)$/);
2934     if($level && $op && $path) {
2935       open(my $fh, '>', $path)
2936         ||die "Cannot open trace file at $path: $!";
2937       $app->trace_logger($fh);
2938       $app->trace_level($level);
2939     } else {
2940       $app->trace_level($trace);
2941     }
2942   }
2943
2944   # Next, we look at config
2945   $app->trace_level($app->config->{trace_level}) unless defined($app->trace_level);
2946   $app->trace_logger($app->config->{trace_logger}) unless defined($app->trace_logger);
2947
2948   # We do setup_trace AFTER setup_log, so this stuff should be all good to
2949   # use by this point in application setup.  For BackCompat, we will try to
2950   # respect ->debug
2951
2952   if($app->debug) {
2953     $app->trace_level(1) unless defined($app->trace_level);
2954     $app->trace_logger(sub { shift->log->debug }) unless defined($app->trace_logger);
2955   }
2956
2957   # Last, we set defaults if the settings are still emtpy
2958   # Setup the defaults
2959
2960   $app->trace_level(0) unless defined($app->trace_level);
2961   $app->trace_logger(sub { shift->log->debug }) unless defined($app->trace_logger);
2962
2963   return;
2964 }
2965
2966 sub trace {
2967   my ($class, $message, $level) = @_;
2968   die "Level is required" unless defined $level;
2969   if($class->trace_level >= $level) {
2970     ref($class->trace_logger) eq 'CODE' ?
2971       $class->trace_logger->($class, $message, $level) :
2972         $class->trace_logger->print($message);
2973   }
2974 }
2975
2976 =head2 $c->setup_home
2977
2978 Sets up the home directory.
2979
2980 =cut
2981
2982 sub setup_home {
2983     my ( $class, $home ) = @_;
2984
2985     if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
2986         $home = $env;
2987     }
2988
2989     $home ||= Catalyst::Utils::home($class);
2990
2991     if ($home) {
2992         #I remember recently being scolded for assigning config values like this
2993         $class->config->{home} ||= $home;
2994         $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
2995     }
2996 }
2997
2998 =head2 $c->setup_log
2999
3000 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
3001 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
3002 log to.
3003
3004 This method also installs a C<debug> method that returns a true value into the
3005 catalyst subclass if the "debug" level is passed in the comma-delimited list,
3006 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
3007
3008 Note that if the log has already been setup, by either a previous call to
3009 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
3010 that this method won't actually set up the log object.
3011
3012 =cut
3013
3014 sub setup_log {
3015     my ( $class, $levels ) = @_;
3016
3017     $levels ||= '';
3018     $levels =~ s/^\s+//;
3019     $levels =~ s/\s+$//;
3020     my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
3021
3022     my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
3023     if ( defined $env_debug ) {
3024         $levels{debug} = 1 if $env_debug; # Ugly!
3025         delete($levels{debug}) unless $env_debug;
3026     }
3027
3028     unless ( $class->log ) {
3029         $class->log( Catalyst::Log->new(keys %levels) );
3030     }
3031
3032     if ( $levels{debug} ) {
3033         Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
3034         $class->log->debug('Debug messages enabled');
3035     }
3036 }
3037
3038 =head2 $c->setup_plugins
3039
3040 Sets up plugins.
3041
3042 =cut
3043
3044 =head2 $c->setup_stats
3045
3046 Sets up timing statistics class.
3047
3048 =cut
3049
3050 sub setup_stats {
3051     my ( $class, $stats ) = @_;
3052
3053     Catalyst::Utils::ensure_class_loaded($class->stats_class);
3054
3055     my $env = Catalyst::Utils::env_value( $class, 'STATS' );
3056     if ( defined($env) ? $env : ($stats || $class->debug ) ) {
3057         Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
3058         $class->log->debug('Statistics enabled');
3059     }
3060 }
3061
3062
3063 =head2 $c->registered_plugins
3064
3065 Returns a sorted list of the plugins which have either been stated in the
3066 import list.
3067
3068 If passed a given plugin name, it will report a boolean value indicating
3069 whether or not that plugin is loaded.  A fully qualified name is required if
3070 the plugin name does not begin with C<Catalyst::Plugin::>.
3071
3072  if ($c->registered_plugins('Some::Plugin')) {
3073      ...
3074  }
3075
3076 =cut
3077
3078 {
3079
3080     sub registered_plugins {
3081         my $proto = shift;
3082         return sort keys %{ $proto->_plugins } unless @_;
3083         my $plugin = shift;
3084         return 1 if exists $proto->_plugins->{$plugin};
3085         return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
3086     }
3087
3088     sub _register_plugin {
3089         my ( $proto, $plugin, $instant ) = @_;
3090         my $class = ref $proto || $proto;
3091
3092         load_class( $plugin );
3093         $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
3094             if $plugin->isa( 'Catalyst::Component' );
3095         my $plugin_meta = Moose::Meta::Class->create($plugin);
3096         if (!$plugin_meta->has_method('new')
3097             && ( $plugin->isa('Class::Accessor::Fast') || $plugin->isa('Class::Accessor') ) ) {
3098             $plugin_meta->add_method('new', Moose::Object->meta->get_method('new'))
3099         }
3100         if (!$instant && !$proto->_plugins->{$plugin}) {
3101             my $meta = Class::MOP::get_metaclass_by_name($class);
3102             $meta->superclasses($plugin, $meta->superclasses);
3103         }
3104         $proto->_plugins->{$plugin} = 1;
3105         return $class;
3106     }
3107
3108     sub _default_plugins { return qw(Unicode::Encoding) }
3109
3110     sub setup_plugins {
3111         my ( $class, $plugins ) = @_;
3112
3113         $class->_plugins( {} ) unless $class->_plugins;
3114         $plugins = [ grep {
3115             m/Unicode::Encoding/ ? do {
3116                 $class->log->warn(
3117                     'Unicode::Encoding plugin is auto-applied,'
3118                     . ' please remove this from your appclass'
3119                     . ' and make sure to define "encoding" config'
3120                 );
3121                 unless (exists $class->config->{'encoding'}) {
3122                   $class->config->{'encoding'} = 'UTF-8';
3123                 }
3124                 () }
3125                 : $_
3126         } @$plugins ];
3127         push @$plugins, $class->_default_plugins;
3128         $plugins = Data::OptList::mkopt($plugins || []);
3129
3130         my @plugins = map {
3131             [ Catalyst::Utils::resolve_namespace(
3132                   $class . '::Plugin',
3133                   'Catalyst::Plugin', $_->[0]
3134               ),
3135               $_->[1],
3136             ]
3137          } @{ $plugins };
3138
3139         for my $plugin ( reverse @plugins ) {
3140             load_class($plugin->[0], $plugin->[1]);
3141             my $meta = find_meta($plugin->[0]);
3142             next if $meta && $meta->isa('Moose::Meta::Role');
3143
3144             $class->_register_plugin($plugin->[0]);
3145         }
3146
3147         my @roles =
3148             map  { $_->[0]->name, $_->[1] }
3149             grep { blessed($_->[0]) && $_->[0]->isa('Moose::Meta::Role') }
3150             map  { [find_meta($_->[0]), $_->[1]] }
3151             @plugins;
3152
3153         Moose::Util::apply_all_roles(
3154             $class => @roles
3155         ) if @roles;
3156     }
3157 }
3158
3159 =head2 registered_middlewares
3160
3161 Read only accessor that returns an array of all the middleware in the order
3162 that they were added (which is the REVERSE of the order they will be applied).
3163
3164 The values returned will be either instances of L<Plack::Middleware> or of a
3165 compatible interface, or a coderef, which is assumed to be inlined middleware
3166
3167 =head2 setup_middleware (?@middleware)
3168
3169 Read configuration information stored in configuration key C<psgi_middleware> or
3170 from passed @args.
3171
3172 See under L</CONFIGURATION> information regarding C<psgi_middleware> and how
3173 to use it to enable L<Plack::Middleware>
3174
3175 This method is automatically called during 'setup' of your application, so
3176 you really don't need to invoke it.  However you may do so if you find the idea
3177 of loading middleware via configuration weird :).  For example:
3178
3179     package MyApp;
3180
3181     use Catalyst;
3182
3183     __PACKAGE__->setup_middleware('Head');
3184     __PACKAGE__->setup;
3185
3186 When we read middleware definitions from configuration, we reverse the list
3187 which sounds odd but is likely how you expect it to work if you have prior
3188 experience with L<Plack::Builder> or if you previously used the plugin
3189 L<Catalyst::Plugin::EnableMiddleware> (which is now considered deprecated)
3190
3191 So basically your middleware handles an incoming request from the first
3192 registered middleware, down and handles the response from the last middleware
3193 up.
3194
3195 =cut
3196
3197 sub registered_middlewares {
3198     my $class = shift;
3199     if(my $middleware = $class->_psgi_middleware) {
3200         return (
3201           Catalyst::Middleware::Stash->new,
3202           Plack::Middleware::HTTPExceptions->new,
3203           Plack::Middleware::RemoveRedundantBody->new,
3204           Plack::Middleware::FixMissingBodyInRedirect->new,
3205           Plack::Middleware::ContentLength->new,
3206           Plack::Middleware::MethodOverride->new,
3207           Plack::Middleware::Head->new,
3208           @$middleware);
3209     } else {
3210         die "You cannot call ->registered_middlewares until middleware has been setup";
3211     }
3212 }
3213
3214 sub setup_middleware {
3215     my $class = shift;
3216     my @middleware_definitions = @_ ?
3217       reverse(@_) : reverse(@{$class->config->{'psgi_middleware'}||[]});
3218
3219     my @middleware = ();
3220     while(my $next = shift(@middleware_definitions)) {
3221         if(ref $next) {
3222             if(Scalar::Util::blessed $next && $next->can('wrap')) {
3223                 push @middleware, $next;
3224             } elsif(ref $next eq 'CODE') {
3225                 push @middleware, $next;
3226             } elsif(ref $next eq 'HASH') {
3227                 my $namespace = shift @middleware_definitions;
3228                 my $mw = $class->Catalyst::Utils::build_middleware($namespace, %$next);
3229                 push @middleware, $mw;
3230             } else {
3231               die "I can't handle middleware definition ${\ref $next}";
3232             }
3233         } else {
3234           my $mw = $class->Catalyst::Utils::build_middleware($next);
3235           push @middleware, $mw;
3236         }
3237     }
3238
3239     my @existing = @{$class->_psgi_middleware || []};
3240     $class->_psgi_middleware([@middleware,@existing,]);
3241 }
3242
3243 =head2 registered_data_handlers
3244
3245 A read only copy of registered Data Handlers returned as a Hash, where each key
3246 is a content type and each value is a subref that attempts to decode that content
3247 type.
3248
3249 =head2 setup_data_handlers (?@data_handler)
3250
3251 Read configuration information stored in configuration key C<data_handlers> or
3252 from passed @args.
3253
3254 See under L</CONFIGURATION> information regarding C<data_handlers>.
3255
3256 This method is automatically called during 'setup' of your application, so
3257 you really don't need to invoke it.
3258
3259 =head2 default_data_handlers
3260
3261 Default Data Handlers that come bundled with L<Catalyst>.  Currently there are
3262 only two default data handlers, for 'application/json' and an alternative to
3263 'application/x-www-form-urlencoded' which supposed nested form parameters via
3264 L<CGI::Struct> or via L<CGI::Struct::XS> IF you've installed it.
3265
3266 The 'application/json' data handler is used to parse incoming JSON into a Perl
3267 data structure.  It used either L<JSON::MaybeXS> or L<JSON>, depending on which
3268 is installed.  This allows you to fail back to L<JSON:PP>, which is a Pure Perl
3269 JSON decoder, and has the smallest dependency impact.
3270
3271 Because we don't wish to add more dependencies to L<Catalyst>, if you wish to
3272 use this new feature we recommend installing L<JSON> or L<JSON::MaybeXS> in
3273 order to get the best performance.  You should add either to your dependency
3274 list (Makefile.PL, dist.ini, cpanfile, etc.)
3275
3276 =cut
3277
3278 sub registered_data_handlers {
3279     my $class = shift;
3280     if(my $data_handlers = $class->_data_handlers) {
3281         return %$data_handlers;
3282     } else {
3283         $class->setup_data_handlers;
3284         return $class->registered_data_handlers;
3285     }
3286 }
3287
3288 sub setup_data_handlers {
3289     my ($class, %data_handler_callbacks) = @_;
3290     %data_handler_callbacks = (
3291       %{$class->default_data_handlers},
3292       %{$class->config->{'data_handlers'}||+{}},
3293       %data_handler_callbacks);
3294
3295     $class->_data_handlers(\%data_handler_callbacks);
3296 }
3297
3298 sub default_data_handlers {
3299     my ($class) = @_;
3300     return +{
3301       'application/x-www-form-urlencoded' => sub {
3302           my ($fh, $req) = @_;
3303           my $params = $req->_use_hash_multivalue ? $req->body_parameters->mixed : $req->body_parameters;
3304           Class::Load::load_first_existing_class('CGI::Struct::XS', 'CGI::Struct')
3305             ->can('build_cgi_struct')->($params);
3306       },
3307       'application/json' => sub {
3308           Class::Load::load_first_existing_class('JSON::MaybeXS', 'JSON')
3309             ->can('decode_json')->(do { local $/; $_->getline });
3310       },
3311     };
3312 }
3313
3314 =head2 $c->stack
3315
3316 Returns an arrayref of the internal execution stack (actions that are
3317 currently executing).
3318
3319 =head2 $c->stats
3320
3321 Returns the current timing statistics object. By default Catalyst uses
3322 L<Catalyst::Stats|Catalyst::Stats>, but can be set otherwise with
3323 L<< stats_class|/"$c->stats_class" >>.
3324
3325 Even if L<< -Stats|/"-Stats" >> is not enabled, the stats object is still
3326 available. By enabling it with C< $c->stats->enabled(1) >, it can be used to
3327 profile explicitly, although MyApp.pm still won't profile nor output anything
3328 by itself.
3329
3330 =head2 $c->stats_class
3331
3332 Returns or sets the stats (timing statistics) class. L<Catalyst::Stats|Catalyst::Stats> is used by default.
3333
3334 =head2 $c->use_stats
3335
3336 Returns 1 when L<< stats collection|/"-Stats" >> is enabled.
3337
3338 Note that this is a static method, not an accessor and should be overridden
3339 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
3340
3341 =cut
3342
3343 sub use_stats { 0 }
3344
3345
3346 =head2 $c->write( $data )
3347
3348 Writes $data to the output stream. When using this method directly, you
3349 will need to manually set the C<Content-Length> header to the length of
3350 your output data, if known.
3351
3352 =cut
3353
3354 sub write {
3355     my $c = shift;
3356
3357     # Finalize headers if someone manually writes output (for compat)
3358     $c->finalize_headers;
3359
3360     return $c->response->write( @_ );
3361 }
3362
3363 =head2 version
3364
3365 Returns the Catalyst version number. Mostly useful for "powered by"
3366 messages in template systems.
3367
3368 =cut
3369
3370 sub version { return $Catalyst::VERSION }
3371
3372 =head1 CONFIGURATION
3373
3374 There are a number of 'base' config variables which can be set:
3375
3376 =over
3377
3378 =item *
3379
3380 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
3381
3382 =item *
3383
3384 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
3385
3386 =item *
3387
3388 C<disable_component_resolution_regex_fallback> - Turns
3389 off the deprecated component resolution functionality so
3390 that if any of the component methods (e.g. C<< $c->controller('Foo') >>)
3391 are called then regex search will not be attempted on string values and
3392 instead C<undef> will be returned.
3393
3394 =item *
3395
3396 C<home> - The application home directory. In an uninstalled application,
3397 this is the top level application directory. In an installed application,
3398 this will be the directory containing C<< MyApp.pm >>.
3399
3400 =item *
3401
3402 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
3403
3404 =item *
3405
3406 C<name> - The name of the application in debug messages and the debug and
3407 welcome screens
3408
3409 =item *
3410
3411 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
3412 until it is accessed. This allows you to (for example) check authentication (and reject
3413 the upload) before actually receiving all the data. See L</ON-DEMAND PARSER>
3414
3415 =item *
3416
3417 C<root> - The root directory for templates. Usually this is just a
3418 subdirectory of the home directory, but you can set it to change the
3419 templates to a different directory.
3420
3421 =item *
3422
3423 C<search_extra> - Array reference passed to Module::Pluggable to for additional
3424 namespaces from which components will be loaded (and constructed and stored in
3425 C<< $c->components >>).
3426
3427 =item *
3428
3429 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
3430 to be shown in hit debug tables in the test server.
3431
3432 =item *
3433
3434 C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
3435 variable should be used for determining the request path.
3436
3437 Most web server environments pass the requested path to the application using environment variables,
3438 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
3439 exposed as C<< $c->request->base >>) and the request path below that base.
3440
3441 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
3442 is determined by the C<< $c->config(use_request_uri_for_path) >> setting (which can either be true or false).
3443
3444 =over
3445
3446 =item use_request_uri_for_path => 0
3447
3448 This is the default (and the) traditional method that Catalyst has used for determining the path information.
3449 The path is generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
3450 The allows the application to behave correctly when C<mod_rewrite> is being used to redirect requests
3451 into the application, as these variables are adjusted by mod_rewrite to take account for the redirect.
3452
3453 However this method has the major disadvantage that it is impossible to correctly decode some elements
3454 of the path, as RFC 3875 says: "C<< Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
3455 contain path-segment parameters. >>" This means PATH_INFO is B<always> decoded, and therefore Catalyst
3456 can't distinguish / vs %2F in paths (in addition to other encoded values).
3457
3458 =item use_request_uri_for_path => 1
3459
3460 This method uses the C<REQUEST_URI> and C<SCRIPT_NAME> environment variables. As C<REQUEST_URI> is never
3461 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
3462 (i.e. with C<AllowEncodedSlashes> set to C<On> in Apache).
3463
3464 Given that this method of path resolution is provably more correct, it is recommended that you use
3465 this unless you have a specific need to deploy your application in a non-standard environment, and you are
3466 aware of the implications of not being able to handle encoded URI paths correctly.
3467
3468 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
3469 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public_html directory, with mod_rewrite in a
3470 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
3471 at other URIs than that which the app is 'normally' based at with C<mod_rewrite>), the resolution of
3472 C<< $c->request->base >> will be incorrect.
3473
3474 =back
3475
3476 =item *
3477
3478 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
3479
3480 =item *
3481
3482 C<encoding> - See L</ENCODING>
3483
3484 =item *
3485
3486 C<abort_chain_on_error_fix>
3487
3488 When there is an error in an action chain, the default behavior is to continue
3489 processing the remaining actions and then catch the error upon chain end.  This
3490 can lead to running actions when the application is in an unexpected state.  If
3491 you have this issue, setting this config value to true will promptly exit a
3492 chain when there is an error raised in any action (thus terminating the chain
3493 early.)
3494
3495 use like:
3496
3497     __PACKAGE__->config(abort_chain_on_error_fix => 1);
3498
3499 In the future this might become the default behavior.
3500
3501 =item *
3502
3503 C<use_hash_multivalue_in_request>
3504
3505 In L<Catalyst::Request> the methods C<query_parameters>, C<body_parametes>
3506 and C<parameters> return a hashref where values might be scalar or an arrayref
3507 depending on the incoming data.  In many cases this can be undesirable as it
3508 leads one to writing defensive code like the following:
3509
3510     my ($val) = ref($c->req->parameters->{a}) ?
3511       @{$c->req->parameters->{a}} :
3512         $c->req->parameters->{a};
3513
3514 Setting this configuration item to true will make L<Catalyst> populate the
3515 attributes underlying these methods with an instance of L<Hash::MultiValue>
3516 which is used by L<Plack::Request> and others to solve this very issue.  You
3517 may prefer this behavior to the default, if so enable this option (be warned
3518 if you enable it in a legacy application we are not sure if it is completely
3519 backwardly compatible).
3520
3521 =item *
3522
3523 C<psgi_middleware> - See L</PSGI MIDDLEWARE>.
3524
3525 =item *
3526
3527 C<data_handlers> - See L</DATA HANDLERS>.
3528
3529 =item *
3530
3531 trace_level - This sets your application trace level - See L</TRACING>.
3532
3533 =item *
3534
3535 trace_logger - This sets your application trace logger - See L</TRACING>.
3536
3537 =back
3538
3539 =head1 EXCEPTIONS
3540
3541 Generally when you throw an exception inside an Action (or somewhere in
3542 your stack, such as in a model that an Action is calling) that exception
3543 is caught by Catalyst and unless you either catch it yourself (via eval
3544 or something like L<Try::Tiny> or by reviewing the L</error> stack, it
3545 will eventually reach L</finalize_errors> and return either the debugging
3546 error stack page, or the default error page.  However, if your exception
3547 can be caught by L<Plack::Middleware::HTTPExceptions>, L<Catalyst> will
3548 instead rethrow it so that it can be handled by that middleware (which
3549 is part of the default middleware).  For example this would allow
3550
3551     use HTTP::Throwable::Factory 'http_throw';
3552
3553     sub throws_exception :Local {
3554       my ($self, $c) = @_;
3555
3556       http_throw(SeeOther => { location =>
3557         $c->uri_for($self->action_for('redirect')) });
3558
3559     }
3560
3561 =head1 INTERNAL ACTIONS
3562
3563 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
3564 C<_ACTION>, and C<_END>. These are by default not shown in the private
3565 action table, but you can make them visible with a config parameter.
3566
3567     MyApp->config(show_internal_actions => 1);
3568
3569 =head1 ON-DEMAND PARSER
3570
3571 The request body is usually parsed at the beginning of a request,
3572 but if you want to handle input yourself, you can enable on-demand
3573 parsing with a config parameter.
3574
3575     MyApp->config(parse_on_demand => 1);
3576
3577 =head1 PROXY SUPPORT
3578
3579 Many production servers operate using the common double-server approach,
3580 with a lightweight frontend web server passing requests to a larger
3581 backend server. An application running on the backend server must deal
3582 with two problems: the remote user always appears to be C<127.0.0.1> and
3583 the server's hostname will appear to be C<localhost> regardless of the
3584 virtual host that the user connected through.
3585
3586 Catalyst will automatically detect this situation when you are running
3587 the frontend and backend servers on the same machine. The following
3588 changes are made to the request.
3589
3590     $c->req->address is set to the user's real IP address, as read from
3591     the HTTP X-Forwarded-For header.
3592
3593     The host value for $c->req->base and $c->req->uri is set to the real
3594     host, as read from the HTTP X-Forwarded-Host header.
3595
3596 Additionally, you may be running your backend application on an insecure
3597 connection (port 80) while your frontend proxy is running under SSL.  If there
3598 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
3599 tell Catalyst what port the frontend listens on.  This will allow all URIs to
3600 be created properly.
3601
3602 In the case of passing in:
3603
3604     X-Forwarded-Port: 443
3605
3606 All calls to C<uri_for> will result in an https link, as is expected.
3607
3608 Obviously, your web server must support these headers for this to work.
3609
3610 In a more complex server farm environment where you may have your
3611 frontend proxy server(s) on different machines, you will need to set a
3612 configuration option to tell Catalyst to read the proxied data from the
3613 headers.
3614
3615     MyApp->config(using_frontend_proxy => 1);
3616
3617 If you do not wish to use the proxy support at all, you may set:
3618
3619     MyApp->config(ignore_frontend_proxy => 0);
3620
3621 =head2 Note about psgi files
3622
3623 Note that if you supply your own .psgi file, calling
3624 C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.
3625
3626 You either need to apply L<Plack::Middleware::ReverseProxy> yourself
3627 in your psgi, for example:
3628
3629     builder {
3630         enable "Plack::Middleware::ReverseProxy";
3631         MyApp->psgi_app
3632     };
3633
3634 This will unconditionally add the ReverseProxy support, or you need to call
3635 C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
3636 apply the support depending upon your config).
3637
3638 See L<Catalyst::PSGI> for more information.
3639
3640 =head1 THREAD SAFETY
3641
3642 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
3643 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
3644 believe the Catalyst core to be thread-safe.
3645
3646 If you plan to operate in a threaded environment, remember that all other
3647 modules you are using must also be thread-safe. Some modules, most notably
3648 L<DBD::SQLite>, are not thread-safe.
3649
3650 =head1 DATA HANDLERS
3651
3652 The L<Catalyst::Request> object uses L<HTTP::Body> to populate 'classic' HTML
3653 form parameters and URL search query fields.  However it has become common
3654 for various alternative content types to be PUT or POSTed to your controllers
3655 and actions.  People working on RESTful APIs, or using AJAX often use JSON,
3656 XML and other content types when communicating with an application server.  In
3657 order to better support this use case, L<Catalyst> defines a global configuration
3658 option, C<data_handlers>, which lets you associate a content type with a coderef
3659 that parses that content type into something Perl can readily access.
3660
3661     package MyApp::Web;
3662
3663     use Catalyst;
3664     use JSON::Maybe;
3665
3666     __PACKAGE__->config(
3667       data_handlers => {
3668         'application/json' => sub { local $/; decode_json $_->getline },
3669       },
3670       ## Any other configuration.
3671     );
3672
3673     __PACKAGE__->setup;
3674
3675 By default L<Catalyst> comes with a generic JSON data handler similar to the
3676 example given above, which uses L<JSON::Maybe> to provide either L<JSON::PP>
3677 (a pure Perl, dependency free JSON parser) or L<Cpanel::JSON::XS> if you have
3678 it installed (if you want the faster XS parser, add it to you project Makefile.PL
3679 or dist.ini, cpanfile, etc.)
3680
3681 The C<data_handlers> configuration is a hashref whose keys are HTTP Content-Types
3682 (matched against the incoming request type using a regexp such as to be case
3683 insensitive) and whose values are coderefs that receive a localized version of
3684 C<$_> which is a filehandle object pointing to received body.
3685
3686 This feature is considered an early access release and we reserve the right
3687 to alter the interface in order to provide a performant and secure solution to
3688 alternative request body content.  Your reports welcomed!
3689
3690 =head1 PSGI MIDDLEWARE
3691
3692 You can define middleware, defined as L<Plack::Middleware> or a compatible
3693 interface in configuration.  Your middleware definitions are in the form of an
3694 arrayref under the configuration key C<psgi_middleware>.  Here's an example
3695 with details to follow:
3696
3697     package MyApp::Web;
3698
3699     use Catalyst;
3700     use Plack::Middleware::StackTrace;
3701
3702     my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
3703
3704     __PACKAGE__->config(
3705       'psgi_middleware', [
3706         'Debug',
3707         '+MyApp::Custom',
3708         $stacktrace_middleware,
3709         'Session' => {store => 'File'},
3710         sub {
3711           my $app = shift;
3712           return sub {
3713             my $env = shift;
3714             $env->{myapp.customkey} = 'helloworld';
3715             $app->($env);
3716           },
3717         },
3718       ],
3719     );
3720
3721     __PACKAGE__->setup;
3722
3723 So the general form is:
3724
3725     __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
3726
3727 Where C<@middleware> is one or more of the following, applied in the REVERSE of
3728 the order listed (to make it function similarly to L<Plack::Builder>:
3729
3730 Alternatively, you may also define middleware by calling the L</setup_middleware>
3731 package method:
3732
3733     package MyApp::Web;
3734
3735     use Catalyst;
3736
3737     __PACKAGE__->setup_middleware( \@middleware_definitions);
3738     __PACKAGE__->setup;
3739
3740 In the case where you do both (use 'setup_middleware' and configuration) the
3741 package call to setup_middleware will be applied earlier (in other words its
3742 middleware will wrap closer to the application).  Keep this in mind since in
3743 some cases the order of middleware is important.
3744
3745 The two approaches are not exclusive.
3746
3747 =over 4
3748
3749 =item Middleware Object
3750
3751 An already initialized object that conforms to the L<Plack::Middleware>
3752 specification:
3753
3754     my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
3755
3756     __PACKAGE__->config(
3757       'psgi_middleware', [
3758         $stacktrace_middleware,
3759       ]);
3760
3761
3762 =item coderef
3763
3764 A coderef that is an inlined middleware:
3765
3766     __PACKAGE__->config(
3767       'psgi_middleware', [
3768         sub {
3769           my $app = shift;
3770           return sub {
3771             my $env = shift;
3772             if($env->{PATH_INFO} =~m/forced/) {
3773               Plack::App::File
3774                 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
3775                 ->call($env);
3776             } else {
3777               return $app->($env);
3778             }
3779          },
3780       },
3781     ]);
3782
3783
3784
3785 =item a scalar
3786
3787 We assume the scalar refers to a namespace after normalizing it using the
3788 following rules:
3789
3790 (1) If the scalar is prefixed with a "+" (as in C<+MyApp::Foo>) then the full string
3791 is assumed to be 'as is', and we just install and use the middleware.
3792
3793 (2) If the scalar begins with "Plack::Middleware" or your application namespace
3794 (the package name of your Catalyst application subclass), we also assume then
3795 that it is a full namespace, and use it.
3796
3797 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
3798 resolve it first by looking for it under your application namespace (for example
3799 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
3800 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
3801 will then look under the regular L<Plack::Middleware> namespace (i.e. for the
3802 previous we'd try "Plack::Middleware::MyMiddleware").  We look under your application
3803 namespace first to let you 'override' common L<Plack::Middleware> locally, should
3804 you find that a good idea.
3805
3806 Examples:
3807
3808     package MyApp::Web;
3809
3810     __PACKAGE__->config(
3811       'psgi_middleware', [
3812         'Debug',  ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
3813         'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
3814         '+MyApp::Custom',  ## MyApp::Custom->wrap
3815       ],
3816     );
3817
3818 =item a scalar followed by a hashref
3819
3820 Just like the previous, except the following C<HashRef> is used as arguments
3821 to initialize the middleware object.
3822
3823     __PACKAGE__->config(
3824       'psgi_middleware', [
3825          'Session' => {store => 'File'},
3826     ]);
3827
3828 =back
3829
3830 Please see L<PSGI> for more on middleware.
3831
3832 =head1 TRACING
3833
3834 B<NOTE> Tracing replaces the functionality of L<Debug>.  For now both
3835 interfaces will be supported but it is suggested that you become familiar with
3836 the new interface and begin using it.
3837
3838 Application tracing is debugging information about the state of your L<Catalyst>
3839 application and a request / response cycle.  This is often used when you want a
3840 peek into the 'Catalyst Black Box' without needing to actually hack into the
3841 core code and add debugging statements.  Examples of application tracing include
3842 startup information about loaded plugins, middleware, models, controllers and
3843 views.  It also includes details about how a request is dispatched (what actions
3844 in what controllers are hit, and approximately how long each took) and how a
3845 response is generated.  Additional trace information includes details about errors
3846 and some basic statistics on your running application.
3847
3848 It is often the case when running an application in a development environment
3849 for development purposes that you will enable tracing to assist you in your work.
3850 However, application tracing is not strictly tied to environment so trace levels
3851 are not automatically enabled based on any environment settings (although you are
3852 allowed to set trace levels via configuration, which can be environment specific,
3853 if you choose so).
3854
3855 Application tracing is also not the same thing as logging. Logging is custom messages
3856 that you've added to your custom application for the purposes of better understanding
3857 your application and how effective your application is in achieving its goals.
3858 Often logging is extended, unstructured meta data around your core business logic
3859 such as details about when a user account is created or failed to be created, what
3860 types of validation issues are occuring in your forms, page views, user engagement
3861 and timestamps to help you understand your application performance.  Basically this
3862 is often information of business value that doesn't cleanly or meaningfully fit
3863 into a database.  Catalyst provides an interface for adding various kinds of
3864 Loggers which can assist you in these tasks.  Most Loggers allow one to log
3865 messages at different levels of priority, such as debug, warning, critical, etc.
3866 This is a useful feature since it permits one to turn the logging level down in
3867 high traffic environments.  In the past Catalyst tracing (previously called
3868 'Debug') was conflated with log levels of debug, in that in order to enable
3869 application tracing (or debugging) one was required to turn log level debug on
3870 globally.  Additionally, the Catalyst application tracing (or debugging) used
3871 the defined logger to 'record' its messages.  Neither is ideal since it leads
3872 one to be forced to accept more logging than may be wished, and it also does
3873 not allow one to separate development tracing from application debug logging.
3874
3875 Application tracing fixes this issues by allowing you to turn on tracing
3876 independently of setting your log level.  It also lets you define a trace
3877 log message handler separately from your logger.  So for example you might
3878 wish to send trace messages to STDOUT, but send your logging to Elasticsearch.
3879 Here's an example:
3880
3881     package MyApp;
3882
3883     use Catalyst;
3884
3885     __PACKAGE__->trace_level(1);
3886     __PACKAGE__->trace_logger(sub { my $class = shift; ...});
3887     __PACKAGE__->setup;
3888
3889 You may also configure tracing via configuration:
3890
3891     package MyApp;
3892
3893     use Catalyst;
3894
3895     __PACKAGE__->config({
3896       trace_level => 1,
3897       trace_logger => sub { my $class = shift; ...},
3898     });
3899
3900     __PACKAGE__->setup;
3901
3902 Or, you may set tracing via environment varables, for example:
3903
3904     CATALYST_TRACE=1 perl script/myapp_server.pl
3905     MYAPP_TRACE=1 perl script/myapp_server.pl
3906     MYAPP_TRACE=1=/var/log/traces perl script/myapp_server.pl
3907
3908 The order of precidence is that custom application environment variables
3909 ('MYAPP_TRACE') come first, followed by global environment variables
3910 ('CATALYST_TRACE'), followed by configuration settings and lastly application
3911 defaults.
3912
3913 For backwards compatiblity, we respect classic Catalyst debugging (L<Debug>) in
3914 the following way.  If debugging is true, we automatically set
3915 C<trace_level=1> and set the C<trace_logger> to your the debug method of your
3916 defined log object (basically it works just as described in L<Debug>).  In this
3917 case $c->debug will also be set to true.
3918
3919 Please note that if you set C<trace_level> but not debugging then debugging
3920 ($c->debug) will NOT be set to true.
3921
3922 Please note that if you set BOTH trace_level and 'class' debugging, your trace
3923 level and trace configuation is respected at a high priority, however the state
3924 of the debug method will be set as requested (although overridden).  This is
3925 done for backcompatibility with applications that overloaded the debug method
3926 in custom applications.
3927
3928 Please note that when setting trace levels via environment, you may use an
3929 extended form of the value, which opens a filehandled to a specified path
3930 and sends all trace information there:
3931
3932     MYAPP_TRACE=1=/var/log/traces perl script/myapp_server.pl
3933
3934 This would override any other settings for L<\trace_logger>.  I
3935
3936 =head2 trace_level
3937
3938 This is a number that defaults to 0.  It indicates the level of application
3939 tracing that is desired.  Larger numbers indicate greater level of tracing.
3940 Currently trace levels are defined, although at this time respect is limited,
3941 as this is a new feature.
3942
3943 Levels 1,2 and 3 are reserved for Catalyst core code (code that is part of the
3944 L<Catalyst> distribution).
3945
3946 Levels 4,5 and 6 are reserved for Catalyst extended ecosystem (Catalyst plugins,
3947 models, views and distributions under the CatalystX namespace).
3948
3949 Levels 7,8 and 9 are reserved but not currently defined.
3950
3951 Levels 10 and higher are reserved for local (not on CPAN) application use.
3952
3953 =head2 trace_logger
3954
3955 This handles a trace message, if it is determined that one should be sent based
3956 on the running L<\trace_level>.  This can accept the following values
3957
3958 =over 4
3959
3960 =item a CodeRef
3961
3962 This is a code reference that gets the application class (your Catalyst.pm
3963 subclass) as argument0, the message as argument1 and the level as argument3.
3964 The message is expected to be a string.  For example:
3965
3966     __PACKAGE__->trace_logger( sub {
3967       my ($app, $message, $level) = @_;
3968       $app->log->debug($message);
3969     });
3970
3971 Would send trace messages to the debug log handler (This is currently the
3972 default behavior).
3973
3974 =item A Filehandle or Object
3975
3976 This must be an open filehandle setup to received output.  We really
3977 just look for a 'print' method, so strictly speaking this could be
3978 any object that satisfies the duck type.
3979
3980 =item A String
3981
3982 A path that be be resolved as a file that we open a filehandle to.
3983
3984 =back
3985
3986 =head1 ENCODING
3987
3988 On request, decodes all params from encoding into a sequence of
3989 logical characters. On response, encodes body into encoding.
3990
3991 =head2 Methods
3992
3993 =over 4
3994
3995 =item encoding
3996
3997 Returns an instance of an C<Encode> encoding
3998
3999     print $c->encoding->name
4000
4001 =item handle_unicode_encoding_exception ($exception_context)
4002
4003 Method called when decoding process for a request fails.
4004
4005 An C<$exception_context> hashref is provided to allow you to override the
4006 behaviour of your application when given data with incorrect encodings.
4007
4008 The default method throws exceptions in the case of invalid request parameters
4009 (resulting in a 500 error), but ignores errors in upload filenames.
4010
4011 The keys passed in the C<$exception_context> hash are:
4012
4013 =over
4014
4015 =item param_value
4016
4017 The value which was not able to be decoded.
4018
4019 =item error_msg
4020
4021 The exception received from L<Encode>.
4022
4023 =item encoding_step
4024
4025 What type of data was being decoded. Valid values are (currently)
4026 C<params> - for request parameters / arguments / captures
4027 and C<uploads> - for request upload filenames.
4028
4029 =back
4030
4031 =back
4032
4033 =head1 SUPPORT
4034
4035 IRC:
4036
4037     Join #catalyst on irc.perl.org.
4038
4039 Mailing Lists:
4040
4041     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
4042     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
4043
4044 Web:
4045
4046     http://catalyst.perl.org
4047
4048 Wiki:
4049
4050     http://dev.catalyst.perl.org
4051
4052 =head1 SEE ALSO
4053
4054 =head2 L<Task::Catalyst> - All you need to start with Catalyst
4055
4056 =head2 L<Catalyst::Manual> - The Catalyst Manual
4057
4058 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
4059
4060 =head2 L<Catalyst::Engine> - Core engine
4061
4062 =head2 L<Catalyst::Log> - Log class.
4063
4064 =head2 L<Catalyst::Request> - Request object
4065
4066 =head2 L<Catalyst::Response> - Response object
4067
4068 =head2 L<Catalyst::Test> - The test suite.
4069
4070 =head1 PROJECT FOUNDER
4071
4072 sri: Sebastian Riedel <sri@cpan.org>
4073
4074 =head1 CONTRIBUTORS
4075
4076 abw: Andy Wardley
4077
4078 acme: Leon Brocard <leon@astray.com>
4079
4080 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
4081
4082 Andrew Bramble
4083
4084 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
4085
4086 Andrew Ruthven
4087
4088 andyg: Andy Grundman <andy@hybridized.org>
4089
4090 audreyt: Audrey Tang
4091
4092 bricas: Brian Cassidy <bricas@cpan.org>
4093
4094 Caelum: Rafael Kitover <rkitover@io.com>
4095
4096 chansen: Christian Hansen
4097
4098 chicks: Christopher Hicks
4099
4100 Chisel Wright C<pause@herlpacker.co.uk>
4101
4102 Danijel Milicevic C<me@danijel.de>
4103
4104 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
4105
4106 David Naughton, C<naughton@umn.edu>
4107
4108 David E. Wheeler
4109
4110 dhoss: Devin Austin <dhoss@cpan.org>
4111
4112 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
4113
4114 Drew Taylor
4115
4116 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4117
4118 esskar: Sascha Kiefer
4119
4120 fireartist: Carl Franks <cfranks@cpan.org>
4121
4122 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
4123
4124 gabb: Danijel Milicevic
4125
4126 Gary Ashton Jones
4127
4128 Gavin Henry C<ghenry@perl.me.uk>
4129
4130 Geoff Richards
4131
4132 groditi: Guillermo Roditi <groditi@gmail.com>
4133
4134 hobbs: Andrew Rodland <andrew@cleverdomain.org>
4135
4136 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
4137
4138 jcamacho: Juan Camacho
4139
4140 jester: Jesse Sheidlower C<jester@panix.com>
4141
4142 jhannah: Jay Hannah <jay@jays.net>
4143
4144 Jody Belka
4145
4146 Johan Lindstrom
4147
4148 jon: Jon Schutz <jjschutz@cpan.org>
4149
4150 Jonathan Rockway C<< <jrockway@cpan.org> >>
4151
4152 Kieren Diment C<kd@totaldatasolution.com>
4153
4154 konobi: Scott McWhirter <konobi@cpan.org>
4155
4156 marcus: Marcus Ramberg <mramberg@cpan.org>
4157
4158 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
4159
4160 mgrimes: Mark Grimes <mgrimes@cpan.org>
4161
4162 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
4163
4164 mugwump: Sam Vilain
4165
4166 naughton: David Naughton
4167
4168 ningu: David Kamholz <dkamholz@cpan.org>
4169
4170 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
4171
4172 numa: Dan Sully <daniel@cpan.org>
4173
4174 obra: Jesse Vincent
4175
4176 Octavian Rasnita
4177
4178 omega: Andreas Marienborg
4179
4180 Oleg Kostyuk <cub.uanic@gmail.com>
4181
4182 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
4183
4184 rafl: Florian Ragwitz <rafl@debian.org>
4185
4186 random: Roland Lammel <lammel@cpan.org>
4187
4188 Robert Sedlacek C<< <rs@474.at> >>
4189
4190 SpiceMan: Marcel Montes
4191
4192 sky: Arthur Bergman
4193
4194 szbalint: Balint Szilakszi <szbalint@cpan.org>
4195
4196 t0m: Tomas Doran <bobtfish@bobtfish.net>
4197
4198 Ulf Edvinsson
4199
4200 vanstyn: Henry Van Styn <vanstyn@cpan.org>
4201
4202 Viljo Marrandi C<vilts@yahoo.com>
4203
4204 Will Hawes C<info@whawes.co.uk>
4205
4206 willert: Sebastian Willert <willert@cpan.org>
4207
4208 wreis: Wallace Reis <wreis@cpan.org>
4209
4210 Yuval Kogman, C<nothingmuch@woobling.org>
4211
4212 rainboxx: Matthias Dietrich, C<perl@rainboxx.de>
4213
4214 dd070: Dhaval Dhanani <dhaval070@gmail.com>
4215
4216 Upasana <me@upasana.me>
4217
4218 =head1 COPYRIGHT
4219
4220 Copyright (c) 2005-2014, the above named PROJECT FOUNDER and CONTRIBUTORS.
4221
4222 =head1 LICENSE
4223
4224 This library is free software. You can redistribute it and/or modify it under
4225 the same terms as Perl itself.
4226
4227 =cut
4228
4229 no Moose;
4230
4231 __PACKAGE__->meta->make_immutable;
4232
4233 1;