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