lib/Catalyst.pm

   1 package Catalyst;
   2
   3 use strict;
   4 use base qw[ Catalyst::Base Catalyst::Setup ];
   5 use UNIVERSAL::require;
   6 use Catalyst::Exception;
   7 use Catalyst::Log;
   8 use Catalyst::Utils;
   9 use NEXT;
  10 use Path::Class;
  11 our $CATALYST_SCRIPT_GEN = 4;
  12
  13 __PACKAGE__->mk_classdata($_) for qw/arguments dispatcher engine log/;
  14
  15 our $VERSION = '5.34';
  16 our @ISA;
  17
  18 =head1 NAME
  19
  20 Catalyst - The Elegant MVC Web Application Framework
  21
  22 =head1 SYNOPSIS
  23
  24     # use the helper to start a new application
  25     catalyst.pl MyApp
  26     cd MyApp
  27
  28     # add models, views, controllers
  29     script/myapp_create.pl model Something
  30     script/myapp_create.pl view Stuff
  31     script/myapp_create.pl controller Yada
  32
  33     # built in testserver
  34     script/myapp_server.pl
  35
  36     # command line interface
  37     script/myapp_test.pl /yada
  38
  39
  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
  48     sub default : Private { $_[1]->res->output('Hello') } );
  49
  50     sub index : Path('/index.html') {
  51         my ( $self, $c ) = @_;
  52         $c->res->output('Hello');
  53         $c->forward('foo');
  54     }
  55
  56     sub product : Regex('^product[_]*(\d*).html$') {
  57         my ( $self, $c ) = @_;
  58         $c->stash->{template} = 'product.tt';
  59         $c->stash->{product} = $c->req->snippets->[0];
  60     }
  61
  62 See also L<Catalyst::Manual::Intro>
  63
  64 =head1 DESCRIPTION
  65
  66 The key concept of Catalyst is DRY (Don't Repeat Yourself).
  67
  68 See L<Catalyst::Manual> for more documentation.
  69
  70 Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
  71 Omit the C<Catalyst::Plugin::> prefix from the plugin name,
  72 so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
  73
  74     use Catalyst 'My::Module';
  75
  76 Special flags like -Debug and -Engine can also be specifed as arguments when
  77 Catalyst is loaded:
  78
  79     use Catalyst qw/-Debug My::Module/;
  80
  81 The position of plugins and flags in the chain is important, because they are
  82 loaded in exactly the order that they appear.
  83
  84 The following flags are supported:
  85
  86 =over 4
  87
  88 =item -Debug
  89
  90 enables debug output, i.e.:
  91
  92     use Catalyst '-Debug';
  93
  94 this is equivalent to:
  95
  96     use Catalyst;
  97     sub debug { 1 }
  98
  99 =item -Engine
 100
 101 Force Catalyst to use a specific engine.
 102 Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
 103
 104     use Catalyst '-Engine=CGI';
 105
 106 =back
 107
 108 =head1 METHODS
 109
 110 =over 4
 111
 112 =item debug
 113
 114 Overload to enable debug messages.
 115
 116 =cut
 117
 118 sub debug { 0 }
 119
 120 =item config
 121
 122 Returns a hashref containing your applications settings.
 123
 124 =cut
 125
 126 sub import {
 127     my ( $class, @arguments ) = @_;
 128
 129     # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
 130     # callers @ISA.
 131     return unless $class eq 'Catalyst';
 132
 133     my $caller = caller(0);
 134
 135     unless ( $caller->isa('Catalyst') ) {
 136         no strict 'refs';
 137         push @{"$caller\::ISA"}, $class;
 138     }
 139
 140     $caller->arguments( [ @arguments ] );
 141     $caller->setup_home;
 142 }
 143
 144 =item $c->engine
 145
 146 Contains the engine class.
 147
 148 =item $c->log
 149
 150 Contains the logging object.  Unless it is already set Catalyst sets this up with a
 151 C<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
 156 Your log class should implement the methods described in the C<Catalyst::Log>
 157 man page.
 158
 159 =item $c->plugin( $name, $class, @args )
 160
 161 Instant plugins for Catalyst.
 162 Classdata 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
 170 sub 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
 196 =back
 197
 198 =head1 CASE SENSITIVITY
 199
 200 By default Catalyst is not case sensitive, so C<MyApp::C::FOO::Bar> becomes
 201 C</foo/bar>.
 202
 203 But you can activate case sensitivity with a config parameter.
 204
 205     MyApp->config->{case_sensitive} = 1;
 206
 207 =head1 LIMITATIONS
 208
 209 mod_perl2 support is considered experimental and may contain bugs.
 210
 211 =head1 SUPPORT
 212
 213 IRC:
 214
 215     Join #catalyst on irc.perl.org.
 216
 217 Mailing-Lists:
 218
 219     http://lists.rawmode.org/mailman/listinfo/catalyst
 220     http://lists.rawmode.org/mailman/listinfo/catalyst-dev
 221
 222 Web:
 223
 224     http://catalyst.perl.org
 225
 226 =head1 SEE ALSO
 227
 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
 243
 244 =head1 CREDITS
 245
 246 Andy Grundman
 247
 248 Andrew Ford
 249
 250 Andrew Ruthven
 251
 252 Autrijus Tang
 253
 254 Christian Hansen
 255
 256 Christopher Hicks
 257
 258 Dan Sully
 259
 260 Danijel Milicevic
 261
 262 David Naughton
 263
 264 Gary Ashton Jones
 265
 266 Geoff Richards
 267
 268 Jesse Sheidlower
 269
 270 Jody Belka
 271
 272 Johan Lindstrom
 273
 274 Juan Camacho
 275
 276 Leon Brocard
 277
 278 Marcus Ramberg
 279
 280 Matt S Trout
 281
 282 Robert Sedlacek
 283
 284 Sebastian Riedel
 285
 286 Tatsuhiko Miyagawa
 287
 288 Ulf Edvinsson
 289
 290 =head1 AUTHOR
 291
 292 Sebastian Riedel, C<sri@oook.de>
 293
 294 =head1 LICENSE
 295
 296 This library is free software . You can redistribute it and/or modify it under
 297 the same terms as perl itself.
 298
 299 =cut
 300
 301 1;