1 package Catalyst::Dispatcher;
5 with 'MooseX::Emulate::Class::Accessor::Fast';
7 use Catalyst::Exception;
10 use Catalyst::ActionContainer;
11 use Catalyst::DispatchType::Default;
12 use Catalyst::DispatchType::Index;
14 use Text::SimpleTable;
16 use Tree::Simple::Visitor::FindByPath;
17 use Class::Load qw(load_class try_load_class);
18 use Encode 2.21 'decode_utf8';
20 use namespace::clean -except => 'meta';
23 # do these belong as package vars or should we build these via a builder method?
24 # See Catalyst-Plugin-Server for them being added to, which should be much less ugly.
26 # Preload these action types
27 our @PRELOAD = qw/Index Path/;
29 # Postload these action types
30 our @POSTLOAD = qw/Default/;
32 # Note - see back-compat methods at end of file.
33 has _tree => (is => 'rw', builder => '_build__tree');
34 has dispatch_types => (is => 'rw', default => sub { [] }, required => 1, lazy => 1);
35 has _registered_dispatch_types => (is => 'rw', default => sub { {} }, required => 1, lazy => 1);
36 has _method_action_class => (is => 'rw', default => 'Catalyst::Action');
37 has _action_hash => (is => 'rw', required => 1, lazy => 1, default => sub { {} });
38 has _container_hash => (is => 'rw', required => 1, lazy => 1, default => sub { {} });
40 my %dispatch_types = ( pre => \@PRELOAD, post => \@POSTLOAD );
41 foreach my $type (keys %dispatch_types) {
42 has $type . "load_dispatch_types" => (
43 is => 'rw', required => 1, lazy => 1, default => sub { $dispatch_types{$type} },
44 traits => ['MooseX::Emulate::Class::Accessor::Fast::Meta::Role::Attribute'], # List assignment is CAF style
50 Catalyst::Dispatcher - The Catalyst Dispatcher
58 This is the class that maps public urls to actions in your Catalyst
59 application based on the attributes you set.
65 Construct a new dispatcher.
73 Catalyst::ActionContainer->new( { part => '/', actions => {} } );
75 return Tree::Simple->new($container, Tree::Simple->ROOT);
78 =head2 $self->preload_dispatch_types
80 An arrayref of pre-loaded dispatchtype classes
82 Entries are considered to be available as C<Catalyst::DispatchType::CLASS>
83 To use a custom class outside the regular C<Catalyst> namespace, prefix
84 it with a C<+>, like so:
88 =head2 $self->postload_dispatch_types
90 An arrayref of post-loaded dispatchtype classes
92 Entries are considered to be available as C<Catalyst::DispatchType::CLASS>
93 To use a custom class outside the regular C<Catalyst> namespace, prefix
94 it with a C<+>, like so:
98 =head2 $self->dispatch($c)
100 Delegate the dispatch to the action that matched the url, or return a
101 message about unknown resource
106 my ( $self, $c ) = @_;
107 if ( my $action = $c->action ) {
108 $c->forward( join( '/', '', $action->namespace, '_DISPATCH' ) );
111 my $path = $c->req->path;
112 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
113 $path = decode_utf8($path);
116 ? qq/Unknown resource "$path"/
117 : "No default action defined";
118 $c->log->error($error) if $c->debug;
123 # $self->_command2action( $c, $command [, \@arguments ] )
124 # $self->_command2action( $c, $command [, \@captures, \@arguments ] )
125 # Search for an action, from the command and returns C<($action, $args, $captures)> on
126 # success. Returns C<(0)> on error.
128 sub _command2action {
129 my ( $self, $c, $command, @extra_params ) = @_;
132 $c->log->debug('Nothing to go to') if $c->debug;
136 my (@args, @captures);
138 if ( ref( $extra_params[-2] ) eq 'ARRAY' ) {
139 @captures = @{ splice @extra_params, -2, 1 };
142 if ( ref( $extra_params[-1] ) eq 'ARRAY' ) {
143 @args = @{ pop @extra_params }
145 # this is a copy, it may take some abuse from
146 # ->_invoke_as_path if the path had trailing parts
147 @args = @{ $c->request->arguments };
152 # go to a string path ("/foo/bar/gorch")
154 if (blessed($command) && $command->isa('Catalyst::Action')) {
158 $action = $self->_invoke_as_path( $c, "$command", \@args );
161 # go to a component ( "View::Foo" or $c->component("...")
162 # - a path or an object)
164 my $method = @extra_params ? $extra_params[0] : "process";
165 $action = $self->_invoke_as_component( $c, $command, $method );
168 return $action, \@args, \@captures;
171 =head2 $self->visit( $c, $command [, \@arguments ] )
173 Documented in L<Catalyst>
179 $self->_do_visit('visit', @_);
185 my ( $c, $command ) = @_;
186 my ( $action, $args, $captures ) = $self->_command2action(@_);
187 my $error = qq/Couldn't $opname("$command"): /;
190 $error .= qq/Couldn't $opname to command "$command": /
191 .qq/Invalid action or component./;
193 elsif (!defined $action->namespace) {
194 $error .= qq/Action has no namespace: cannot $opname() to a plain /
195 .qq/method or component, must be an :Action of some sort./
197 elsif (!$action->class->can('_DISPATCH')) {
198 $error .= qq/Action cannot _DISPATCH. /
199 .qq/Did you try to $opname() a non-controller action?/;
207 $c->log->debug($error) if $c->debug;
211 $action = $self->expand_action($action);
213 local $c->request->{arguments} = $args;
214 local $c->request->{captures} = $captures;
215 local $c->{namespace} = $action->{'namespace'};
216 local $c->{action} = $action;
221 =head2 $self->go( $c, $command [, \@arguments ] )
223 Documented in L<Catalyst>
229 $self->_do_visit('go', @_);
230 Catalyst::Exception::Go->throw;
233 =head2 $self->forward( $c, $command [, \@arguments ] )
235 Documented in L<Catalyst>
241 no warnings 'recursion';
242 $self->_do_forward(forward => @_);
248 my ( $c, $command ) = @_;
249 my ( $action, $args, $captures ) = $self->_command2action(@_);
252 my $error .= qq/Couldn't $opname to command "$command": /
253 .qq/Invalid action or component./;
255 $c->log->debug($error) if $c->debug;
260 local $c->request->{arguments} = $args;
261 no warnings 'recursion';
262 $action->dispatch( $c );
267 =head2 $self->detach( $c, $command [, \@arguments ] )
269 Documented in L<Catalyst>
274 my ( $self, $c, $command, @args ) = @_;
275 $self->_do_forward(detach => $c, $command, @args ) if $command;
276 $c->state(0); # Needed in order to skip any auto functions
277 Catalyst::Exception::Detach->throw;
280 sub _action_rel2abs {
281 my ( $self, $c, $path ) = @_;
283 unless ( $path =~ m#^/# ) {
284 my $namespace = $c->stack->[-1]->namespace;
285 $path = "$namespace/$path";
292 sub _invoke_as_path {
293 my ( $self, $c, $rel_path, $args ) = @_;
295 my $path = $self->_action_rel2abs( $c, $rel_path );
297 my ( $tail, @extra_args );
298 while ( ( $path, $tail ) = ( $path =~ m#^(?:(.*)/)?(\w+)?$# ) )
299 { # allow $path to be empty
300 if ( my $action = $c->get_action( $tail, $path ) ) {
301 push @$args, @extra_args;
307 ; # if a match on the global namespace failed then the whole lookup failed
310 unshift @extra_args, $tail;
314 sub _find_component {
315 my ( $self, $c, $component ) = @_;
317 # fugly, why doesn't ->component('MyApp') work?
318 return $c if ($component eq blessed($c));
320 return blessed($component)
322 : $c->component($component);
325 sub _invoke_as_component {
326 my ( $self, $c, $component_or_class, $method ) = @_;
328 my $component = $self->_find_component($c, $component_or_class);
329 my $component_class = blessed $component || return 0;
331 if (my $code = $component_class->can('action_for')) {
332 my $possible_action = $component->$code($method);
333 return $possible_action if $possible_action;
336 if ( my $code = $component_class->can($method) ) {
337 return $self->_method_action_class->new(
341 reverse => "$component_class->$method",
342 class => $component_class,
343 namespace => Catalyst::Utils::class2prefix(
344 $component_class, ref($c)->config->{case_sensitive}
351 qq/Couldn't forward to "$component_class". Does not implement "$method"/;
353 $c->log->debug($error)
359 =head2 $self->prepare_action($c)
361 Find an dispatch type that matches $c->req->path, and set args from it.
366 my ( $self, $c ) = @_;
368 my $path = $req->path;
369 my @path = split /\//, $req->path;
370 $req->args( \my @args );
372 unshift( @path, '' ); # Root action
374 DESCEND: while (@path) {
375 $path = join '/', @path;
378 # Check out dispatch types to see if any will handle the path at
381 foreach my $type ( @{ $self->dispatch_types } ) {
382 last DESCEND if $type->match( $c, $path );
385 # If not, move the last part path to args
386 my $arg = pop(@path);
387 $arg =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
391 s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg for grep { defined } @{$req->captures||[]};
393 if($c->debug && defined $req->match && length $req->match) {
394 my $match = $req->match;
395 $match =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
396 $match = decode_utf8($match);
397 $c->log->debug( 'Path is "' . $match . '"' )
400 $c->log->debug( 'Arguments are "' . join( '/', map { decode_utf8 $_ } @args ) . '"' )
401 if ( $c->debug && @args );
404 =head2 $self->get_action( $action, $namespace )
406 returns a named action from a given namespace.
411 my ( $self, $name, $namespace ) = @_;
414 $namespace = join( "/", grep { length } split '/', ( defined $namespace ? $namespace : "" ) );
416 return $self->_action_hash->{"${namespace}/${name}"};
419 =head2 $self->get_action_by_path( $path );
421 Returns the named action by its full private path.
425 sub get_action_by_path {
426 my ( $self, $path ) = @_;
428 $path = "/$path" unless $path =~ /\//;
429 $self->_action_hash->{$path};
432 =head2 $self->get_actions( $c, $action, $namespace )
437 my ( $self, $c, $action, $namespace ) = @_;
438 return [] unless $action;
440 $namespace = join( "/", grep { length } split '/', $namespace || "" );
442 my @match = $self->get_containers($namespace);
444 return map { $_->get_action($action) } @match;
447 =head2 $self->get_containers( $namespace )
449 Return all the action containers for a given namespace, inclusive
454 my ( $self, $namespace ) = @_;
456 $namespace = '' if $namespace eq '/';
460 if ( length $namespace ) {
462 push @containers, $self->_container_hash->{$namespace};
463 } while ( $namespace =~ s#/[^/]+$## );
466 return reverse grep { defined } @containers, $self->_container_hash->{''};
469 =head2 $self->uri_for_action($action, \@captures)
471 Takes a Catalyst::Action object and action parameters and returns a URI
472 part such that if $c->req->path were this URI part, this action would be
473 dispatched to with $c->req->captures set to the supplied arrayref.
475 If the action object is not available for external dispatch or the dispatcher
476 cannot determine an appropriate URI, this method will return undef.
481 my ( $self, $action, $captures) = @_;
483 foreach my $dispatch_type ( @{ $self->dispatch_types } ) {
484 my $uri = $dispatch_type->uri_for_action( $action, $captures );
485 return( $uri eq '' ? '/' : $uri )
493 expand an action into a full representation of the dispatch.
494 mostly useful for chained, other actions will just return a
500 my ($self, $action) = @_;
502 foreach my $dispatch_type (@{ $self->dispatch_types }) {
503 my $expanded = $dispatch_type->expand_action($action);
504 return $expanded if $expanded;
510 =head2 $self->register( $c, $action )
512 Make sure all required dispatch types for this action are loaded, then
513 pass the action to our dispatch types so they can register it if required.
514 Also, set up the tree with the action containers.
519 my ( $self, $c, $action ) = @_;
521 my $registered = $self->_registered_dispatch_types;
523 foreach my $key ( keys %{ $action->attributes } ) {
524 next if $key eq 'Private';
525 my $class = "Catalyst::DispatchType::$key";
526 unless ( $registered->{$class} ) {
527 # FIXME - Some error checking and re-throwing needed here, as
528 # we eat exceptions loading dispatch types.
529 # see also try_load_class
530 eval { load_class($class) };
531 my $load_failed = $@;
532 $self->_check_deprecated_dispatch_type( $key, $load_failed );
533 push( @{ $self->dispatch_types }, $class->new ) unless $load_failed;
534 $registered->{$class} = 1;
538 my @dtypes = @{ $self->dispatch_types };
540 my @low_precedence_dtypes;
542 for my $type ( @dtypes ) {
543 if ($type->_is_low_precedence) {
544 push @low_precedence_dtypes, $type;
546 push @normal_dtypes, $type;
550 # Pass the action to our dispatch types so they can register it if reqd.
551 my $was_registered = 0;
552 foreach my $type ( @normal_dtypes ) {
553 $was_registered = 1 if $type->register( $c, $action );
556 if (not $was_registered) {
557 foreach my $type ( @low_precedence_dtypes ) {
558 $type->register( $c, $action );
562 my $namespace = $action->namespace;
563 my $name = $action->name;
565 my $container = $self->_find_or_create_action_container($namespace);
567 # Set the method value
568 $container->add_action($action);
570 $self->_action_hash->{"$namespace/$name"} = $action;
571 $self->_container_hash->{$namespace} = $container;
574 sub _find_or_create_action_container {
575 my ( $self, $namespace ) = @_;
577 my $tree ||= $self->_tree;
579 return $tree->getNodeValue unless $namespace;
581 my @namespace = split '/', $namespace;
582 return $self->_find_or_create_namespace_node( $tree, @namespace )
586 sub _find_or_create_namespace_node {
587 my ( $self, $parent, $part, @namespace ) = @_;
589 return $parent unless $part;
592 ( grep { $_->getNodeValue->part eq $part } $parent->getAllChildren )[0];
595 my $container = Catalyst::ActionContainer->new($part);
596 $parent->addChild( $child = Tree::Simple->new($container) );
599 $self->_find_or_create_namespace_node( $child, @namespace );
602 =head2 $self->setup_actions( $class, $context )
604 Loads all of the pre-load dispatch types, registers their actions and then
605 loads all of the post-load dispatch types, and iterates over the tree of
606 actions, displaying the debug information if appropriate.
611 my ( $self, $c ) = @_;
614 $self->_load_dispatch_types( @{ $self->preload_dispatch_types } );
615 @{ $self->_registered_dispatch_types }{@classes} = (1) x @classes;
617 foreach my $comp ( values %{ $c->components } ) {
618 $comp = $comp->() if ref($comp) eq 'CODE';
619 $comp->register_actions($c) if $comp->can('register_actions');
622 $self->_load_dispatch_types( @{ $self->postload_dispatch_types } );
624 return unless $c->debug;
625 $self->_display_action_tables($c);
628 sub _display_action_tables {
631 my $avail_width = Catalyst::Utils::term_width() - 12;
632 my $col1_width = ($avail_width * .25) < 20 ? 20 : int($avail_width * .25);
633 my $col2_width = ($avail_width * .50) < 36 ? 36 : int($avail_width * .50);
634 my $col3_width = $avail_width - $col1_width - $col2_width;
635 my $privates = Text::SimpleTable->new(
636 [ $col1_width, 'Private' ], [ $col2_width, 'Class' ], [ $col3_width, 'Method' ]
641 my ( $walker, $parent, $prefix ) = @_;
642 $prefix .= $parent->getNodeValue || '';
643 $prefix .= '/' unless $prefix =~ /\/$/;
644 my $node = $parent->getNodeValue->actions;
646 for my $action ( keys %{$node} ) {
647 my $action_obj = $node->{$action};
649 if ( ( $action =~ /^_.*/ )
650 && ( !$c->config->{show_internal_actions} ) );
651 $privates->row( "$prefix$action", $action_obj->class, $action );
655 $walker->( $walker, $_, $prefix ) for $parent->getAllChildren;
658 $walker->( $walker, $self->_tree, '' );
659 $c->log->debug( "Loaded Private actions:\n" . $privates->draw . "\n" )
662 # List all public actions
663 $_->list($c) for @{ $self->dispatch_types };
666 sub _load_dispatch_types {
667 my ( $self, @types ) = @_;
670 # Preload action types
671 for my $type (@types) {
672 # first param is undef because we cannot get the appclass
673 my $class = Catalyst::Utils::resolve_namespace(undef, 'Catalyst::DispatchType', $type);
675 my ($success, $error) = try_load_class($class);
676 Catalyst::Exception->throw( message => $error ) if not $success;
677 push @{ $self->dispatch_types }, $class->new;
679 push @loaded, $class;
685 =head2 $self->dispatch_type( $type )
687 Get the DispatchType object of the relevant type, i.e. passing C<$type> of
688 C<Chained> would return a L<Catalyst::DispatchType::Chained> object (assuming
689 of course it's being used.)
694 my ($self, $name) = @_;
696 # first param is undef because we cannot get the appclass
697 $name = Catalyst::Utils::resolve_namespace(undef, 'Catalyst::DispatchType', $name);
699 for (@{ $self->dispatch_types }) {
700 return $_ if ref($_) eq $name;
705 sub _check_deprecated_dispatch_type {
706 my ($self, $key, $load_failed) = @_;
708 return unless $key =~ /^(Local)?Regexp?/;
710 # TODO: Should these throw an exception rather than just warning?
712 warn( "Attempt to use deprecated $key dispatch type.\n"
713 . " Use Chained methods or install the standalone\n"
714 . " Catalyst::DispatchType::Regex if necessary.\n" );
715 } elsif ( !defined $Catalyst::DispatchType::Regex::VERSION
716 || $Catalyst::DispatchType::Regex::VERSION le '5.90020' ) {
717 # We loaded the old core version of the Regex module this will break
718 warn( "The $key DispatchType has been removed from Catalyst core.\n"
719 . " An old version of the core Catalyst::DispatchType::Regex\n"
720 . " has been loaded and will likely fail. Please remove\n"
721 . " $INC{'Catalyst/DispatchType/Regex.pm'}\n"
722 . " and use Chained methods or install the standalone\n"
723 . " Catalyst::DispatchType::Regex if necessary.\n" );
729 # 5.70 backwards compatibility hacks.
731 # Various plugins (e.g. Plugin::Server and Plugin::Authorization::ACL)
732 # need the methods here which *should* be private..
734 # You should be able to use get_actions or get_containers appropriately
735 # instead of relying on these methods which expose implementation details
736 # of the dispatcher..
738 # IRC backlog included below, please come ask if this doesn't work for you.
740 # <@t0m> 5.80, the state of. There are things in the dispatcher which have
741 # been deprecated, that we yell at anyone for using, which there isn't
742 # a good alternative for yet..
743 # <@mst> er, get_actions/get_containers provides that doesn't it?
744 # <@mst> DispatchTypes are loaded on demand anyway
745 # <@t0m> I'm thinking of things like _tree which is aliased to 'tree' with
746 # warnings otherwise shit breaks.. We're issuing warnings about the
747 # correct set of things which you shouldn't be calling..
749 # <@mst> basically, I don't see there's a need for a replacement for anything
750 # <@mst> it was never a good idea to call ->tree
751 # <@mst> nothingmuch was the only one who did AFAIK
752 # <@mst> and he admitted it was a hack ;)
754 # See also t/lib/TestApp/Plugin/AddDispatchTypes.pm
756 # Alias _method_name to method_name, add a before modifier to warn..
757 foreach my $public_method_name (qw/
759 registered_dispatch_types
764 my $private_method_name = '_' . $public_method_name;
765 my $meta = __PACKAGE__->meta; # Calling meta method here fine as we happen at compile time.
766 $meta->add_method($public_method_name, $meta->get_method($private_method_name));
768 my %package_hash; # Only warn once per method, per package. These are infrequent enough that
769 # I haven't provided a way to disable them, patches welcome.
770 $meta->add_before_method_modifier($public_method_name, sub {
771 my $class = caller(2);
773 $package_hash{$class}++ || do {
774 warn("Class $class is calling the deprecated method\n"
775 . " Catalyst::Dispatcher::$public_method_name,\n"
776 . " this will be removed in Catalyst 5.9\n");
781 # End 5.70 backwards compatibility hacks.
783 __PACKAGE__->meta->make_immutable;
791 Catalyst Contributors, see Catalyst.pm
795 This library is free software. You can redistribute it and/or modify it under
796 the same terms as Perl itself.