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     my $caller = caller(0);
 131
 132     # Prepare inheritance
 133     unless ( $caller->isa($class) ) {
 134
 135         no strict 'refs';
 136         push @{"$caller\::ISA"}, $class;
 137
 138         *{"$caller\::import"} = sub { 1 };
 139     }
 140
 141     $caller->arguments( [ @arguments ] );
 142     $caller->setup_home;
 143 }
 144
 145 =item $c->engine
 146
 147 Contains the engine class.
 148
 149 =item $c->log
 150
 151 Contains the logging object.  Unless it is already set Catalyst sets this up with a
 152 C<Catalyst::Log> object.  To use your own log class:
 153
 154     $c->log( MyLogger->new );
 155     $c->log->info("now logging with my own logger!");
 156
 157 Your log class should implement the methods described in the C<Catalyst::Log>
 158 man page.
 159
 160 =item $c->plugin( $name, $class, @args )
 161
 162 Instant plugins for Catalyst.
 163 Classdata accessor/mutator will be created, class loaded and instantiated.
 164
 165     MyApp->plugin( 'prototype', 'HTML::Prototype' );
 166
 167     $c->prototype->define_javascript_functions;
 168
 169 =cut
 170
 171 sub plugin {
 172     my ( $class, $name, $plugin, @args ) = @_;
 173     $plugin->require;
 174
 175     if ( my $error = $UNIVERSAL::require::ERROR ) {
 176         Catalyst::Exception->throw(
 177             message => qq/Couldn't load instant plugin "$plugin", "$error"/
 178         );
 179     }
 180
 181     eval { $plugin->import };
 182     $class->mk_classdata($name);
 183     my $obj;
 184     eval { $obj = $plugin->new(@args) };
 185
 186     if ( $@ ) {
 187         Catalyst::Exception->throw(
 188             message => qq/Couldn't instantiate instant plugin "$plugin", "$@"/
 189         );
 190     }
 191
 192     $class->$name($obj);
 193     $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
 194       if $class->debug;
 195 }
 196
 197 =back
 198
 199 =head1 LIMITATIONS
 200
 201 mod_perl2 support is considered experimental and may contain bugs.
 202
 203 =head1 SUPPORT
 204
 205 IRC:
 206
 207     Join #catalyst on irc.perl.org.
 208
 209 Mailing-Lists:
 210
 211     http://lists.rawmode.org/mailman/listinfo/catalyst
 212     http://lists.rawmode.org/mailman/listinfo/catalyst-dev
 213
 214 Web:
 215
 216     http://catalyst.perl.org
 217
 218 =head1 SEE ALSO
 219
 220 =over 4
 221
 222 =item L<Catalyst::Manual> - The Catalyst Manual
 223
 224 =item L<Catalyst::Engine> - Core Engine
 225
 226 =item L<Catalyst::Log> - The Log Class.
 227
 228 =item L<Catalyst::Request> - The Request Object
 229
 230 =item L<Catalyst::Response> - The Response Object
 231
 232 =item L<Catalyst::Test> - The test suite.
 233
 234 =back
 235
 236 =head1 AUTHOR
 237
 238 Sebastian Riedel, C<sri@oook.de>
 239
 240 =head1 THANK YOU
 241
 242 Andy Grundman, Andrew Ford, Andrew Ruthven, Autrijus Tang, Christian Hansen,
 243 Christopher Hicks, Dan Sully, Danijel Milicevic, David Naughton,
 244 Gary Ashton Jones, Geoff Richards, Jesse Sheidlower, Jody Belka,
 245 Johan Lindstrom, Juan Camacho, Leon Brocard, Marcus Ramberg,
 246 Tatsuhiko Miyagawa and all the others who've helped.
 247
 248 =head1 LICENSE
 249
 250 This library is free software . You can redistribute it and/or modify it under
 251 the same terms as perl itself.
 252
 253 =cut
 254
 255 1;