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;
19 # do these belong as package vars or should we build these via a builder method?
20 # See Catalyst-Plugin-Server for them being added to, which should be much less ugly.
22 # Preload these action types
23 our @PRELOAD = qw/Index Path Regex/;
25 # Postload these action types
26 our @POSTLOAD = qw/Default/;
28 # Note - see back-compat methods at end of file.
29 has _tree => (is => 'rw');
30 has _dispatch_types => (is => 'rw', default => sub { [] }, required => 1, lazy => 1);
31 has _registered_dispatch_types => (is => 'rw', default => sub { {} }, required => 1, lazy => 1);
32 has _method_action_class => (is => 'rw', default => 'Catalyst::Action');
33 has _action_hash => (is => 'rw', required => 1, lazy => 1, default => sub { {} });
34 has _container_hash => (is => 'rw', required => 1, lazy => 1, default => sub { {} });
36 has preload_dispatch_types => (is => 'rw', required => 1, lazy => 1, default => sub { [@PRELOAD] });
37 has postload_dispatch_types => (is => 'rw', required => 1, lazy => 1, default => sub { [@POSTLOAD] });
39 # Wrap accessors so you can assign a list and it will capture a list ref.
40 around qw/preload_dispatch_types postload_dispatch_types/ => sub {
43 return $self->$orig([@_]) if (scalar @_ && ref $_[0] ne 'ARRAY');
44 return $self->$orig(@_);
51 Catalyst::Dispatcher - The Catalyst Dispatcher
59 This is the class that maps public urls to actions in your Catalyst
60 application based on the attributes you set.
66 Construct a new dispatcher.
71 my ($self, $params) = @_;
74 Catalyst::ActionContainer->new( { part => '/', actions => {} } );
76 $self->_tree( Tree::Simple->new( $container, Tree::Simple->ROOT ) );
79 =head2 $self->preload_dispatch_types
81 An arrayref of pre-loaded dispatchtype classes
83 Entries are considered to be available as C<Catalyst::DispatchType::CLASS>
84 To use a custom class outside the regular C<Catalyst> namespace, prefix
85 it with a C<+>, like so:
89 =head2 $self->postload_dispatch_types
91 An arrayref of post-loaded dispatchtype classes
93 Entries are considered to be available as C<Catalyst::DispatchType::CLASS>
94 To use a custom class outside the regular C<Catalyst> namespace, prefix
95 it with a C<+>, like so:
99 =head2 $self->dispatch($c)
101 Delegate the dispatch to the action that matched the url, or return a
102 message about unknown resource
107 my ( $self, $c ) = @_;
108 if ( my $action = $c->action ) {
109 $c->forward( join( '/', '', $action->namespace, '_DISPATCH' ) );
112 my $path = $c->req->path;
114 ? qq/Unknown resource "$path"/
115 : "No default action defined";
116 $c->log->error($error) if $c->debug;
121 # $self->_command2action( $c, $command [, \@arguments ] )
122 # Search for an action, from the command and returns C<($action, $args)> on
123 # success. Returns C<(0)> on error.
125 sub _command2action {
126 my ( $self, $c, $command, @extra_params ) = @_;
129 $c->log->debug('Nothing to go to') if $c->debug;
135 if ( ref( $extra_params[-1] ) eq 'ARRAY' ) {
136 @args = @{ pop @extra_params }
138 # this is a copy, it may take some abuse from
139 # ->_invoke_as_path if the path had trailing parts
140 @args = @{ $c->request->arguments };
145 # go to a string path ("/foo/bar/gorch")
147 if (blessed($command) && $command->isa('Catalyst::Action')) {
151 $action = $self->_invoke_as_path( $c, "$command", \@args );
154 # go to a component ( "MyApp::*::Foo" or $c->component("...")
155 # - a path or an object)
157 my $method = @extra_params ? $extra_params[0] : "process";
158 $action = $self->_invoke_as_component( $c, $command, $method );
161 return $action, \@args;
164 =head2 $self->visit( $c, $command [, \@arguments ] )
166 Documented in L<Catalyst>
172 $self->_do_visit('visit', @_);
178 my ( $c, $command ) = @_;
179 my ( $action, $args ) = $self->_command2action(@_);
180 my $error = qq/Couldn't $opname("$command"): /;
183 $error .= qq/Couldn't $opname to command "$command": /
184 .qq/Invalid action or component./;
186 elsif (!defined $action->namespace) {
187 $error .= qq/Action has no namespace: cannot $opname() to a plain /
188 .qq/method or component, must be a :Action or some sort./
190 elsif (!$action->class->can('_DISPATCH')) {
191 $error .= qq/Action cannot _DISPATCH. /
192 .qq/Did you try to $opname() a non-controller action?/;
200 $c->log->debug($error) if $c->debug;
204 $action = $self->expand_action($action);
206 local $c->request->{arguments} = $args;
207 local $c->{namespace} = $action->{'namespace'};
208 local $c->{action} = $action;
213 =head2 $self->go( $c, $command [, \@arguments ] )
215 Documented in L<Catalyst>
221 $self->_do_visit('go', @_);
225 =head2 $self->forward( $c, $command [, \@arguments ] )
227 Documented in L<Catalyst>
233 $self->_do_forward(forward => @_);
239 my ( $c, $command ) = @_;
240 my ( $action, $args ) = $self->_command2action(@_);
243 my $error .= qq/Couldn't $opname to command "$command": /
244 .qq/Invalid action or component./;
246 $c->log->debug($error) if $c->debug;
250 no warnings 'recursion';
252 local $c->request->{arguments} = $args;
253 $action->dispatch( $c );
258 =head2 $self->detach( $c, $command [, \@arguments ] )
260 Documented in L<Catalyst>
265 my ( $self, $c, $command, @args ) = @_;
266 $self->_do_forward(detach => $c, $command, @args ) if $command;
267 die $Catalyst::DETACH;
270 sub _action_rel2abs {
271 my ( $self, $c, $path ) = @_;
273 unless ( $path =~ m#^/# ) {
274 my $namespace = $c->stack->[-1]->namespace;
275 $path = "$namespace/$path";
282 sub _invoke_as_path {
283 my ( $self, $c, $rel_path, $args ) = @_;
285 my $path = $self->_action_rel2abs( $c, $rel_path );
287 my ( $tail, @extra_args );
288 while ( ( $path, $tail ) = ( $path =~ m#^(?:(.*)/)?(\w+)?$# ) )
289 { # allow $path to be empty
290 if ( my $action = $c->get_action( $tail, $path ) ) {
291 push @$args, @extra_args;
297 ; # if a match on the global namespace failed then the whole lookup failed
300 unshift @extra_args, $tail;
304 sub _find_component_class {
305 my ( $self, $c, $component ) = @_;
307 return ref($component)
308 || ref( $c->component($component) )
309 || $c->component($component);
312 sub _invoke_as_component {
313 my ( $self, $c, $component, $method ) = @_;
315 my $class = $self->_find_component_class( $c, $component ) || return 0;
317 if ( my $code = $class->can($method) ) {
318 return $self->_method_action_class->new(
322 reverse => "$class->$method",
324 namespace => Catalyst::Utils::class2prefix(
325 $class, $c->config->{case_sensitive}
332 qq/Couldn't forward to "$class". Does not implement "$method"/;
334 $c->log->debug($error)
340 =head2 $self->prepare_action($c)
342 Find an dispatch type that matches $c->req->path, and set args from it.
347 my ( $self, $c ) = @_;
349 my $path = $req->path;
350 my @path = split /\//, $req->path;
351 $req->args( \my @args );
353 unshift( @path, '' ); # Root action
355 DESCEND: while (@path) {
356 $path = join '/', @path;
359 $path = '' if $path eq '/'; # Root action
361 # Check out dispatch types to see if any will handle the path at
364 foreach my $type ( @{ $self->_dispatch_types } ) {
365 last DESCEND if $type->match( $c, $path );
368 # If not, move the last part path to args
369 my $arg = pop(@path);
370 $arg =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
374 s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg for grep { defined } @{$req->captures||[]};
376 $c->log->debug( 'Path is "' . $req->match . '"' )
377 if ( $c->debug && defined $req->match && length $req->match );
379 $c->log->debug( 'Arguments are "' . join( '/', @args ) . '"' )
380 if ( $c->debug && @args );
383 =head2 $self->get_action( $action, $namespace )
385 returns a named action from a given namespace.
390 my ( $self, $name, $namespace ) = @_;
393 $namespace = join( "/", grep { length } split '/', ( defined $namespace ? $namespace : "" ) );
395 return $self->_action_hash->{"${namespace}/${name}"};
398 =head2 $self->get_action_by_path( $path );
400 Returns the named action by its full path.
404 sub get_action_by_path {
405 my ( $self, $path ) = @_;
407 $path = "/$path" unless $path =~ /\//;
408 $self->_action_hash->{$path};
411 =head2 $self->get_actions( $c, $action, $namespace )
416 my ( $self, $c, $action, $namespace ) = @_;
417 return [] unless $action;
419 $namespace = join( "/", grep { length } split '/', $namespace || "" );
421 my @match = $self->get_containers($namespace);
423 return map { $_->get_action($action) } @match;
426 =head2 $self->get_containers( $namespace )
428 Return all the action containers for a given namespace, inclusive
433 my ( $self, $namespace ) = @_;
435 $namespace = '' if $namespace eq '/';
439 if ( length $namespace ) {
441 push @containers, $self->_container_hash->{$namespace};
442 } while ( $namespace =~ s#/[^/]+$## );
445 return reverse grep { defined } @containers, $self->_container_hash->{''};
447 #return (split '/', $namespace); # isnt this more clear?
448 my @parts = split '/', $namespace;
451 =head2 $self->uri_for_action($action, \@captures)
453 Takes a Catalyst::Action object and action parameters and returns a URI
454 part such that if $c->req->path were this URI part, this action would be
455 dispatched to with $c->req->captures set to the supplied arrayref.
457 If the action object is not available for external dispatch or the dispatcher
458 cannot determine an appropriate URI, this method will return undef.
463 my ( $self, $action, $captures) = @_;
465 foreach my $dispatch_type ( @{ $self->_dispatch_types } ) {
466 my $uri = $dispatch_type->uri_for_action( $action, $captures );
467 return( $uri eq '' ? '/' : $uri )
475 expand an action into a full representation of the dispatch.
476 mostly useful for chained, other actions will just return a
482 my ($self, $action) = @_;
484 foreach my $dispatch_type (@{ $self->_dispatch_types }) {
485 my $expanded = $dispatch_type->expand_action($action);
486 return $expanded if $expanded;
492 =head2 $self->register( $c, $action )
494 Make sure all required dispatch types for this action are loaded, then
495 pass the action to our dispatch types so they can register it if required.
496 Also, set up the tree with the action containers.
501 my ( $self, $c, $action ) = @_;
503 my $registered = $self->_registered_dispatch_types;
505 #my $priv = 0; #seems to be unused
506 foreach my $key ( keys %{ $action->attributes } ) {
507 next if $key eq 'Private';
508 my $class = "Catalyst::DispatchType::$key";
509 unless ( $registered->{$class} ) {
510 # FIXME - Some error checking and re-throwing needed here, as
511 # we eat exceptions loading dispatch types.
512 eval { Class::MOP::load_class($class) };
513 push( @{ $self->_dispatch_types }, $class->new ) unless $@;
514 $registered->{$class} = 1;
518 # Pass the action to our dispatch types so they can register it if reqd.
519 foreach my $type ( @{ $self->_dispatch_types } ) {
520 $type->register( $c, $action );
523 my $namespace = $action->namespace;
524 my $name = $action->name;
526 my $container = $self->_find_or_create_action_container($namespace);
528 # Set the method value
529 $container->add_action($action);
531 $self->_action_hash->{"$namespace/$name"} = $action;
532 $self->_container_hash->{$namespace} = $container;
535 sub _find_or_create_action_container {
536 my ( $self, $namespace ) = @_;
538 my $tree ||= $self->_tree;
540 return $tree->getNodeValue unless $namespace;
542 my @namespace = split '/', $namespace;
543 return $self->_find_or_create_namespace_node( $tree, @namespace )
547 sub _find_or_create_namespace_node {
548 my ( $self, $parent, $part, @namespace ) = @_;
550 return $parent unless $part;
553 ( grep { $_->getNodeValue->part eq $part } $parent->getAllChildren )[0];
556 my $container = Catalyst::ActionContainer->new($part);
557 $parent->addChild( $child = Tree::Simple->new($container) );
560 $self->_find_or_create_namespace_node( $child, @namespace );
563 =head2 $self->setup_actions( $class, $context )
565 Loads all of the preload dispatch types, registers their actions and then
566 loads all of the postload dispatch types, and iterates over the tree of
567 actions, displaying the debug information if appropriate.
572 my ( $self, $c ) = @_;
575 $self->_load_dispatch_types( @{ $self->preload_dispatch_types } );
576 @{ $self->_registered_dispatch_types }{@classes} = (1) x @classes;
578 foreach my $comp ( values %{ $c->components } ) {
579 $comp->register_actions($c) if $comp->can('register_actions');
582 $self->_load_dispatch_types( @{ $self->postload_dispatch_types } );
584 return unless $c->debug;
586 my $column_width = Catalyst::Utils::term_width() - 20 - 36 - 12;
587 my $privates = Text::SimpleTable->new(
588 [ 20, 'Private' ], [ 36, 'Class' ], [ $column_width, 'Method' ]
593 my ( $walker, $parent, $prefix ) = @_;
594 $prefix .= $parent->getNodeValue || '';
595 $prefix .= '/' unless $prefix =~ /\/$/;
596 my $node = $parent->getNodeValue->actions;
598 for my $action ( keys %{$node} ) {
599 my $action_obj = $node->{$action};
601 if ( ( $action =~ /^_.*/ )
602 && ( !$c->config->{show_internal_actions} ) );
603 $privates->row( "$prefix$action", $action_obj->class, $action );
607 $walker->( $walker, $_, $prefix ) for $parent->getAllChildren;
610 $walker->( $walker, $self->_tree, '' );
611 $c->log->debug( "Loaded Private actions:\n" . $privates->draw . "\n" )
614 # List all public actions
615 $_->list($c) for @{ $self->_dispatch_types };
618 sub _load_dispatch_types {
619 my ( $self, @types ) = @_;
623 # Preload action types
624 for my $type (@types) {
626 ( $type =~ /^\+(.*)$/ ) ? $1 : "Catalyst::DispatchType::${type}";
628 eval { Class::MOP::load_class($class) };
629 Catalyst::Exception->throw( message => qq/Couldn't load "$class"/ )
631 push @{ $self->_dispatch_types }, $class->new;
633 push @loaded, $class;
641 # 5.70 backwards compatibility hacks.
643 # Various plugins (e.g. Plugin::Server and Plugin::Authorization::ACL)
644 # need the methods here which *should* be private..
646 # However we can't really take them away until there is a sane API for
647 # building actions and configuring / introspecting the dispatcher.
648 # In 5.90, we should build that infrastructure, port the plugins which
649 # use it, and then take the crap below away.
650 # See also t/lib/TestApp/Plugin/AddDispatchTypes.pm
652 # Alias _method_name to method_name, add a before modifier to warn..
653 foreach my $public_method_name (qw/
656 registered_dispatch_types
661 my $private_method_name = '_' . $public_method_name;
662 my $meta = __PACKAGE__->meta; # Calling meta method here fine as we happen at compile time.
663 $meta->add_method($public_method_name, $meta->get_method($private_method_name));
665 my %package_hash; # Only warn once per method, per package. These are infrequent enough that
666 # I haven't provided a way to disable them, patches welcome.
667 $meta->add_before_method_modifier($public_method_name, sub {
668 my $class = blessed(shift);
669 $package_hash{$class}++ || do {
670 warn("Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,\n"
671 . "this will be removed in Catalyst 5.9X");
676 # End 5.70 backwards compatibility hacks.
679 __PACKAGE__->meta->make_immutable;
687 Catalyst Contributors, see Catalyst.pm
691 This program is free software, you can redistribute it and/or modify it under
692 the same terms as Perl itself.