lib/Catalyst/Controller.pm

   1 package Catalyst::Controller;
   2
   3 use Moose;
   4 use Class::MOP;
   5 use Class::Load ':all';
   6 use String::RewritePrefix;
   7 use Moose::Util qw/find_meta/;
   8 use List::Util qw/first/;
   9 use List::MoreUtils qw/uniq/;
  10 use namespace::clean -except => 'meta';
  11
  12 BEGIN {
  13     extends qw/Catalyst::Component/;
  14     with qw/MooseX::MethodAttributes::Role::AttrContainer::Inheritable/;
  15 }
  16
  17 use MooseX::MethodAttributes;
  18 use Catalyst::Exception;
  19 use Catalyst::Utils;
  20
  21 with 'Catalyst::Component::ApplicationAttribute';
  22
  23 has path_prefix => (
  24     is        => 'rw',
  25     isa       => 'Str',
  26     init_arg  => 'path',
  27     predicate => 'has_path_prefix',
  28 );
  29
  30 has action_namespace => (
  31     is        => 'rw',
  32     isa       => 'Str',
  33     init_arg  => 'namespace',
  34     predicate => 'has_action_namespace',
  35 );
  36
  37 has actions => (
  38     accessor => '_controller_actions',
  39     isa      => 'HashRef',
  40     init_arg => undef,
  41 );
  42
  43 has _action_role_args => (
  44     traits     => [qw(Array)],
  45     isa        => 'ArrayRef[Str]',
  46     init_arg   => 'action_roles',
  47     default    => sub { [] },
  48     handles    => {
  49         _action_role_args => 'elements',
  50     },
  51 );
  52
  53 has _action_roles => (
  54     traits     => [qw(Array)],
  55     isa        => 'ArrayRef[RoleName]',
  56     init_arg   => undef,
  57     lazy       => 1,
  58     builder    => '_build__action_roles',
  59     handles    => {
  60         _action_roles => 'elements',
  61     },
  62 );
  63
  64 has action_args => (is => 'ro');
  65
  66 # ->config(actions => { '*' => ...
  67 has _all_actions_attributes => (
  68     is       => 'ro',
  69     isa      => 'HashRef',
  70     init_arg => undef,
  71     lazy     => 1,
  72     builder  => '_build__all_actions_attributes',
  73 );
  74
  75 sub BUILD {
  76     my ($self, $args) = @_;
  77     my $action  = delete $args->{action}  || {};
  78     my $actions = delete $args->{actions} || {};
  79     my $attr_value = $self->merge_config_hashes($actions, $action);
  80     $self->_controller_actions($attr_value);
  81
  82     # trigger lazy builder
  83     $self->_all_actions_attributes;
  84     $self->_action_roles;
  85 }
  86
  87 sub _build__action_roles {
  88     my $self = shift;
  89     my @roles = $self->_expand_role_shortname($self->_action_role_args);
  90     load_class($_) for @roles;
  91     return \@roles;
  92 }
  93
  94 sub _build__all_actions_attributes {
  95     my ($self) = @_;
  96     delete $self->_controller_actions->{'*'} || {};
  97 }
  98
  99 =head1 NAME
 100
 101 Catalyst::Controller - Catalyst Controller base class
 102
 103 =head1 SYNOPSIS
 104
 105   package MyApp::Controller::Search
 106   use base qw/Catalyst::Controller/;
 107
 108   sub foo : Local {
 109     my ($self,$c,@args) = @_;
 110     ...
 111   } # Dispatches to /search/foo
 112
 113 =head1 DESCRIPTION
 114
 115 Controllers are where the actions in the Catalyst framework
 116 reside. Each action is represented by a function with an attribute to
 117 identify what kind of action it is. See the L<Catalyst::Dispatcher>
 118 for more info about how Catalyst dispatches to actions.
 119
 120 =cut
 121
 122 #I think both of these could be attributes. doesn't really seem like they need
 123 #to be class data. i think that attributes +default would work just fine
 124 __PACKAGE__->mk_classdata($_) for qw/_dispatch_steps _action_class _action_role_prefix/;
 125
 126 __PACKAGE__->_dispatch_steps( [qw/_BEGIN _AUTO _ACTION/] );
 127 __PACKAGE__->_action_class('Catalyst::Action');
 128 __PACKAGE__->_action_role_prefix([ 'Catalyst::ActionRole::' ]);
 129
 130
 131 sub _DISPATCH : Private {
 132     my ( $self, $c ) = @_;
 133
 134     foreach my $disp ( @{ $self->_dispatch_steps } ) {
 135         last unless $c->forward($disp);
 136     }
 137
 138     $c->forward('_END');
 139 }
 140
 141 sub _BEGIN : Private {
 142     my ( $self, $c ) = @_;
 143     my $begin = ( $c->get_actions( 'begin', $c->namespace ) )[-1];
 144     return 1 unless $begin;
 145     $begin->dispatch( $c );
 146     #If there is an error, all bets off
 147     if( @{ $c->error }) {
 148       return !@{ $c->error };
 149     } else {
 150       return $c->state || 1;
 151     }
 152 }
 153
 154 sub _AUTO : Private {
 155     my ( $self, $c ) = @_;
 156     my @auto = $c->get_actions( 'auto', $c->namespace );
 157     foreach my $auto (@auto) {
 158         # We FORCE the auto action user to explicitly return
 159         # true.  We need to do this since there's some auto
 160         # users (Catalyst::Authentication::Credential::HTTP) that
 161         # actually do a detach instead.
 162         $c->state(0);
 163         $auto->dispatch( $c );
 164         return 0 unless $c->state;
 165     }
 166     return $c->state || 1;
 167 }
 168
 169 sub _ACTION : Private {
 170     my ( $self, $c ) = @_;
 171     if (   ref $c->action
 172         && $c->action->can('execute')
 173         && defined $c->req->action )
 174     {
 175         $c->action->dispatch( $c );
 176     }
 177     #If there is an error, all bets off
 178     if( @{ $c->error }) {
 179       return !@{ $c->error };
 180     } else {
 181       return $c->state || 1;
 182     }
 183 }
 184
 185 sub _END : Private {
 186     my ( $self, $c ) = @_;
 187     my $end = ( $c->get_actions( 'end', $c->namespace ) )[-1];
 188     return 1 unless $end;
 189     $end->dispatch( $c );
 190     return !@{ $c->error };
 191 }
 192
 193 sub action_for {
 194     my ( $self, $name ) = @_;
 195     my $app = ($self->isa('Catalyst') ? $self : $self->_application);
 196     return $app->dispatcher->get_action($name, $self->action_namespace);
 197 }
 198
 199 #my opinion is that this whole sub really should be a builder method, not
 200 #something that happens on every call. Anyone else disagree?? -- groditi
 201 ## -- apparently this is all just waiting for app/ctx split
 202 around action_namespace => sub {
 203     my $orig = shift;
 204     my ( $self, $c ) = @_;
 205
 206     my $class = ref($self) || $self;
 207     my $appclass = ref($c) || $c;
 208     if( ref($self) ){
 209         return $self->$orig if $self->has_action_namespace;
 210     } else {
 211         return $class->config->{namespace} if exists $class->config->{namespace};
 212     }
 213
 214     my $case_s;
 215     if( $c ){
 216         $case_s = $appclass->config->{case_sensitive};
 217     } else {
 218         if ($self->isa('Catalyst')) {
 219             $case_s = $class->config->{case_sensitive};
 220         } else {
 221             if (ref $self) {
 222                 $case_s = ref($self->_application)->config->{case_sensitive};
 223             } else {
 224                 confess("Can't figure out case_sensitive setting");
 225             }
 226         }
 227     }
 228
 229     my $namespace = Catalyst::Utils::class2prefix($self->catalyst_component_name, $case_s) || '';
 230     $self->$orig($namespace) if ref($self);
 231     return $namespace;
 232 };
 233
 234 #Once again, this is probably better written as a builder method
 235 around path_prefix => sub {
 236     my $orig = shift;
 237     my $self = shift;
 238     if( ref($self) ){
 239       return $self->$orig if $self->has_path_prefix;
 240     } else {
 241       return $self->config->{path} if exists $self->config->{path};
 242     }
 243     my $namespace = $self->action_namespace(@_);
 244     $self->$orig($namespace) if ref($self);
 245     return $namespace;
 246 };
 247
 248 sub get_action_methods {
 249     my $self = shift;
 250     my $meta = find_meta($self) || confess("No metaclass setup for $self");
 251     confess(
 252         sprintf "Metaclass %s for %s cannot support register_actions.",
 253             ref $meta, $meta->name,
 254     ) unless $meta->can('get_nearest_methods_with_attributes');
 255     my @methods = $meta->get_nearest_methods_with_attributes;
 256
 257     # actions specified via config are also action_methods
 258     push(
 259         @methods,
 260         map {
 261             $meta->find_method_by_name($_)
 262                 || confess( sprintf 'Action "%s" is not available from controller %s',
 263                             $_, ref $self )
 264         } keys %{ $self->_controller_actions }
 265     ) if ( ref $self );
 266     return uniq @methods;
 267 }
 268
 269
 270 sub register_actions {
 271     my ( $self, $c ) = @_;
 272     $self->register_action_methods( $c, $self->get_action_methods );
 273 }
 274
 275 sub register_action_methods {
 276     my ( $self, $c, @methods ) = @_;
 277     my $class = $self->catalyst_component_name;
 278     #this is still not correct for some reason.
 279     my $namespace = $self->action_namespace($c);
 280
 281     # FIXME - fugly
 282     if (!blessed($self) && $self eq $c && scalar(@methods)) {
 283         my @really_bad_methods = grep { ! /^_(DISPATCH|BEGIN|AUTO|ACTION|END)$/ } map { $_->name } @methods;
 284         if (scalar(@really_bad_methods)) {
 285             $c->log->warn("Action methods (" . join(', ', @really_bad_methods) . ") found defined in your application class, $self. This is deprecated, please move them into a Root controller.");
 286         }
 287     }
 288
 289     foreach my $method (@methods) {
 290         my $name = $method->name;
 291         # Horrible hack! All method metaclasses should have an attributes
 292         # method, core Moose bug - see r13354.
 293         my $attributes = $method->can('attributes') ? $method->attributes : [];
 294         my $attrs = $self->_parse_attrs( $c, $name, @{ $attributes } );
 295         if ( $attrs->{Private} && ( keys %$attrs > 1 ) ) {
 296             $c->log->warn( 'Bad action definition "'
 297                   . join( ' ', @{ $attributes } )
 298                   . qq/" for "$class->$name"/ )
 299               if $c->debug;
 300             next;
 301         }
 302         my $reverse = $namespace ? "${namespace}/${name}" : $name;
 303         my $action = $self->create_action(
 304             name       => $name,
 305             code       => $method->body,
 306             reverse    => $reverse,
 307             namespace  => $namespace,
 308             class      => $class,
 309             attributes => $attrs,
 310         );
 311
 312         $c->dispatcher->register( $c, $action );
 313     }
 314 }
 315
 316 sub _apply_action_class_roles {
 317     my ($self, $class, @roles) = @_;
 318
 319     load_class($_) for @roles;
 320     my $meta = Moose::Meta::Class->initialize($class)->create_anon_class(
 321         superclasses => [$class],
 322         roles        => \@roles,
 323         cache        => 1,
 324     );
 325     $meta->add_method(meta => sub { $meta });
 326
 327     return $meta->name;
 328 }
 329
 330 sub action_class {
 331     my $self = shift;
 332     my %args = @_;
 333
 334     my $class = (exists $args{attributes}{ActionClass}
 335         ? $args{attributes}{ActionClass}[0]
 336         : $self->_action_class);
 337
 338     load_class($class);
 339     return $class;
 340 }
 341
 342 sub create_action {
 343     my $self = shift;
 344     my %args = @_;
 345
 346     my $class = $self->action_class(%args);
 347
 348     load_class($class);
 349     Moose->init_meta(for_class => $class)
 350         unless Class::MOP::does_metaclass_exist($class);
 351
 352     unless ($args{name} =~ /^_(DISPATCH|BEGIN|AUTO|ACTION|END)$/) {
 353        my @roles = $self->gather_action_roles(%args);
 354        push @roles, $self->gather_default_action_roles(%args);
 355
 356        $class = $self->_apply_action_class_roles($class, @roles) if @roles;
 357     }
 358
 359     my $action_args = (
 360         ref($self)
 361             ? $self->action_args
 362             : $self->config->{action_args}
 363     );
 364
 365     my %extra_args = (
 366         %{ $action_args->{'*'}           || {} },
 367         %{ $action_args->{ $args{name} } || {} },
 368     );
 369
 370     return $class->new({ %extra_args, %args });
 371 }
 372
 373 sub gather_action_roles {
 374    my ($self, %args) = @_;
 375    return (
 376       (blessed $self ? $self->_action_roles : ()),
 377       @{ $args{attributes}->{Does} || [] },
 378    );
 379 }
 380
 381 sub gather_default_action_roles {
 382   my ($self, %args) = @_;
 383   my @roles = ();
 384   push @roles, 'Catalyst::ActionRole::HTTPMethods'
 385     if $args{attributes}->{Method};
 386
 387   push @roles, 'Catalyst::ActionRole::ConsumesContent'
 388     if $args{attributes}->{Consumes};
 389
 390   push @roles, 'Catalyst::ActionRole::Scheme'
 391     if $args{attributes}->{Scheme};
 392
 393   push @roles, 'Catalyst::ActionRole::QueryMatching'
 394     if $args{attributes}->{Query};
 395     return @roles;
 396 }
 397
 398 sub _parse_attrs {
 399     my ( $self, $c, $name, @attrs ) = @_;
 400
 401     my %raw_attributes;
 402
 403     foreach my $attr (@attrs) {
 404
 405         # Parse out :Foo(bar) into Foo => bar etc (and arrayify)
 406
 407         if ( my ( $key, $value ) = ( $attr =~ /^(.*?)(?:\(\s*(.+?)?\s*\))?$/ ) )
 408         {
 409
 410             if ( defined $value ) {
 411                 ( $value =~ s/^'(.*)'$/$1/ ) || ( $value =~ s/^"(.*)"/$1/ );
 412             }
 413             push( @{ $raw_attributes{$key} }, $value );
 414         }
 415     }
 416
 417     my ($actions_config, $all_actions_config);
 418     if( ref($self) ) {
 419         $actions_config = $self->_controller_actions;
 420         # No, you're not getting actions => { '*' => ... } with actions in MyApp.
 421         $all_actions_config = $self->_all_actions_attributes;
 422     } else {
 423         my $cfg = $self->config;
 424         $actions_config = $self->merge_config_hashes($cfg->{actions}, $cfg->{action});
 425         $all_actions_config = {};
 426     }
 427
 428     %raw_attributes = (
 429         %raw_attributes,
 430         # Note we deep copy array refs here to stop crapping on config
 431         # when attributes are parsed. RT#65463
 432         exists $actions_config->{$name} ? map { ref($_) eq 'ARRAY' ? [ @$_ ] : $_ } %{ $actions_config->{$name } } : (),
 433     );
 434
 435     # Private actions with additional attributes will raise a warning and then
 436     # be ignored. Adding '*' arguments to the default _DISPATCH / etc. methods,
 437     # which are Private, will prevent those from being registered. They should
 438     # probably be turned into :Actions instead, or we might want to otherwise
 439     # disambiguate between those built-in internal actions and user-level
 440     # Private ones.
 441     %raw_attributes = (%{ $all_actions_config }, %raw_attributes)
 442         unless $raw_attributes{Private};
 443
 444     my %final_attributes;
 445
 446     while (my ($key, $value) = each %raw_attributes){
 447         my $new_attrs = $self->_parse_attr($c, $name, $key => $value );
 448         push @{ $final_attributes{$_} }, @{ $new_attrs->{$_} } for keys %$new_attrs;
 449     }
 450
 451     return \%final_attributes;
 452 }
 453
 454 sub _parse_attr {
 455     my ($self, $c, $name, $key, $values) = @_;
 456
 457     my %final_attributes;
 458     foreach my $value (ref($values) eq 'ARRAY' ? @$values : $values) {
 459         my $meth = "_parse_${key}_attr";
 460         if ( my $code = $self->can($meth) ) {
 461             my %new_attrs = $self->$code( $c, $name, $value );
 462             while (my ($new_key, $value) = each %new_attrs){
 463                 my $new_attrs = $key eq $new_key ?
 464                     { $new_key => [$value] } :
 465                     $self->_parse_attr($c, $name, $new_key => $value );
 466                 push @{ $final_attributes{$_} }, @{ $new_attrs->{$_} } for keys %$new_attrs;
 467             }
 468         }
 469         else {
 470             push( @{ $final_attributes{$key} }, $value );
 471         }
 472     }
 473
 474     return \%final_attributes;
 475 }
 476
 477 sub _parse_Global_attr {
 478     my ( $self, $c, $name, $value ) = @_;
 479     # _parse_attr will call _parse_Path_attr for us
 480     return Path => "/$name";
 481 }
 482
 483 sub _parse_Absolute_attr { shift->_parse_Global_attr(@_); }
 484
 485 sub _parse_Local_attr {
 486     my ( $self, $c, $name, $value ) = @_;
 487     # _parse_attr will call _parse_Path_attr for us
 488     return Path => $name;
 489 }
 490
 491 sub _parse_Relative_attr { shift->_parse_Local_attr(@_); }
 492
 493 sub _parse_Path_attr {
 494     my ( $self, $c, $name, $value ) = @_;
 495     $value = '' if !defined $value;
 496     if ( $value =~ m!^/! ) {
 497         return ( 'Path', $value );
 498     }
 499     elsif ( length $value ) {
 500         return ( 'Path', join( '/', $self->path_prefix($c), $value ) );
 501     }
 502     else {
 503         return ( 'Path', $self->path_prefix($c) );
 504     }
 505 }
 506
 507 sub _parse_Chained_attr {
 508     my ($self, $c, $name, $value) = @_;
 509
 510     if (defined($value) && length($value)) {
 511         if ($value eq '.') {
 512             $value = '/'.$self->action_namespace($c);
 513         } elsif (my ($rel, $rest) = $value =~ /^((?:\.{2}\/)+)(.*)$/) {
 514             my @parts = split '/', $self->action_namespace($c);
 515             my @levels = split '/', $rel;
 516
 517             $value = '/'.join('/', @parts[0 .. $#parts - @levels], $rest);
 518         } elsif ($value !~ m/^\//) {
 519             my $action_ns = $self->action_namespace($c);
 520
 521             if ($action_ns) {
 522                 $value = '/'.join('/', $action_ns, $value);
 523             } else {
 524                 $value = '/'.$value; # special case namespace '' (root)
 525             }
 526         }
 527     } else {
 528         $value = '/'
 529     }
 530
 531     return Chained => $value;
 532 }
 533
 534 sub _parse_ChainedParent_attr {
 535     my ($self, $c, $name, $value) = @_;
 536     return $self->_parse_Chained_attr($c, $name, '../'.$name);
 537 }
 538
 539 sub _parse_PathPrefix_attr {
 540     my ( $self, $c ) = @_;
 541     return PathPart => $self->path_prefix($c);
 542 }
 543
 544 sub _parse_ActionClass_attr {
 545     my ( $self, $c, $name, $value ) = @_;
 546     my $appname = $self->_application;
 547     $value = Catalyst::Utils::resolve_namespace($appname . '::Action', $self->_action_class, $value);
 548     return ( 'ActionClass', $value );
 549 }
 550
 551 sub _parse_MyAction_attr {
 552     my ( $self, $c, $name, $value ) = @_;
 553
 554     my $appclass = Catalyst::Utils::class2appclass($self);
 555     $value = "+${appclass}::Action::${value}";
 556
 557     return ( 'ActionClass', $value );
 558 }
 559
 560 sub _parse_Does_attr {
 561     my ($self, $app, $name, $value) = @_;
 562     return Does => $self->_expand_role_shortname($value);
 563 }
 564
 565 sub _parse_GET_attr     { Method => 'GET'     }
 566 sub _parse_POST_attr    { Method => 'POST'    }
 567 sub _parse_PUT_attr     { Method => 'PUT'     }
 568 sub _parse_DELETE_attr  { Method => 'DELETE'  }
 569 sub _parse_OPTIONS_attr { Method => 'OPTIONS' }
 570 sub _parse_HEAD_attr    { Method => 'HEAD'    }
 571 sub _parse_PATCH_attr  { Method => 'PATCH'  }
 572
 573 sub _expand_role_shortname {
 574     my ($self, @shortnames) = @_;
 575     my $app = $self->_application;
 576
 577     my $prefix = $self->can('_action_role_prefix') ? $self->_action_role_prefix : ['Catalyst::ActionRole::'];
 578     my @prefixes = (qq{${app}::ActionRole::}, @$prefix);
 579
 580     return String::RewritePrefix->rewrite(
 581         { ''  => sub {
 582             my $loaded = load_first_existing_class(
 583                 map { "$_$_[0]" } @prefixes
 584             );
 585             return first { $loaded =~ /^$_/ }
 586               sort { length $b <=> length $a } @prefixes;
 587           },
 588           '~' => $prefixes[0],
 589           '+' => '' },
 590         @shortnames,
 591     );
 592 }
 593
 594 __PACKAGE__->meta->make_immutable;
 595
 596 1;
 597
 598 __END__
 599
 600 =head1 CONFIGURATION
 601
 602 Like any other L<Catalyst::Component>, controllers have a config hash,
 603 accessible through $self->config from the controller actions.  Some
 604 settings are in use by the Catalyst framework:
 605
 606 =head2 namespace
 607
 608 This specifies the internal namespace the controller should be bound
 609 to. By default the controller is bound to the URI version of the
 610 controller name. For instance controller 'MyApp::Controller::Foo::Bar'
 611 will be bound to 'foo/bar'. The default Root controller is an example
 612 of setting namespace to '' (the null string).
 613
 614 =head2 path
 615
 616 Sets 'path_prefix', as described below.
 617
 618 =head2 action
 619
 620 Allows you to set the attributes that the dispatcher creates actions out of.
 621 This allows you to do 'rails style routes', or override some of the
 622 attribute definitions of actions composed from Roles.
 623 You can set arguments globally (for all actions of the controller) and
 624 specifically (for a single action).
 625
 626     __PACKAGE__->config(
 627         action => {
 628             '*' => { Chained => 'base', Args => 0  },
 629             base => { Chained => '/', PathPart => '', CaptureArgs => 0 },
 630         },
 631      );
 632
 633 In the case above every sub in the package would be made into a Chain
 634 endpoint with a URI the same as the sub name for each sub, chained
 635 to the sub named C<base>. Ergo dispatch to C</example> would call the
 636 C<base> method, then the C<example> method.
 637
 638 =head2 action_args
 639
 640 Allows you to set constructor arguments on your actions. You can set arguments
 641 globally and specifically (as above).
 642 This is particularly useful when using C<ActionRole>s
 643 (L<Catalyst::Controller::ActionRole>) and custom C<ActionClass>es.
 644
 645     __PACKAGE__->config(
 646         action_args => {
 647             '*' => { globalarg1 => 'hello', globalarg2 => 'goodbye' },
 648             'specific_action' => { customarg => 'arg1' },
 649         },
 650      );
 651
 652 In the case above the action class associated with C<specific_action> would get
 653 passed the following arguments, in addition to the normal action constructor
 654 arguments, when it is instantiated:
 655
 656   (globalarg1 => 'hello', globalarg2 => 'goodbye', customarg => 'arg1')
 657
 658 =head1 METHODS
 659
 660 =head2 BUILDARGS ($app, @args)
 661
 662 From L<Catalyst::Component::ApplicationAttribute>, stashes the application
 663 instance as $self->_application.
 664
 665 =head2 $self->action_for('name')
 666
 667 Returns the Catalyst::Action object (if any) for a given method name
 668 in this component.
 669
 670 =head2 $self->action_namespace($c)
 671
 672 Returns the private namespace for actions in this component. Defaults
 673 to a value from the controller name (for
 674 e.g. MyApp::Controller::Foo::Bar becomes "foo/bar") or can be
 675 overridden from the "namespace" config key.
 676
 677
 678 =head2 $self->path_prefix($c)
 679
 680 Returns the default path prefix for :PathPrefix, :Local and
 681 relative :Path actions in this component. Defaults to the action_namespace or
 682 can be overridden from the "path" config key.
 683
 684 =head2 $self->register_actions($c)
 685
 686 Finds all applicable actions for this component, creates
 687 Catalyst::Action objects (using $self->create_action) for them and
 688 registers them with $c->dispatcher.
 689
 690 =head2 $self->get_action_methods()
 691
 692 Returns a list of L<Moose::Meta::Method> objects, doing the
 693 L<MooseX::MethodAttributes::Role::Meta::Method> role, which are the set of
 694 action methods for this package.
 695
 696 =head2 $self->register_action_methods($c, @methods)
 697
 698 Creates action objects for a set of action methods using C< create_action >,
 699 and registers them with the dispatcher.
 700
 701 =head2 $self->action_class(%args)
 702
 703 Used when a controller is creating an action to determine the correct base
 704 action class to use.
 705
 706 =head2 $self->create_action(%args)
 707
 708 Called with a hash of data to be use for construction of a new
 709 Catalyst::Action (or appropriate sub/alternative class) object.
 710
 711 =head2 $self->gather_action_roles(\%action_args)
 712
 713 Gathers the list of roles to apply to an action with the given %action_args.
 714
 715 =head2 $self->gather_default_action_roles(\%action_args)
 716
 717 returns a list of action roles to be applied based on core, builtin rules.
 718 Currently only the L<Catalyst::ActionRole::HTTPMethods> role is applied
 719 this way.
 720
 721 =head2 $self->_application
 722
 723 =head2 $self->_app
 724
 725 Returns the application instance stored by C<new()>
 726
 727 =head1 ACTION SUBROUTINE ATTRIBUTES
 728
 729 Please see L<Catalyst::Manual::Intro> for more details
 730
 731 Think of action attributes as a sort of way to record metadata about an action,
 732 similar to how annotations work in other languages you might have heard of.
 733 Generally L<Catalyst> uses these to influence how the dispatcher sees your
 734 action and when it will run it in response to an incoming request.  They can
 735 also be used for other things.  Here's a summary, but you should refer to the
 736 linked manual page for additional help.
 737
 738 =head2 Global
 739
 740   sub homepage :Global { ... }
 741
 742 A global action defined in any controller always runs relative to your root.
 743 So the above is the same as:
 744
 745   sub myaction :Path("/homepage") { ... }
 746
 747 =head2 Absolute
 748
 749 Status: Deprecated alias to L</Global>.
 750
 751 =head2 Local
 752
 753 Alias to "Path("$action_name").  The following two actions are the same:
 754
 755   sub myaction :Local { ... }
 756   sub myaction :Path('myaction') { ... }
 757
 758 =head2 Relative
 759
 760 Status: Deprecated alias to L</Local>
 761
 762 =head2 Path
 763
 764 Handle various types of paths:
 765
 766   package MyApp::Controller::Baz {
 767
 768     ...
 769
 770     sub myaction1 :Path { ... }  # -> /baz
 771     sub myaction2 :Path('foo') { ... } # -> /baz/foo
 772     sub myaction2 :Path('/bar') { ... } # -> /bar
 773   }
 774
 775 This is a general toolbox for attaching your action to a given path.
 776
 777
 778 =head2 Regex
 779
 780 =head2 Regexp
 781
 782 B<Status: Deprecated.>  Use Chained methods or other techniques.
 783 If you really depend on this, install the standalone
 784 L<Catalyst::DispatchType::Regex> distribution.
 785
 786 A global way to match a give regular expression in the incoming request path.
 787
 788 =head2 LocalRegex
 789
 790 =head2 LocalRegexp
 791
 792 B<Status: Deprecated.>  Use Chained methods or other techniques.
 793 If you really depend on this, install the standalone
 794 L<Catalyst::DispatchType::Regex> distribution.
 795
 796 Like L</Regex> but scoped under the namespace of the containing controller
 797
 798 =head2 Chained
 799
 800 =head2 ChainedParent
 801
 802 =head2 PathPrefix
 803
 804 =head2 PathPart
 805
 806 =head2 CaptureArgs
 807
 808 Allowed values for CaptureArgs is a single integer (CaptureArgs(2), meaning two
 809 allowed) or you can declare a L<Moose>, L<MooseX::Types> or L<Type::Tiny>
 810 named constraint such as CaptureArgs(Int,Str) would require two args with
 811 the first being a Integer and the second a string.  You may declare your own
 812 custom type constraints and import them into the controller namespace:
 813
 814     package MyApp::Controller::Root;
 815
 816     use Moose;
 817     use MooseX::MethodAttributes;
 818     use MyApp::Types qw/Int/;
 819
 820     extends 'Catalyst::Controller';
 821
 822     sub chain_base :Chained(/) CaptureArgs(1) { }
 823
 824       sub any_priority_chain :Chained(chain_base) PathPart('') Args(1) { }
 825
 826       sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
 827
 828 See L<Catalyst::RouteMatching> for more.
 829
 830 Please see L<Catalyst::DispatchType::Chained> for more.
 831
 832 =head2 ActionClass
 833
 834 Set the base class for the action, defaults to L</Catalyst::Action>.  It is now
 835 preferred to use L</Does>.
 836
 837 =head2 MyAction
 838
 839 Set the ActionClass using a custom Action in your project namespace.
 840
 841 The following is exactly the same:
 842
 843     sub foo_action1 : Local ActionClass('+MyApp::Action::Bar') { ... }
 844     sub foo_action2 : Local MyAction('Bar') { ... }
 845
 846 =head2 Does
 847
 848     package MyApp::Controller::Zoo;
 849
 850     sub foo  : Local Does('Moo')  { ... } # Catalyst::ActionRole::
 851     sub bar  : Local Does('~Moo') { ... } # MyApp::ActionRole::Moo
 852     sub baz  : Local Does('+MyApp::ActionRole::Moo') { ... }
 853
 854 =head2 GET
 855
 856 =head2 POST
 857
 858 =head2 PUT
 859
 860 =head2 DELETE
 861
 862 =head2 OPTION
 863
 864 =head2 HEAD
 865
 866 =head2 PATCH
 867
 868 =head2 Method('...')
 869
 870 Sets the give action path to match the specified HTTP method, or via one of the
 871 broadly accepted methods of overriding the 'true' method (see
 872 L<Catalyst::ActionRole::HTTPMethods>).
 873
 874 =head2 Args
 875
 876 When used with L</Path> indicates the number of arguments expected in
 877 the path.  However if no Args value is set, assumed to 'slurp' all
 878 remaining path pars under this namespace.
 879
 880 Allowed values for Args is a single integer (Args(2), meaning two allowed) or you
 881 can declare a L<Moose>, L<MooseX::Types> or L<Type::Tiny> named constraint such
 882 as Args(Int,Str) would require two args with the first being a Integer and the
 883 second a string.  You may declare your own custom type constraints and import
 884 them into the controller namespace:
 885
 886     package MyApp::Controller::Root;
 887
 888     use Moose;
 889     use MooseX::MethodAttributes;
 890     use MyApp::Types qw/Tuple Int Str StrMatch UserId/;
 891
 892     extends 'Catalyst::Controller';
 893
 894     sub user :Local Args(UserId) {
 895       my ($self, $c, $int) = @_;
 896     }
 897
 898     sub an_int :Local Args(Int) {
 899       my ($self, $c, $int) = @_;
 900     }
 901
 902     sub many_ints :Local Args(ArrayRef[Int]) {
 903       my ($self, $c, @ints) = @_;
 904     }
 905
 906     sub match :Local Args(StrMatch[qr{\d\d-\d\d-\d\d}]) {
 907       my ($self, $c, $int) = @_;
 908     }
 909
 910 If you choose not to use imported type constraints (like L<Type::Tiny>, or <MooseX::Types>
 911 you may use L<Moose> 'stringy' types however just like when you use these types in your
 912 declared attributes you must quote them:
 913
 914     sub my_moose_type :Local Args('Int') { ... }
 915
 916 If you use 'reference' type constraints (such as ArrayRef[Int]) that have an unknown
 917 number of allowed matches, we set this the same way "Args" is.  Please keep in mind
 918 that actions with an undetermined number of args match at lower precedence than those
 919 with a fixed number.  You may use reference types such as Tuple from L<Types::Standard>
 920 that allows you to fix the number of allowed args.  For example Args(Tuple[Int,Int])
 921 would be determined to be two args (or really the same as Args(Int,Int).)  You may
 922 find this useful for creating custom subtypes with complex matching rules that you
 923 wish to reuse over many actions.
 924
 925 See L<Catalyst::RouteMatching> for more.
 926
 927 B<Note>: It is highly recommended to use L<Type::Tiny> for your type constraints over
 928 other options.  L<Type::Tiny> exposed a better meta data interface which allows us to
 929 do more and better types of introspection driving tests and debugging.
 930
 931 =head2 Consumes('...')
 932
 933 Matches the current action against the content-type of the request.  Typically
 934 this is used when the request is a POST or PUT and you want to restrict the
 935 submitted content type.  For example, you might have an HTML for that either
 936 returns classic url encoded form data, or JSON when Javascript is enabled.  In
 937 this case you may wish to match either incoming type to one of two different
 938 actions, for properly processing.
 939
 940 Examples:
 941
 942     sub is_json       : Chained('start') Consumes('application/json') { ... }
 943     sub is_urlencoded : Chained('start') Consumes('application/x-www-form-urlencoded') { ... }
 944     sub is_multipart  : Chained('start') Consumes('multipart/form-data') { ... }
 945
 946 To reduce boilerplate, we include the following content type shortcuts:
 947
 948 Examples
 949
 950       sub is_json       : Chained('start') Consume(JSON) { ... }
 951       sub is_urlencoded : Chained('start') Consumes(UrlEncoded) { ... }
 952       sub is_multipart  : Chained('start') Consumes(Multipart) { ... }
 953
 954 You may specify more than one match:
 955
 956       sub is_more_than_one
 957         : Chained('start')
 958         : Consumes('application/x-www-form-urlencoded')
 959         : Consumes('multipart/form-data')
 960
 961       sub is_more_than_one
 962         : Chained('start')
 963         : Consumes(UrlEncoded)
 964         : Consumes(Multipart)
 965
 966 Since it is a common case the shortcut C<HTMLForm> matches both
 967 'application/x-www-form-urlencoded' and 'multipart/form-data'.  Here's the full
 968 list of available shortcuts:
 969
 970     JSON => 'application/json',
 971     JS => 'application/javascript',
 972     PERL => 'application/perl',
 973     HTML => 'text/html',
 974     XML => 'text/XML',
 975     Plain => 'text/plain',
 976     UrlEncoded => 'application/x-www-form-urlencoded',
 977     Multipart => 'multipart/form-data',
 978     HTMLForm => ['application/x-www-form-urlencoded','multipart/form-data'],
 979
 980 Please keep in mind that when dispatching, L<Catalyst> will match the first most
 981 relevant case, so if you use the C<Consumes> attribute, you should place your
 982 most accurate matches early in the Chain, and your 'catchall' actions last.
 983
 984 See L<Catalyst::ActionRole::ConsumesContent> for more.
 985
 986 =head2 Scheme(...)
 987
 988 Allows you to specify a URI scheme for the action or action chain.  For example
 989 you can required that a given path be C<https> or that it is a websocket endpoint
 990 C<ws> or C<wss>.  For an action chain you may currently only have one defined
 991 Scheme.
 992
 993     package MyApp::Controller::Root;
 994
 995     use base 'Catalyst::Controller';
 996
 997     sub is_http :Path(scheme) Scheme(http) Args(0) {
 998       my ($self, $c) = @_;
 999       $c->response->body("is_http");
1000     }
1001
1002     sub is_https :Path(scheme) Scheme(https) Args(0)  {
1003       my ($self, $c) = @_;
1004       $c->response->body("is_https");
1005     }
1006
1007 In the above example http://localhost/root/scheme would match the first
1008 action (is_http) but https://localhost/root/scheme would match the second.
1009
1010 As an added benefit, if an action or action chain defines a Scheme, when using
1011 $c->uri_for the scheme of the generated URL will use what you define in the action
1012 or action chain (the current behavior is to set the scheme based on the current
1013 incoming request).  This makes it easier to use uri_for on websites where some
1014 paths are secure and others are not.  You may also use this to other schemes
1015 like websockets.
1016
1017 See L<Catalyst::ActionRole::Scheme> for more.
1018
1019 =head1 OPTIONAL METHODS
1020
1021 =head2 _parse_[$name]_attr
1022
1023 Allows you to customize parsing of subroutine attributes.
1024
1025     sub myaction1 :Path TwoArgs { ... }
1026
1027     sub _parse_TwoArgs_attr {
1028       my ( $self, $c, $name, $value ) = @_;
1029       # $self -> controller instance
1030       #
1031       return(Args => 2);
1032     }
1033
1034 Please note that this feature does not let you actually assign new functions
1035 to actions via subroutine attributes, but is really more for creating useful
1036 aliases to existing core and extended attributes, and transforms based on
1037 existing information (like from configuration).  Code for actually doing
1038 something meaningful with the subroutine attributes will be located in the
1039 L<Catalyst::Action> classes (or your subclasses), L<Catalyst::Dispatcher> and
1040 in subclasses of L<Catalyst::DispatchType>.  Remember these methods only get
1041 called basically once when the application is starting, not per request!
1042
1043 =head1 AUTHORS
1044
1045 Catalyst Contributors, see Catalyst.pm
1046
1047 =head1 COPYRIGHT
1048
1049 This library is free software. You can redistribute it and/or modify
1050 it under the same terms as Perl itself.
1051
1052 =cut