Added recursive -r flag to prove example
[catagits/Catalyst-Runtime.git] / lib / Catalyst.pm
CommitLineData
fc7ec1d9 1package Catalyst;
2
3use strict;
5d9a6d47 4use base qw[ Catalyst::Base Catalyst::Setup ];
fc7ec1d9 5use UNIVERSAL::require;
a2f2cde9 6use Catalyst::Exception;
fc7ec1d9 7use Catalyst::Log;
812a28c9 8use Catalyst::Utils;
5d9a6d47 9use NEXT;
4f6748f1 10use Path::Class;
367d15f8 11our $CATALYST_SCRIPT_GEN = 4;
fc7ec1d9 12
10dd6896 13__PACKAGE__->mk_classdata($_) for qw/arguments dispatcher engine log/;
14
fd59198f 15our $VERSION = '5.34';
fc7ec1d9 16our @ISA;
17
18=head1 NAME
19
20Catalyst - The Elegant MVC Web Application Framework
21
22=head1 SYNOPSIS
23
24 # use the helper to start a new application
91864987 25 catalyst.pl MyApp
fc7ec1d9 26 cd MyApp
27
28 # add models, views, controllers
ae4e40a7 29 script/myapp_create.pl model Something
30 script/myapp_create.pl view Stuff
31 script/myapp_create.pl controller Yada
fc7ec1d9 32
33 # built in testserver
ae4e40a7 34 script/myapp_server.pl
fc7ec1d9 35
36 # command line interface
ae4e40a7 37 script/myapp_test.pl /yada
fc7ec1d9 38
39
fc7ec1d9 40 use Catalyst;
41
42 use Catalyst qw/My::Module My::OtherModule/;
43
44 use Catalyst '-Debug';
45
46 use Catalyst qw/-Debug -Engine=CGI/;
47
5a8ed4fe 48 sub default : Private { $_[1]->res->output('Hello') } );
49
e3dc9d78 50 sub index : Path('/index.html') {
5a8ed4fe 51 my ( $self, $c ) = @_;
52 $c->res->output('Hello');
064834ea 53 $c->forward('foo');
5a8ed4fe 54 }
55
064834ea 56 sub product : Regex('^product[_]*(\d*).html$') {
5a8ed4fe 57 my ( $self, $c ) = @_;
58 $c->stash->{template} = 'product.tt';
59 $c->stash->{product} = $c->req->snippets->[0];
60 }
fc7ec1d9 61
3803e98f 62See also L<Catalyst::Manual::Intro>
63
fc7ec1d9 64=head1 DESCRIPTION
65
fc7ec1d9 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 {
0319a12c 127 my ( $class, @arguments ) = @_;
953b0e15 128
129 # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
130 # callers @ISA.
599b5295 131 return unless $class eq 'Catalyst';
132
fc7ec1d9 133 my $caller = caller(0);
953b0e15 134
135 unless ( $caller->isa('Catalyst') ) {
fc7ec1d9 136 no strict 'refs';
0319a12c 137 push @{"$caller\::ISA"}, $class;
1c99e125 138 }
0319a12c 139
10dd6896 140 $caller->arguments( [ @arguments ] );
141 $caller->setup_home;
0319a12c 142}
143
144=item $c->engine
145
146Contains the engine class.
fc7ec1d9 147
0319a12c 148=item $c->log
149
150Contains the logging object. Unless it is already set Catalyst sets this up with a
151C<Catalyst::Log> object. To use your own log class:
152
153 $c->log( MyLogger->new );
154 $c->log->info("now logging with my own logger!");
155
156Your log class should implement the methods described in the C<Catalyst::Log>
157man page.
158
159=item $c->plugin( $name, $class, @args )
160
161Instant plugins for Catalyst.
162Classdata accessor/mutator will be created, class loaded and instantiated.
163
164 MyApp->plugin( 'prototype', 'HTML::Prototype' );
165
166 $c->prototype->define_javascript_functions;
167
168=cut
169
170sub plugin {
171 my ( $class, $name, $plugin, @args ) = @_;
172 $plugin->require;
173
174 if ( my $error = $UNIVERSAL::require::ERROR ) {
175 Catalyst::Exception->throw(
176 message => qq/Couldn't load instant plugin "$plugin", "$error"/
177 );
178 }
179
180 eval { $plugin->import };
181 $class->mk_classdata($name);
182 my $obj;
183 eval { $obj = $plugin->new(@args) };
184
185 if ( $@ ) {
186 Catalyst::Exception->throw(
187 message => qq/Couldn't instantiate instant plugin "$plugin", "$@"/
188 );
189 }
190
191 $class->$name($obj);
192 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
193 if $class->debug;
194}
195
23f9d934 196=back
197
d2ee9760 198=head1 CASE SENSITIVITY
199
200By default Catalyst is not case sensitive, so C<MyApp::C::FOO::Bar> becomes
201C</foo/bar>.
202
203But you can activate case sensitivity with a config parameter.
204
205 MyApp->config->{case_sensitive} = 1;
206
d1a31ac6 207=head1 LIMITATIONS
208
b2b7d352 209mod_perl2 support is considered experimental and may contain bugs.
d1a31ac6 210
3cb1db8c 211=head1 SUPPORT
212
213IRC:
214
215 Join #catalyst on irc.perl.org.
216
217Mailing-Lists:
218
219 http://lists.rawmode.org/mailman/listinfo/catalyst
220 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
1985c30b 221
432d507d 222Web:
223
224 http://catalyst.perl.org
225
fc7ec1d9 226=head1 SEE ALSO
227
61b1e958 228=over 4
229
230=item L<Catalyst::Manual> - The Catalyst Manual
231
232=item L<Catalyst::Engine> - Core Engine
233
234=item L<Catalyst::Log> - The Log Class.
235
236=item L<Catalyst::Request> - The Request Object
237
238=item L<Catalyst::Response> - The Response Object
239
240=item L<Catalyst::Test> - The test suite.
241
242=back
fc7ec1d9 243
15f0b5b7 244=head1 CREDITS
fc7ec1d9 245
15f0b5b7 246Andy Grundman
247
248Andrew Ford
249
250Andrew Ruthven
251
252Autrijus Tang
253
254Christian Hansen
255
256Christopher Hicks
257
258Dan Sully
259
260Danijel Milicevic
261
262David Naughton
263
264Gary Ashton Jones
265
266Geoff Richards
267
268Jesse Sheidlower
269
270Jody Belka
271
272Johan Lindstrom
273
274Juan Camacho
275
276Leon Brocard
277
278Marcus Ramberg
279
280Matt S Trout
281
71c3bcc3 282Robert Sedlacek
283
51f0308d 284Sebastian Riedel
285
15f0b5b7 286Tatsuhiko Miyagawa
fc7ec1d9 287
51f0308d 288Ulf Edvinsson
289
290=head1 AUTHOR
291
292Sebastian Riedel, C<sri@oook.de>
293
fc7ec1d9 294=head1 LICENSE
295
296This library is free software . You can redistribute it and/or modify it under
297the same terms as perl itself.
298
299=cut
300
3011;