4 use base 'Catalyst::Base';
5 use UNIVERSAL::require;
9 our $CATALYST_SCRIPT_GEN = 4;
11 __PACKAGE__->mk_classdata($_) for qw/dispatcher engine log/;
13 our $VERSION = '5.20';
18 Catalyst - The Elegant MVC Web Application Framework
22 # use the helper to start a new application
26 # add models, views, controllers
27 script/create.pl model Something
28 script/create.pl view Stuff
29 script/create.pl controller Yada
34 # command line interface
40 use Catalyst qw/My::Module My::OtherModule/;
42 use Catalyst '-Debug';
44 use Catalyst qw/-Debug -Engine=CGI/;
46 sub default : Private { $_[1]->res->output('Hello') } );
48 sub index : Path('/index.html') {
49 my ( $self, $c ) = @_;
50 $c->res->output('Hello');
54 sub product : Regex('^product[_]*(\d*).html$') {
55 my ( $self, $c ) = @_;
56 $c->stash->{template} = 'product.tt';
57 $c->stash->{product} = $c->req->snippets->[0];
60 See also L<Catalyst::Manual::Intro>
64 Catalyst is based upon L<Maypole>, which you should consider for smaller
67 The key concept of Catalyst is DRY (Don't Repeat Yourself).
69 See L<Catalyst::Manual> for more documentation.
71 Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
72 Omit the C<Catalyst::Plugin::> prefix from the plugin name,
73 so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
75 use Catalyst 'My::Module';
77 Special flags like -Debug and -Engine can also be specifed as arguments when
80 use Catalyst qw/-Debug My::Module/;
82 The position of plugins and flags in the chain is important, because they are
83 loaded in exactly the order that they appear.
85 The following flags are supported:
91 enables debug output, i.e.:
93 use Catalyst '-Debug';
95 this is equivalent to:
102 Force Catalyst to use a specific engine.
103 Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
105 use Catalyst '-Engine=CGI';
115 Overload to enable debug messages.
123 Returns a hashref containing your applications settings.
128 my ( $self, @options ) = @_;
129 my $caller = caller(0);
131 # Prepare inheritance
132 unless ( $caller->isa($self) ) {
134 push @{"$caller\::ISA"}, $self;
137 if ( $caller->engine ) {
138 return; # Catalyst is already initialized
141 unless ( $caller->log ) {
142 $caller->log( Catalyst::Log->new );
146 if ( $ENV{CATALYST_DEBUG} || $ENV{ uc($caller) . '_DEBUG' } ) {
148 *{"$caller\::debug"} = sub { 1 };
149 $caller->log->debug('Debug messages enabled');
152 my $engine = 'Catalyst::Engine::CGI';
153 my $dispatcher = 'Catalyst::Dispatcher';
156 if ( $ENV{MOD_PERL} ) {
160 if ( $ENV{MOD_PERL_API_VERSION} == 2 ) {
161 $engine = 'Catalyst::Engine::Apache::MP20';
163 elsif ( $mod_perl::VERSION >= 1.99 ) {
164 $engine = 'Catalyst::Engine::Apache::MP19';
167 $engine = 'Catalyst::Engine::Apache::MP13';
171 $caller->log->info( "You are running an old helper script! "
172 . "Please update your scripts by regenerating the "
173 . "application and copying over the new scripts." )
174 if ( $ENV{CATALYST_SCRIPT_GEN}
175 && ( $ENV{CATALYST_SCRIPT_GEN} < $CATALYST_SCRIPT_GEN ) );
182 next if $caller->debug;
184 *{"$caller\::debug"} = sub { 1 };
185 $caller->log->debug('Debug messages enabled');
188 elsif (/^-Dispatcher=(.*)$/) {
189 $dispatcher = "Catalyst::Dispatcher::$1";
192 elsif (/^-Engine=(.*)$/) { $engine = "Catalyst::Engine::$1" }
193 elsif (/^-.*$/) { $caller->log->error(qq/Unknown flag "$_"/) }
196 my $plugin = "Catalyst::Plugin::$_";
200 if ($@) { die qq/Couldn't load plugin "$plugin", "$@"/ }
202 push @plugins, $plugin;
204 push @{"$caller\::ISA"}, $plugin;
211 my $t = Text::ASCIITable->new( { hide_HeadRow => 1, hide_HeadLine => 1 } );
212 $t->setCols('Class');
213 $t->setColWidth( 'Class', 75, 1 );
214 $t->addRow($_) for @plugins;
215 $caller->log->debug( 'Loaded plugins', $t->draw )
216 if ( @plugins && $caller->debug );
219 $dispatcher = "Catalyst::Dispatcher::$ENV{CATALYST_DISPATCHER}"
220 if $ENV{CATALYST_DISPATCHER};
221 my $appdis = $ENV{ uc($caller) . '_DISPATCHER' };
222 $dispatcher = "Catalyst::Dispatcher::$appdis" if $appdis;
224 $dispatcher->require;
225 die qq/Couldn't load dispatcher "$dispatcher", "$@"/ if $@;
228 push @{"$caller\::ISA"}, $dispatcher;
230 $caller->dispatcher($dispatcher);
231 $caller->log->debug(qq/Loaded dispatcher "$dispatcher"/) if $caller->debug;
234 $engine = "Catalyst::Engine::$ENV{CATALYST_ENGINE}"
235 if $ENV{CATALYST_ENGINE};
236 my $appeng = $ENV{ uc($caller) . '_ENGINE' };
237 $engine = "Catalyst::Engine::$appeng" if $appeng;
240 die qq/Couldn't load engine "$engine", "$@"/ if $@;
243 push @{"$caller\::ISA"}, $engine;
245 $caller->engine($engine);
246 $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
250 $name =~ s/\:\:/\//g;
252 if ( my $path = $INC{"$name.pm"} ) {
253 $home = file($path)->absolute->dir;
256 my $subdir = dir($home)->subdir($append);
257 for ( split '/', $name ) { $home = dir($home)->parent }
258 if ( $home =~ /blib$/ ) { $home = dir($home)->parent }
259 elsif ( !-f file( $home, 'Makefile.PL' ) ) { $home = $subdir }
262 if ( $caller->debug ) {
265 ? $caller->log->debug(qq/Found home "$home"/)
266 : $caller->log->debug(qq/Home "$home" doesn't exist/)
267 : $caller->log->debug(q/Couldn't find home/);
269 $caller->config->{home} = $home || '';
270 $caller->config->{root} = defined $home ? dir($home)->subdir('root') : '';
275 Contains the engine class.
279 Contains the logging object. Unless it is already set Catalyst sets this up with a
280 C<Catalyst::Log> object. To use your own log class:
282 $c->log( MyLogger->new );
283 $c->log->info("now logging with my own logger!");
285 Your log class should implement the methods described in the C<Catalyst::Log>
288 =item $c->plugin( $name, $class, @args )
290 Instant plugins for Catalyst.
291 Classdata accessor/mutator will be created, class loaded and instantiated.
293 MyApp->plugin( 'prototype', 'HTML::Prototype' );
295 $c->prototype->define_javascript_functions;
300 my ( $class, $name, $plugin, @args ) = @_;
302 my $error = $UNIVERSAL::require::ERROR;
303 die qq/Couldn't load instant plugin "$plugin", "$error"/ if $error;
304 eval { $plugin->import };
305 $class->mk_classdata($name);
307 eval { $obj = $plugin->new(@args) };
308 die qq/Couldn't instantiate instant plugin "$plugin", "$@"/ if $@;
310 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
318 mod_perl2 support is considered experimental and may contain bugs.
324 Join #catalyst on irc.perl.org.
328 http://lists.rawmode.org/mailman/listinfo/catalyst
329 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
333 http://catalyst.perl.org
339 =item L<Catalyst::Manual> - The Catalyst Manual
341 =item L<Catalyst::Engine> - Core Engine
343 =item L<Catalyst::Log> - The Log Class.
345 =item L<Catalyst::Request> - The Request Object
347 =item L<Catalyst::Response> - The Response Object
349 =item L<Catalyst::Test> - The test suite.
355 Sebastian Riedel, C<sri@oook.de>
359 Andy Grundman, Andrew Ford, Andrew Ruthven, Autrijus Tang, Christian Hansen,
360 Christopher Hicks, Dan Sully, Danijel Milicevic, David Naughton,
361 Gary Ashton Jones, Geoff Richards, Jesse Sheidlower, Jody Belka,
362 Johan Lindstrom, Leon Brocard, Marcus Ramberg, Tatsuhiko Miyagawa
363 and all the others who've helped.
367 This library is free software . You can redistribute it and/or modify it under
368 the same terms as perl itself.