lib/Catalyst.pm

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