lib/Catalyst.pm

   1 package Catalyst;
   2
   3 use strict;
   4 use base 'Catalyst::Base';
   5 use UNIVERSAL::require;
   6 use Catalyst::Log;
   7 use Catalyst::Helper;
   8 use Text::ASCIITable;
   9
  10 __PACKAGE__->mk_classdata($_) for qw/dispatcher engine log/;
  11
  12 our $VERSION = '5.00';
  13 our @ISA;
  14
  15 =head1 NAME
  16
  17 Catalyst - The Elegant MVC Web Application Framework
  18
  19 =head1 SYNOPSIS
  20
  21     # use the helper to start a new application
  22     catalyst.pl MyApp
  23     cd MyApp
  24
  25     # add models, views, controllers
  26     script/create.pl model Something
  27     script/create.pl view Stuff
  28     script/create.pl controller Yada
  29
  30     # built in testserver
  31     script/server.pl
  32
  33     # command line interface
  34     script/test.pl /yada
  35
  36
  37     use Catalyst;
  38
  39     use Catalyst qw/My::Module My::OtherModule/;
  40
  41     use Catalyst '-Debug';
  42
  43     use Catalyst qw/-Debug -Engine=CGI/;
  44
  45     sub default : Private { $_[1]->res->output('Hello') } );
  46
  47     sub index : Path('/index.html') {
  48         my ( $self, $c ) = @_;
  49         $c->res->output('Hello');
  50         $c->forward('foo');
  51     }
  52
  53     sub product : Regex('^product[_]*(\d*).html$') {
  54         my ( $self, $c ) = @_;
  55         $c->stash->{template} = 'product.tt';
  56         $c->stash->{product} = $c->req->snippets->[0];
  57     }
  58
  59 See also L<Catalyst::Manual::Intro>
  60
  61 =head1 DESCRIPTION
  62
  63 Catalyst is based upon L<Maypole>, which you should consider for smaller
  64 projects.
  65
  66 The key concept of Catalyst is DRY (Don't Repeat Yourself).
  67
  68 See L<Catalyst::Manual> for more documentation.
  69
  70 Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
  71 Omit the C<Catalyst::Plugin::> prefix from the plugin name,
  72 so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
  73
  74     use Catalyst 'My::Module';
  75
  76 Special flags like -Debug and -Engine can also be specifed as arguments when
  77 Catalyst is loaded:
  78
  79     use Catalyst qw/-Debug My::Module/;
  80
  81 The position of plugins and flags in the chain is important, because they are
  82 loaded in exactly the order that they appear.
  83
  84 The following flags are supported:
  85
  86 =over 4
  87
  88 =item -Debug
  89
  90 enables debug output, i.e.:
  91
  92     use Catalyst '-Debug';
  93
  94 this is equivalent to:
  95
  96     use Catalyst;
  97     sub debug { 1 }
  98
  99 =item -Engine
 100
 101 Force Catalyst to use a specific engine.
 102 Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
 103
 104     use Catalyst '-Engine=CGI';
 105
 106 =back
 107
 108 =head1 METHODS
 109
 110 =over 4
 111
 112 =item debug
 113
 114 Overload to enable debug messages.
 115
 116 =cut
 117
 118 sub debug { 0 }
 119
 120 =item config
 121
 122 Returns a hashref containing your applications settings.
 123
 124 =cut
 125
 126 sub import {
 127     my ( $self, @options ) = @_;
 128     my $caller = caller(0);
 129
 130     # Prepare inheritance
 131     unless ( $caller->isa($self) ) {
 132         no strict 'refs';
 133         push @{"$caller\::ISA"}, $self;
 134     }
 135
 136     if ( $caller->engine ) {
 137         return;    # Catalyst is already initialized
 138     }
 139
 140     unless ( $caller->log ) {
 141         $caller->log( Catalyst::Log->new );
 142     }
 143
 144     # Debug?
 145     if ( $ENV{CATALYST_DEBUG} || $ENV{ uc($caller) . '_DEBUG' } ) {
 146         no strict 'refs';
 147         *{"$caller\::debug"} = sub { 1 };
 148         $caller->log->debug('Debug messages enabled');
 149     }
 150
 151     my $engine     = 'Catalyst::Engine::CGI';
 152     my $dispatcher = 'Catalyst::Dispatcher';
 153
 154     # Detect mod_perl
 155     if ( $ENV{MOD_PERL} ) {
 156
 157         require mod_perl;
 158
 159         if ( $mod_perl::VERSION >= 1.99 ) {
 160             $engine = 'Catalyst::Engine::Apache::MP19';
 161         }
 162         else {
 163             $engine = 'Catalyst::Engine::Apache::MP13';
 164         }
 165     }
 166
 167     $caller->log->info("You are running an old helper script! ".
 168              "Please update your scripts by regenerating the ".
 169              "application and copying over the new scripts.")
 170         if ( $ENV{CATALYST_SCRIPT_GEN} && (
 171              $ENV{CATALYST_SCRIPT_GEN} <
 172              $Catalyst::Helper::CATALYST_SCRIPT_GEN )) ;
 173     # Process options
 174     my @plugins;
 175     foreach (@options) {
 176
 177         if (/^\-Debug$/) {
 178             next if $caller->debug;
 179             no strict 'refs';
 180             *{"$caller\::debug"} = sub { 1 };
 181             $caller->log->debug('Debug messages enabled');
 182         }
 183
 184         elsif (/^-Dispatcher=(.*)$/) {
 185             $dispatcher = "Catalyst::Dispatcher::$1";
 186         }
 187
 188         elsif (/^-Engine=(.*)$/) { $engine = "Catalyst::Engine::$1" }
 189         elsif (/^-.*$/) { $caller->log->error(qq/Unknown flag "$_"/) }
 190
 191         else {
 192             my $plugin = "Catalyst::Plugin::$_";
 193
 194             $plugin->require;
 195
 196             if ($@) { die qq/Couldn't load plugin "$plugin", "$@"/ }
 197             else {
 198                 push @plugins, $plugin;
 199                 no strict 'refs';
 200                 push @{"$caller\::ISA"}, $plugin;
 201             }
 202         }
 203
 204     }
 205
 206     # Plugin table
 207     my $t = Text::ASCIITable->new( { hide_HeadRow => 1, hide_HeadLine => 1 } );
 208     $t->setCols('Class');
 209     $t->setColWidth( 'Class', 75, 1 );
 210     $t->addRow($_) for @plugins;
 211     $caller->log->debug( 'Loaded plugins', $t->draw )
 212       if ( @plugins && $caller->debug );
 213
 214     # Engine
 215     $engine = "Catalyst::Engine::$ENV{CATALYST_ENGINE}"
 216       if $ENV{CATALYST_ENGINE};
 217
 218     $engine->require;
 219     die qq/Couldn't load engine "$engine", "$@"/ if $@;
 220     {
 221         no strict 'refs';
 222         push @{"$caller\::ISA"}, $engine;
 223     }
 224     $caller->engine($engine);
 225     $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
 226
 227     # Dispatcher
 228     $dispatcher = "Catalyst::Dispatcher::$ENV{CATALYST_DISPATCHER}"
 229       if $ENV{CATALYST_DISPATCHER};
 230
 231     $dispatcher->require;
 232     die qq/Couldn't load dispatcher "$dispatcher", "$@"/ if $@;
 233     {
 234         no strict 'refs';
 235         push @{"$caller\::ISA"}, $dispatcher;
 236     }
 237     $caller->dispatcher($dispatcher);
 238     $caller->log->debug(qq/Loaded dispatcher "$dispatcher"/) if $caller->debug;
 239
 240 }
 241
 242 =item $c->engine
 243
 244 Contains the engine class.
 245
 246 =item $c->log
 247
 248 Contains the logging object.  Unless it is already set Catalyst sets this up with a
 249 C<Catalyst::Log> object.  To use your own log class:
 250
 251     $c->log( MyLogger->new );
 252     $c->log->info("now logging with my own logger!");
 253
 254 Your log class should implement the methods described in the C<Catalyst::Log>
 255 man page.
 256
 257
 258 =back
 259
 260 =head1 LIMITATIONS
 261
 262 FCGI and mod_perl2 support are considered experimental and may contain bugs.
 263
 264 You may encounter problems accessing the built in test server on public ip
 265 addresses on the internet, thats because of a bug in HTTP::Daemon.
 266
 267 =head1 SUPPORT
 268
 269 IRC:
 270
 271     Join #catalyst on irc.perl.org.
 272
 273 Mailing-Lists:
 274
 275     http://lists.rawmode.org/mailman/listinfo/catalyst
 276     http://lists.rawmode.org/mailman/listinfo/catalyst-dev
 277
 278 =head1 SEE ALSO
 279
 280 =over 4
 281
 282 =item L<Catalyst::Manual> - The Catalyst Manual
 283
 284 =item L<Catalyst::Engine> - Core Engine
 285
 286 =item L<Catalyst::Log> - The Log Class.
 287
 288 =item L<Catalyst::Request> - The Request Object
 289
 290 =item L<Catalyst::Response> - The Response Object
 291
 292 =item L<Catalyst::Test> - The test suite.
 293
 294 =back
 295
 296 =head1 AUTHOR
 297
 298 Sebastian Riedel, C<sri@oook.de>
 299
 300 =head1 THANK YOU
 301
 302 Andy Grundman, Andrew Ford, Andrew Ruthven, Christian Hansen,
 303 Christopher Hicks, Dan Sully, Danijel Milicevic, David Naughton,
 304 Gary Ashton Jones, Jesse Sheidlower, Johan Lindstrom, Marcus Ramberg,
 305 Tatsuhiko Miyagawa and all the others who've helped.
 306
 307 =head1 LICENSE
 308
 309 This library is free software . You can redistribute it and/or modify it under
 310 the same terms as perl itself.
 311
 312 =cut
 313
 314 1;