lib/Catalyst.pm

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