lib/Catalyst/Base.pm

   1 package Catalyst::Base;
   2
   3 use strict;
   4 use base qw/Catalyst::Component Catalyst::AttrContainer Class::Accessor::Fast/;
   5
   6 use Catalyst::Exception;
   7 use Catalyst::Utils;
   8 use Class::Inspector;
   9 use NEXT;
  10
  11 __PACKAGE__->mk_classdata($_) for qw/_dispatch_steps _action_class/;
  12
  13 __PACKAGE__->_dispatch_steps( [qw/_BEGIN _AUTO _ACTION/] );
  14 __PACKAGE__->_action_class('Catalyst::Action');
  15
  16 __PACKAGE__->mk_accessors( qw/_application/ );
  17
  18 ### _app as alias
  19 *_app = *_application;
  20
  21 sub _DISPATCH : Private {
  22     my ( $self, $c ) = @_;
  23
  24     foreach my $disp ( @{ $self->_dispatch_steps } ) {
  25         last unless $c->forward($disp);
  26     }
  27
  28     $c->forward('_END');
  29 }
  30
  31 sub _BEGIN : Private {
  32     my ( $self, $c ) = @_;
  33     my $begin = ( $c->get_actions( 'begin', $c->namespace ) )[-1];
  34     return 1 unless $begin;
  35     $begin->dispatch( $c );
  36     return !@{ $c->error };
  37 }
  38
  39 sub _AUTO : Private {
  40     my ( $self, $c ) = @_;
  41     my @auto = $c->get_actions( 'auto', $c->namespace );
  42     foreach my $auto (@auto) {
  43         $auto->dispatch( $c );
  44         return 0 unless $c->state;
  45     }
  46     return 1;
  47 }
  48
  49 sub _ACTION : Private {
  50     my ( $self, $c ) = @_;
  51     if (   ref $c->action
  52         && $c->action->can('execute')
  53         && $c->req->action )
  54     {
  55         $c->action->dispatch( $c );
  56     }
  57     return !@{ $c->error };
  58 }
  59
  60 sub _END : Private {
  61     my ( $self, $c ) = @_;
  62     my $end = ( $c->get_actions( 'end', $c->namespace ) )[-1];
  63     return 1 unless $end;
  64     $end->dispatch( $c );
  65     return !@{ $c->error };
  66 }
  67
  68 sub new {
  69     my $self = shift;
  70     my $app = $_[0];
  71     my $new = $self->NEXT::new(@_);
  72     $new->_application( $app );
  73     return $new;
  74 }
  75
  76 =head1 NAME
  77
  78 Catalyst::Base - Catalyst Base Class
  79
  80 =head1 SYNOPSIS
  81
  82 See L<Catalyst>
  83
  84 =head1 DESCRIPTION
  85
  86 Catalyst Base Class
  87
  88 This is the base class for all Catalyst components.  It is a subclass
  89 of L<Catalyst::Component> which is the universal base class for
  90 catalyst components.  This module includes handling of dispatching for
  91 controller actions.
  92
  93 =head1 METHODS
  94
  95 =head2 $class->new($app, @args)
  96
  97 Proxies through to NEXT::new and stashes the application instance as
  98 $self->_application.
  99
 100 =head2 $self->action_for('name')
 101
 102 Returns the Catalyst::Action object (if any) for a given method name in
 103 this component.
 104
 105 =cut
 106
 107 sub action_for {
 108     my ( $self, $name ) = @_;
 109     my $app = ($self->isa('Catalyst') ? $self : $self->_application);
 110     return $app->dispatcher->get_action($name, $self->action_namespace);
 111 }
 112
 113 =head2 $self->action_namespace($c)
 114
 115 Returns the private namespace for actions in this component. Defaults to a value
 116 from the controller name (for e.g. MyApp::Controller::Foo::Bar becomes
 117 "foo/bar") or can be overriden from the "namespace" config key.
 118
 119 =cut
 120
 121 sub action_namespace {
 122     my ( $self, $c ) = @_;
 123     unless ( $c ) {
 124         $c = ($self->isa('Catalyst') ? $self : $self->_application);
 125     }
 126     my $hash = (ref $self ? $self : $self->config); # hate app-is-class
 127     return $hash->{namespace} if exists $hash->{namespace};
 128     return Catalyst::Utils::class2prefix( ref($self) || $self,
 129         $c->config->{case_sensitive} )
 130       || '';
 131 }
 132
 133 =head2 $self->path_prefix($c)
 134
 135 Returns the default path prefix for :Local, :LocalRegex and relative :Path
 136 actions in this component. Defaults to the action_namespace or can be
 137 overriden from the "path" config key.
 138
 139 =cut
 140
 141 sub path_prefix {
 142     my ( $self, $c ) = @_;
 143     unless ( $c ) {
 144         $c = ($self->isa('Catalyst') ? $self : $self->_application);
 145     }
 146     my $hash = (ref $self ? $self : $self->config); # hate app-is-class
 147     return $hash->{path} if exists $hash->{path};
 148     return shift->action_namespace(@_);
 149 }
 150
 151 =head2 $self->register_actions($c)
 152
 153 Finds all applicable actions for this component, creates Catalyst::Action
 154 objects (using $self->create_action) for them and registers them with
 155 $c->dispatcher.
 156
 157 =cut
 158
 159 sub register_actions {
 160     my ( $self, $c ) = @_;
 161     my $class = ref $self || $self;
 162     my $namespace = $self->action_namespace($c);
 163     my %methods;
 164     $methods{ $self->can($_) } = $_
 165       for @{ Class::Inspector->methods($class) || [] };
 166
 167     # Advanced inheritance support for plugins and the like
 168     my @action_cache;
 169     {
 170         no strict 'refs';
 171         for my $isa ( @{"$class\::ISA"}, $class ) {
 172             push @action_cache, @{ $isa->_action_cache }
 173               if $isa->can('_action_cache');
 174         }
 175     }
 176
 177     foreach my $cache (@action_cache) {
 178         my $code   = $cache->[0];
 179         my $method = delete $methods{$code}; # avoid dupe registers
 180         next unless $method;
 181         my $attrs = $self->_parse_attrs( $c, $method, @{ $cache->[1] } );
 182         if ( $attrs->{Private} && ( keys %$attrs > 1 ) ) {
 183             $c->log->debug( 'Bad action definition "'
 184                   . join( ' ', @{ $cache->[1] } )
 185                   . qq/" for "$class->$method"/ )
 186               if $c->debug;
 187             next;
 188         }
 189         my $reverse = $namespace ? "$namespace/$method" : $method;
 190         my $action = $self->create_action(
 191             name       => $method,
 192             code       => $code,
 193             reverse    => $reverse,
 194             namespace  => $namespace,
 195             class      => $class,
 196             attributes => $attrs,
 197         );
 198
 199         $c->dispatcher->register( $c, $action );
 200     }
 201 }
 202
 203 =head2 $self->create_action(%args)
 204
 205 Called with a hash of data to be use for construction of a new Catalyst::Action
 206 (or appropriate sub/alternative class) object.
 207
 208 Primarily designed for the use of register_actions.
 209
 210 =cut
 211
 212 sub create_action {
 213     my $self = shift;
 214     my %args = @_;
 215
 216     my $class = (exists $args{attributes}{ActionClass}
 217                     ? $args{attributes}{ActionClass}[0]
 218                     : $self->_action_class);
 219
 220     unless ( Class::Inspector->loaded($class) ) {
 221         require Class::Inspector->filename($class);
 222     }
 223
 224     return $class->new( \%args );
 225 }
 226
 227 sub _parse_attrs {
 228     my ( $self, $c, $name, @attrs ) = @_;
 229
 230     my %raw_attributes;
 231
 232     foreach my $attr (@attrs) {
 233
 234         # Parse out :Foo(bar) into Foo => bar etc (and arrayify)
 235
 236         if ( my ( $key, $value ) = ( $attr =~ /^(.*?)(?:\(\s*(.+?)\s*\))?$/ ) )
 237         {
 238
 239             if ( defined $value ) {
 240                 ( $value =~ s/^'(.*)'$/$1/ ) || ( $value =~ s/^"(.*)"/$1/ );
 241             }
 242             push( @{ $raw_attributes{$key} }, $value );
 243         }
 244     }
 245
 246     my $hash = (ref $self ? $self : $self->config); # hate app-is-class
 247
 248     if (exists $hash->{actions} || exists $hash->{action}) {
 249       my $a = $hash->{actions} || $hash->{action};
 250       %raw_attributes = ((exists $a->{'*'} ? %{$a->{'*'}} : ()),
 251                          %raw_attributes,
 252                          (exists $a->{$name} ? %{$a->{$name}} : ()));
 253     }
 254
 255     my %final_attributes;
 256
 257     foreach my $key (keys %raw_attributes) {
 258
 259         my $raw = $raw_attributes{$key};
 260
 261         foreach my $value (ref($raw) eq 'ARRAY' ? @$raw : $raw) {
 262
 263             my $meth = "_parse_${key}_attr";
 264             if ( $self->can($meth) ) {
 265                 ( $key, $value ) = $self->$meth( $c, $name, $value );
 266             }
 267             push( @{ $final_attributes{$key} }, $value );
 268         }
 269     }
 270
 271     return \%final_attributes;
 272 }
 273
 274 sub _parse_Global_attr {
 275     my ( $self, $c, $name, $value ) = @_;
 276     return $self->_parse_Path_attr( $c, $name, "/$name" );
 277 }
 278
 279 sub _parse_Absolute_attr { shift->_parse_Global_attr(@_); }
 280
 281 sub _parse_Local_attr {
 282     my ( $self, $c, $name, $value ) = @_;
 283     return $self->_parse_Path_attr( $c, $name, $name );
 284 }
 285
 286 sub _parse_Relative_attr { shift->_parse_Local_attr(@_); }
 287
 288 sub _parse_Path_attr {
 289     my ( $self, $c, $name, $value ) = @_;
 290     $value ||= '';
 291     if ( $value =~ m!^/! ) {
 292         return ( 'Path', $value );
 293     }
 294     elsif ( length $value ) {
 295         return ( 'Path', join( '/', $self->path_prefix($c), $value ) );
 296     }
 297     else {
 298         return ( 'Path', $self->path_prefix($c) );
 299     }
 300 }
 301
 302 sub _parse_Regex_attr {
 303     my ( $self, $c, $name, $value ) = @_;
 304     return ( 'Regex', $value );
 305 }
 306
 307 sub _parse_Regexp_attr { shift->_parse_Regex_attr(@_); }
 308
 309 sub _parse_LocalRegex_attr {
 310     my ( $self, $c, $name, $value ) = @_;
 311     unless ( $value =~ s/^\^// ) { $value = "(?:.*?)$value"; }
 312     return ( 'Regex', '^' . $self->path_prefix($c) . "/${value}" );
 313 }
 314
 315 sub _parse_LocalRegexp_attr { shift->_parse_LocalRegex_attr(@_); }
 316
 317 sub _parse_ActionClass_attr {
 318     my ( $self, $c, $name, $value ) = @_;
 319     unless ( $value =~ s/^\+// ) {
 320       $value = join('::', $self->_action_class, $value );
 321     }
 322     return ( 'ActionClass', $value );
 323 }
 324
 325 =head2 $self->_application
 326
 327 =head2 $self->_app
 328
 329 Returns the application instance stored by C<new()>
 330
 331 =head1 SEE ALSO
 332
 333 L<Catalyst>, L<Catalyst::Controller>.
 334
 335 =head1 AUTHOR
 336
 337 Sebastian Riedel, C<sri@cpan.org>
 338 Marcus Ramberg, C<mramberg@cpan.org>
 339 Matt S Trout, C<mst@shadowcatsystems.co.uk>
 340
 341 =head1 COPYRIGHT
 342
 343 This program is free software, you can redistribute it and/or modify it under
 344 the same terms as Perl itself.
 345
 346 =cut
 347
 348 1;