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