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