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