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