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.24';
  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                 unshift @ISA, $plugin;
 165             }
 166         }
 167     }
 168
 169     # Engine
 170     $engine = "Catalyst::Engine::$ENV{CATALYST_ENGINE}"
 171       if $ENV{CATALYST_ENGINE};
 172     $engine->require;
 173     die qq/Couldn't load engine "$engine", "$@"/ if $@;
 174     push @ISA, $engine;
 175     $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
 176 }
 177
 178 =head1 SUPPORT
 179
 180 IRC:
 181
 182     Join #catalyst on irc.perl.org.
 183
 184 Mailing-Lists:
 185
 186     http://lists.rawmode.org/mailman/listinfo/catalyst
 187     http://lists.rawmode.org/mailman/listinfo/catalyst-dev
 188
 189 =head1 SEE ALSO
 190
 191 L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
 192 L<Catalyst::Response>, L<Catalyst::Engine>
 193
 194 =head1 AUTHOR
 195
 196 Sebastian Riedel, C<sri@oook.de>
 197
 198 =head1 THANK YOU
 199
 200 Andrew Ruthven, Danijel Milicevic, David Naughton, Gary Ashton Jones,
 201 Jesse Sheidlower, Johan Lindstrom, Marcus Ramberg and all the others
 202 who've helped.
 203
 204 =head1 LICENSE
 205
 206 This library is free software . You can redistribute it and/or modify it under
 207 the same terms as perl itself.
 208
 209 =cut
 210
 211 1;