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 Text::ASCIITable;
  11 use Path::Class;
  12 our $CATALYST_SCRIPT_GEN = 4;
  13
  14 __PACKAGE__->mk_classdata($_) for qw/arguments dispatcher engine log/;
  15
  16 our $VERSION = '5.24';
  17 our @ISA;
  18
  19 =head1 NAME
  20
  21 Catalyst - The Elegant MVC Web Application Framework
  22
  23 =head1 SYNOPSIS
  24
  25     # use the helper to start a new application
  26     catalyst.pl MyApp
  27     cd MyApp
  28
  29     # add models, views, controllers
  30     script/myapp_create.pl model Something
  31     script/myapp_create.pl view Stuff
  32     script/myapp_create.pl controller Yada
  33
  34     # built in testserver
  35     script/myapp_server.pl
  36
  37     # command line interface
  38     script/myapp_test.pl /yada
  39
  40
  41     use Catalyst;
  42
  43     use Catalyst qw/My::Module My::OtherModule/;
  44
  45     use Catalyst '-Debug';
  46
  47     use Catalyst qw/-Debug -Engine=CGI/;
  48
  49     sub default : Private { $_[1]->res->output('Hello') } );
  50
  51     sub index : Path('/index.html') {
  52         my ( $self, $c ) = @_;
  53         $c->res->output('Hello');
  54         $c->forward('foo');
  55     }
  56
  57     sub product : Regex('^product[_]*(\d*).html$') {
  58         my ( $self, $c ) = @_;
  59         $c->stash->{template} = 'product.tt';
  60         $c->stash->{product} = $c->req->snippets->[0];
  61     }
  62
  63 See also L<Catalyst::Manual::Intro>
  64
  65 =head1 DESCRIPTION
  66
  67 The key concept of Catalyst is DRY (Don't Repeat Yourself).
  68
  69 See L<Catalyst::Manual> for more documentation.
  70
  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>.
  74
  75     use Catalyst 'My::Module';
  76
  77 Special flags like -Debug and -Engine can also be specifed as arguments when
  78 Catalyst is loaded:
  79
  80     use Catalyst qw/-Debug My::Module/;
  81
  82 The position of plugins and flags in the chain is important, because they are
  83 loaded in exactly the order that they appear.
  84
  85 The following flags are supported:
  86
  87 =over 4
  88
  89 =item -Debug
  90
  91 enables debug output, i.e.:
  92
  93     use Catalyst '-Debug';
  94
  95 this is equivalent to:
  96
  97     use Catalyst;
  98     sub debug { 1 }
  99
 100 =item -Engine
 101
 102 Force Catalyst to use a specific engine.
 103 Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
 104
 105     use Catalyst '-Engine=CGI';
 106
 107 =back
 108
 109 =head1 METHODS
 110
 111 =over 4
 112
 113 =item debug
 114
 115 Overload to enable debug messages.
 116
 117 =cut
 118
 119 sub debug { 0 }
 120
 121 =item config
 122
 123 Returns a hashref containing your applications settings.
 124
 125 =cut
 126
 127 sub import {
 128     my ( $class, @arguments ) = @_;
 129
 130     return unless $class eq 'Catalyst';
 131
 132     my $caller = caller(0);
 133
 134     # Prepare inheritance
 135     unless ( $caller->isa($class) ) {
 136
 137         no strict 'refs';
 138         push @{"$caller\::ISA"}, $class;
 139
 140     }
 141
 142     $caller->arguments( [ @arguments ] );
 143     $caller->setup_home;
 144 }
 145
 146 =item $c->engine
 147
 148 Contains the engine class.
 149
 150 =item $c->log
 151
 152 Contains the logging object.  Unless it is already set Catalyst sets this up with a
 153 C<Catalyst::Log> object.  To use your own log class:
 154
 155     $c->log( MyLogger->new );
 156     $c->log->info("now logging with my own logger!");
 157
 158 Your log class should implement the methods described in the C<Catalyst::Log>
 159 man page.
 160
 161 =item $c->plugin( $name, $class, @args )
 162
 163 Instant plugins for Catalyst.
 164 Classdata accessor/mutator will be created, class loaded and instantiated.
 165
 166     MyApp->plugin( 'prototype', 'HTML::Prototype' );
 167
 168     $c->prototype->define_javascript_functions;
 169
 170 =cut
 171
 172 sub plugin {
 173     my ( $class, $name, $plugin, @args ) = @_;
 174     $plugin->require;
 175
 176     if ( my $error = $UNIVERSAL::require::ERROR ) {
 177         Catalyst::Exception->throw(
 178             message => qq/Couldn't load instant plugin "$plugin", "$error"/
 179         );
 180     }
 181
 182     eval { $plugin->import };
 183     $class->mk_classdata($name);
 184     my $obj;
 185     eval { $obj = $plugin->new(@args) };
 186
 187     if ( $@ ) {
 188         Catalyst::Exception->throw(
 189             message => qq/Couldn't instantiate instant plugin "$plugin", "$@"/
 190         );
 191     }
 192
 193     $class->$name($obj);
 194     $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
 195       if $class->debug;
 196 }
 197
 198 =back
 199
 200 =head1 CASE SENSITIVITY
 201
 202 By default Catalyst is not case sensitive, so C<MyApp::C::FOO::Bar> becomes
 203 C</foo/bar>.
 204
 205 But you can activate case sensitivity with a config parameter.
 206
 207     MyApp->config->{case_sensitive} = 1;
 208
 209 =head1 LIMITATIONS
 210
 211 mod_perl2 support is considered experimental and may contain bugs.
 212
 213 =head1 SUPPORT
 214
 215 IRC:
 216
 217     Join #catalyst on irc.perl.org.
 218
 219 Mailing-Lists:
 220
 221     http://lists.rawmode.org/mailman/listinfo/catalyst
 222     http://lists.rawmode.org/mailman/listinfo/catalyst-dev
 223
 224 Web:
 225
 226     http://catalyst.perl.org
 227
 228 =head1 SEE ALSO
 229
 230 =over 4
 231
 232 =item L<Catalyst::Manual> - The Catalyst Manual
 233
 234 =item L<Catalyst::Engine> - Core Engine
 235
 236 =item L<Catalyst::Log> - The Log Class.
 237
 238 =item L<Catalyst::Request> - The Request Object
 239
 240 =item L<Catalyst::Response> - The Response Object
 241
 242 =item L<Catalyst::Test> - The test suite.
 243
 244 =back
 245
 246 =head1 AUTHOR
 247
 248 Sebastian Riedel, C<sri@oook.de>
 249
 250 =head1 THANK YOU
 251
 252 Andy Grundman, Andrew Ford, Andrew Ruthven, Autrijus Tang, Christian Hansen,
 253 Christopher Hicks, Dan Sully, Danijel Milicevic, David Naughton,
 254 Gary Ashton Jones, Geoff Richards, Jesse Sheidlower, Jody Belka,
 255 Johan Lindstrom, Juan Camacho, Leon Brocard, Marcus Ramberg,
 256 Tatsuhiko Miyagawa and all the others who've helped.
 257
 258 =head1 LICENSE
 259
 260 This library is free software . You can redistribute it and/or modify it under
 261 the same terms as perl itself.
 262
 263 =cut
 264
 265 1;