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.23';
  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     See also L<Catalyst::Manual::Intro>
  36
  37
  38     use Catalyst;
  39
  40     use Catalyst qw/My::Module My::OtherModule/;
  41
  42     use Catalyst '-Debug';
  43
  44     use Catalyst qw/-Debug -Engine=CGI/;
  45
  46     __PACKAGE__->action( '!default' => sub { $_[1]->res->output('Hello') } );
  47
  48     __PACKAGE__->action(
  49         'index.html' => sub {
  50             my ( $self, $c ) = @_;
  51             $c->res->output('Hello');
  52             $c->forward('_foo');
  53         }
  54     );
  55
  56     __PACKAGE__->action(
  57         '/^product[_]*(\d*).html$/' => sub {
  58             my ( $self, $c ) = @_;
  59             $c->stash->{template} = 'product.tt';
  60             $c->stash->{product} = $c->req->snippets->[0];
  61         }
  62     );
  63
  64 =head1 DESCRIPTION
  65
  66 Catalyst is based upon L<Maypole>, which you should consider for smaller
  67 projects.
  68
  69 The key concept of Catalyst is DRY (Don't Repeat Yourself).
  70
  71 See L<Catalyst::Manual> for more documentation.
  72
  73 Omit the Catalyst::Plugin:: prefix from plugins.
  74 So Catalyst::Plugin::My::Module becomes My::Module.
  75
  76     use Catalyst 'My::Module';
  77
  78 You can also set special flags like -Debug and -Engine.
  79
  80     use Catalyst qw/-Debug My::Module/;
  81
  82 The position of plugins and flags in the chain is important,
  83 because they are loaded in the same order they appear.
  84
  85 =head2 -Debug
  86
  87     use Catalyst '-Debug';
  88
  89 is equivalent to
  90
  91     use Catalyst;
  92     sub debug { 1 }
  93
  94 =head2 -Engine
  95
  96 Force Catalyst to use a specific engine.
  97 Omit the Catalyst::Engine:: prefix.
  98
  99     use Catalyst '-Engine=CGI';
 100
 101 =head2 METHODS
 102
 103 =head3 debug
 104
 105 Overload to enable debug messages.
 106
 107 =cut
 108
 109 sub debug { 0 }
 110
 111 =head3 config
 112
 113 Returns a hashref containing your applications settings.
 114
 115 =cut
 116
 117 sub config {
 118     my $self = shift;
 119     $self->_config( {} ) unless $self->_config;
 120     if ( $_[0] ) {
 121         my $config = $_[1] ? {@_} : $_[0];
 122         while ( my ( $key, $val ) = each %$config ) {
 123             $self->_config->{$key} = $val;
 124         }
 125     }
 126     return $self->_config;
 127 }
 128
 129 sub import {
 130     my ( $self, @options ) = @_;
 131     my $caller = caller(0);
 132
 133     # Class
 134     {
 135         no strict 'refs';
 136         *{"$caller\::handler"} =
 137           sub { Catalyst::Engine::handler( $caller, @_ ) };
 138         push @{"$caller\::ISA"}, $self;
 139     }
 140     $self->log( Catalyst::Log->new );
 141
 142     # Options
 143     my $engine =
 144       $ENV{MOD_PERL} ? 'Catalyst::Engine::Apache' : 'Catalyst::Engine::CGI';
 145     foreach (@options) {
 146         if (/^\-Debug$/) {
 147             no warnings;
 148             no strict 'refs';
 149             *{"$self\::debug"} = sub { 1 };
 150             $caller->log->debug('Debug messages enabled');
 151         }
 152         elsif (/^-Engine=(.*)$/) { $engine = "Catalyst::Engine::$1" }
 153         elsif (/^-.*$/) { $caller->log->error(qq/Unknown flag "$_"/) }
 154         else {
 155             my $plugin = "Catalyst::Plugin::$_";
 156
 157             # Plugin caller should be our application class
 158             eval "package $caller; require $plugin";
 159             if ($@) {
 160                 $caller->log->error(qq/Couldn't load plugin "$plugin", "$@"/);
 161             }
 162             else {
 163                 $caller->log->debug(qq/Loaded plugin "$plugin"/)
 164                   if $caller->debug;
 165                 unshift @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     push @ISA, $engine;
 176     $caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
 177 }
 178
 179 =head1 SEE ALSO
 180
 181 L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
 182 L<Catalyst::Response>, L<Catalyst::Engine>
 183
 184 =head1 AUTHOR
 185
 186 Sebastian Riedel, C<sri@oook.de>
 187
 188 =head1 THANK YOU
 189
 190 Danijel Milicevic, David Naughton, Gary Ashton Jones, Jesse Sheidlower,
 191 Johan Lindstrom, Marcus Ramberg and all the others who've helped.
 192
 193 =head1 LICENSE
 194
 195 This library is free software . You can redistribute it and/or modify it under
 196 the same terms as perl itself.
 197
 198 =cut
 199
 200 1;