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