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