lib/Catalyst.pm

   1 package Catalyst;
   2
   3 use strict;
   4 use base 'Class::Data::Inheritable';
   5 use UNIVERSAL::require;
   6 use Catalyst::Log;
   7
   8 __PACKAGE__->mk_classdata($_) for qw/_config log/;
   9
  10 our $VERSION = '4.28';
  11 our @ISA;
  12
  13 =head1 NAME
  14
  15 Catalyst - The Elegant MVC Web Application Framework
  16
  17 =head1 SYNOPSIS
  18
  19     # use the helper to start a new application
  20     catalyst.pl MyApp
  21     cd MyApp
  22
  23     # add models, views, controllers
  24     script/create.pl model Something
  25     script/create.pl view Stuff
  26     script/create.pl controller Yada
  27
  28     # built in testserver
  29     script/server.pl
  30
  31     # command line interface
  32     script/test.pl /yada
  33
  34
  35     use Catalyst;
  36
  37     use Catalyst qw/My::Module My::OtherModule/;
  38
  39     use Catalyst '-Debug';
  40
  41     use Catalyst qw/-Debug -Engine=CGI/;
  42
  43     __PACKAGE__->action( '!default' => sub { $_[1]->res->output('Hello') } );
  44
  45     __PACKAGE__->action(
  46         'index.html' => sub {
  47             my ( $self, $c ) = @_;
  48             $c->res->output('Hello');
  49             $c->forward('_foo');
  50         }
  51     );
  52
  53     __PACKAGE__->action(
  54         '/^product[_]*(\d*).html$/' => sub {
  55             my ( $self, $c ) = @_;
  56             $c->stash->{template} = 'product.tt';
  57             $c->stash->{product} = $c->req->snippets->[0];
  58         }
  59     );
  60
  61 See also L<Catalyst::Manual::Intro>
  62
  63 =head1 DESCRIPTION
  64
  65 Catalyst is based upon L<Maypole>, which you should consider for smaller
  66 projects.
  67
  68 The key concept of Catalyst is DRY (Don't Repeat Yourself).
  69
  70 See L<Catalyst::Manual> for more documentation.
  71
  72 Omit the Catalyst::Plugin:: prefix from plugins.
  73 So Catalyst::Plugin::My::Module becomes My::Module.
  74
  75     use Catalyst 'My::Module';
  76
  77 You can also set special flags like -Debug and -Engine.
  78
  79     use Catalyst qw/-Debug My::Module/;
  80
  81 The position of plugins and flags in the chain is important,
  82 because they are loaded in the same order they appear.
  83
  84 =head2 -Debug
  85
  86     use Catalyst '-Debug';
  87
  88 is equivalent to
  89
  90     use Catalyst;
  91     sub debug { 1 }
  92
  93 =head2 -Engine
  94
  95 Force Catalyst to use a specific engine.
  96 Omit the Catalyst::Engine:: prefix.
  97
  98     use Catalyst '-Engine=CGI';
  99
 100 =head2 METHODS
 101
 102 =head3 debug
 103
 104 Overload to enable debug messages.
 105
 106 =cut
 107
 108 sub debug { 0 }
 109
 110 =head3 config
 111
 112 Returns a hashref containing your applications settings.
 113
 114 =cut
 115
 116 sub config {
 117     my $self = shift;
 118     $self->_config( {} ) unless $self->_config;
 119     if ( $_[0] ) {
 120         my $config = $_[1] ? {@_} : $_[0];
 121         while ( my ( $key, $val ) = each %$config ) {
 122             $self->_config->{$key} = $val;
 123         }
 124     }
 125     return $self->_config;
 126 }
 127
 128 sub import {
 129     my ( $self, @options ) = @_;
 130     my $caller = caller(0);
 131
 132     # Class
 133     {
 134         no strict 'refs';
 135         *{"$caller\::handler"} =
 136           sub { Catalyst::Engine::handler( $caller, @_ ) };
 137         push @{"$caller\::ISA"}, $self;
 138     }
 139     $self->log( Catalyst::Log->new );
 140
 141     # Options
 142     my $engine =
 143       $ENV{MOD_PERL} ? 'Catalyst::Engine::Apache' : 'Catalyst::Engine::CGI';
 144     foreach (@options) {
 145         if (/^\-Debug$/) {
 146             no warnings;
 147             no strict 'refs';
 148             *{"$self\::debug"} = sub { 1 };
 149             $caller->log->debug('Debug messages enabled');
 150         }
 151         elsif (/^-Engine=(.*)$/) { $engine = "Catalyst::Engine::$1" }
 152         elsif (/^-.*$/) { $caller->log->error(qq/Unknown flag "$_"/) }
 153         else {
 154             my $plugin = "Catalyst::Plugin::$_";
 155
 156             # Plugin caller should be our application class
 157             eval "package $caller; require $plugin";
 158             if ($@) {
 159                 $caller->log->error(qq/Couldn't load plugin "$plugin", "$@"/);
 160             }
 161             else {
 162                 $caller->log->debug(qq/Loaded plugin "$plugin"/)
 163                   if $caller->debug;
 164                 no strict 'refs';
 165                 push @{"$caller\::ISA"}, $plugin;
 166             }
 167         }
 168     }
 169
 170     # Engine
 171     $engine = "Catalyst::Engine::$ENV{CATALYST_ENGINE}"
 172       if $ENV{CATALYST_ENGINE};
 173     $engine->require;
 174     die qq/Couldn't load engine "$engine", "$@"/ if $@;
 175     {
 176         no strict 'refs';
 177         push @{"$caller\::ISA"}, $engine;
 178     }
 179     $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
 180 }
 181
 182 =head1 SUPPORT
 183
 184 IRC:
 185
 186     Join #catalyst on irc.perl.org.
 187
 188 Mailing-Lists:
 189
 190     http://lists.rawmode.org/mailman/listinfo/catalyst
 191     http://lists.rawmode.org/mailman/listinfo/catalyst-dev
 192
 193 =head1 SEE ALSO
 194
 195 L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
 196 L<Catalyst::Response>, L<Catalyst::Engine>
 197
 198 =head1 AUTHOR
 199
 200 Sebastian Riedel, C<sri@oook.de>
 201
 202 =head1 THANK YOU
 203
 204 Andrew Ruthven, Christian Hansen, Christopher Hicks, Danijel Milicevic,
 205 David Naughton, Gary Ashton Jones, Jesse Sheidlower, Johan Lindstrom,
 206 Marcus Ramberg, Tatsuhiko Miyagawa and all the others who've helped.
 207
 208 =head1 LICENSE
 209
 210 This library is free software . You can redistribute it and/or modify it under
 211 the same terms as perl itself.
 212
 213 =cut
 214
 215 1;