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;
13 use Text::SimpleTable;
15 use Tree::Simple::Visitor::FindByPath;
18 #do these belong as package vars or should we build these via a builder method?
19 # Preload these action types
20 our @PRELOAD = qw/Index Path Regex/;
22 # Postload these action types
23 our @POSTLOAD = qw/Default/;
25 # FIXME - All of these should be _private attributes, and should have public accessors
26 # which warn about back-compat if you use them.
27 has tree => (is => 'rw');
28 has dispatch_types => (is => 'rw', default => sub { [] }, required => 1, lazy => 1);
29 has registered_dispatch_types => (is => 'rw', default => sub { {} }, required => 1, lazy => 1);
30 has method_action_class => (is => 'rw', default => 'Catalyst::Action');
31 has action_container_class => (is => 'rw', default => 'Catalyst::ActionContainer');
32 has action_hash => (is => 'rw', required => 1, lazy => 1, default => sub { {} });
33 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
108 my ( $self, $c ) = @_;
109 if ( my $action = $c->action ) {
110 $c->forward( join( '/', '', $action->namespace, '_DISPATCH' ) );
114 my $path = $c->req->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 # Search for an action, from the command and returns C<($action, $args)> on
125 # success. Returns C<(0)> on error.
127 sub _command2action {
128 my ( $self, $c, $command, @extra_params ) = @_;
131 $c->log->debug('Nothing to go to') if $c->debug;
137 if ( ref( $extra_params[-1] ) eq 'ARRAY' ) {
138 @args = @{ pop @extra_params }
140 # this is a copy, it may take some abuse from
141 # ->_invoke_as_path if the path had trailing parts
142 @args = @{ $c->request->arguments };
147 # go to a string path ("/foo/bar/gorch")
149 if (Scalar::Util::blessed($command) && $command->isa('Catalyst::Action')) {
153 $action = $self->_invoke_as_path( $c, "$command", \@args );
156 # go to a component ( "MyApp::*::Foo" or $c->component("...")
157 # - a path or an object)
159 my $method = @extra_params ? $extra_params[0] : "process";
160 $action = $self->_invoke_as_component( $c, $command, $method );
163 return $action, \@args;
166 =head2 $self->visit( $c, $command [, \@arguments ] )
168 Documented in L<Catalyst>
174 $self->_do_visit('visit', @_);
180 my ( $c, $command ) = @_;
181 my ( $action, $args ) = $self->_command2action(@_);
182 my $error = qq/Couldn't $opname("$command"): /;
185 $error .= qq/Couldn't $opname to command "$command": /
186 .qq/Invalid action or component./;
188 elsif (!defined $action->namespace) {
189 $error .= qq/Action has no namespace: cannot $opname() to a plain /
190 .qq/method or component, must be a :Action or some sort./
192 elsif (!$action->class->can('_DISPATCH')) {
193 $error .= qq/Action cannot _DISPATCH. /
194 .qq/Did you try to $opname() a non-controller action?/;
202 $c->log->debug($error) if $c->debug;
206 $action = $self->expand_action($action);
208 local $c->request->{arguments} = $args;
209 local $c->{namespace} = $action->{'namespace'};
210 local $c->{action} = $action;
215 =head2 $self->go( $c, $command [, \@arguments ] )
217 Documented in L<Catalyst>
223 $self->_do_visit('go', @_);
227 =head2 $self->forward( $c, $command [, \@arguments ] )
229 Documented in L<Catalyst>
235 $self->_do_forward(forward => @_);
241 my ( $c, $command ) = @_;
242 my ( $action, $args ) = $self->_command2action(@_);
245 my $error .= qq/Couldn't $opname to command "$command": /
246 .qq/Invalid action or component./;
248 $c->log->debug($error) if $c->debug;
252 no warnings 'recursion';
254 my $orig_args = $c->request->arguments();
255 $c->request->arguments($args);
256 $action->dispatch( $c );
257 $c->request->arguments($orig_args);
262 =head2 $self->detach( $c, $command [, \@arguments ] )
264 Documented in L<Catalyst>
269 my ( $self, $c, $command, @args ) = @_;
270 $self->_do_forward(detach => $c, $command, @args ) if $command;
271 die $Catalyst::DETACH;
274 sub _action_rel2abs {
275 my ( $self, $c, $path ) = @_;
277 unless ( $path =~ m#^/# ) {
278 my $namespace = $c->stack->[-1]->namespace;
279 $path = "$namespace/$path";
286 sub _invoke_as_path {
287 my ( $self, $c, $rel_path, $args ) = @_;
289 my $path = $self->_action_rel2abs( $c, $rel_path );
291 my ( $tail, @extra_args );
292 while ( ( $path, $tail ) = ( $path =~ m#^(?:(.*)/)?(\w+)?$# ) )
293 { # allow $path to be empty
294 if ( my $action = $c->get_action( $tail, $path ) ) {
295 push @$args, @extra_args;
301 ; # if a match on the global namespace failed then the whole lookup failed
304 unshift @extra_args, $tail;
308 sub _find_component_class {
309 my ( $self, $c, $component ) = @_;
311 return ref($component)
312 || ref( $c->component($component) )
313 || $c->component($component);
316 sub _invoke_as_component {
317 my ( $self, $c, $component, $method ) = @_;
319 my $class = $self->_find_component_class( $c, $component ) || return 0;
321 if ( my $code = $class->can($method) ) {
322 return $self->method_action_class->new(
326 reverse => "$class->$method",
328 namespace => Catalyst::Utils::class2prefix(
329 $class, $c->config->{case_sensitive}
336 qq/Couldn't forward to "$class". Does not implement "$method"/;
338 $c->log->debug($error)
344 =head2 $self->prepare_action($c)
346 Find an dispatch type that matches $c->req->path, and set args from it.
351 my ( $self, $c ) = @_;
353 my $path = $req->path;
354 my @path = split /\//, $req->path;
355 $req->args( \my @args );
357 unshift( @path, '' ); # Root action
359 DESCEND: while (@path) {
360 $path = join '/', @path;
363 $path = '' if $path eq '/'; # Root action
365 # Check out dispatch types to see if any will handle the path at
368 foreach my $type ( @{ $self->dispatch_types } ) {
369 last DESCEND if $type->match( $c, $path );
372 # If not, move the last part path to args
373 my $arg = pop(@path);
374 $arg =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
378 s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg for grep { defined } @{$req->captures||[]};
380 $c->log->debug( 'Path is "' . $req->match . '"' )
381 if ( $c->debug && defined $req->match && length $req->match );
383 $c->log->debug( 'Arguments are "' . join( '/', @args ) . '"' )
384 if ( $c->debug && @args );
387 =head2 $self->get_action( $action, $namespace )
389 returns a named action from a given namespace.
394 my ( $self, $name, $namespace ) = @_;
397 $namespace = join( "/", grep { length } split '/', ( defined $namespace ? $namespace : "" ) );
399 return $self->action_hash->{"${namespace}/${name}"};
402 =head2 $self->get_action_by_path( $path );
404 Returns the named action by its full path.
408 sub get_action_by_path {
409 my ( $self, $path ) = @_;
411 $path = "/$path" unless $path =~ /\//;
412 $self->action_hash->{$path};
415 =head2 $self->get_actions( $c, $action, $namespace )
420 my ( $self, $c, $action, $namespace ) = @_;
421 return [] unless $action;
423 $namespace = join( "/", grep { length } split '/', $namespace || "" );
425 my @match = $self->get_containers($namespace);
427 return map { $_->get_action($action) } @match;
430 =head2 $self->get_containers( $namespace )
432 Return all the action containers for a given namespace, inclusive
437 my ( $self, $namespace ) = @_;
439 $namespace = '' if $namespace eq '/';
443 if ( length $namespace ) {
445 push @containers, $self->container_hash->{$namespace};
446 } while ( $namespace =~ s#/[^/]+$## );
449 return reverse grep { defined } @containers, $self->container_hash->{''};
451 #return (split '/', $namespace); # isnt this more clear?
452 my @parts = split '/', $namespace;
455 =head2 $self->uri_for_action($action, \@captures)
457 Takes a Catalyst::Action object and action parameters and returns a URI
458 part such that if $c->req->path were this URI part, this action would be
459 dispatched to with $c->req->captures set to the supplied arrayref.
461 If the action object is not available for external dispatch or the dispatcher
462 cannot determine an appropriate URI, this method will return undef.
467 my ( $self, $action, $captures) = @_;
469 foreach my $dispatch_type ( @{ $self->dispatch_types } ) {
470 my $uri = $dispatch_type->uri_for_action( $action, $captures );
471 return( $uri eq '' ? '/' : $uri )
479 expand an action into a full representation of the dispatch.
480 mostly useful for chained, other actions will just return a
486 my ($self, $action) = @_;
488 foreach my $dispatch_type (@{ $self->dispatch_types }) {
489 my $expanded = $dispatch_type->expand_action($action);
490 return $expanded if $expanded;
496 =head2 $self->register( $c, $action )
498 Make sure all required dispatch types for this action are loaded, then
499 pass the action to our dispatch types so they can register it if required.
500 Also, set up the tree with the action containers.
505 my ( $self, $c, $action ) = @_;
507 my $registered = $self->registered_dispatch_types;
509 #my $priv = 0; #seems to be unused
510 foreach my $key ( keys %{ $action->attributes } ) {
511 next if $key eq 'Private';
512 my $class = "Catalyst::DispatchType::$key";
513 unless ( $registered->{$class} ) {
514 #some error checking rethrowing here wouldn't hurt.
515 eval { Class::MOP::load_class($class) };
516 push( @{ $self->dispatch_types }, $class->new ) unless $@;
517 $registered->{$class} = 1;
521 # Pass the action to our dispatch types so they can register it if reqd.
522 foreach my $type ( @{ $self->dispatch_types } ) {
523 $type->register( $c, $action );
526 my $namespace = $action->namespace;
527 my $name = $action->name;
529 my $container = $self->_find_or_create_action_container($namespace);
531 # Set the method value
532 $container->add_action($action);
534 $self->action_hash->{"$namespace/$name"} = $action;
535 $self->container_hash->{$namespace} = $container;
538 sub _find_or_create_action_container {
539 my ( $self, $namespace ) = @_;
541 my $tree ||= $self->tree;
543 return $tree->getNodeValue unless $namespace;
545 my @namespace = split '/', $namespace;
546 return $self->_find_or_create_namespace_node( $tree, @namespace )
550 sub _find_or_create_namespace_node {
551 my ( $self, $parent, $part, @namespace ) = @_;
553 return $parent unless $part;
556 ( grep { $_->getNodeValue->part eq $part } $parent->getAllChildren )[0];
559 my $container = Catalyst::ActionContainer->new($part);
560 $parent->addChild( $child = Tree::Simple->new($container) );
563 $self->_find_or_create_namespace_node( $child, @namespace );
566 =head2 $self->setup_actions( $class, $context )
572 my ( $self, $c ) = @_;
576 $self->_load_dispatch_types( @{ $self->preload_dispatch_types } );
577 @{ $self->registered_dispatch_types }{@classes} = (1) x @classes;
579 foreach my $comp ( values %{ $c->components } ) {
580 $comp->register_actions($c) if $comp->can('register_actions');
583 $self->_load_dispatch_types( @{ $self->postload_dispatch_types } );
585 return unless $c->debug;
587 my $privates = Text::SimpleTable->new(
595 my ( $walker, $parent, $prefix ) = @_;
596 $prefix .= $parent->getNodeValue || '';
597 $prefix .= '/' unless $prefix =~ /\/$/;
598 my $node = $parent->getNodeValue->actions;
600 for my $action ( keys %{$node} ) {
601 my $action_obj = $node->{$action};
603 if ( ( $action =~ /^_.*/ )
604 && ( !$c->config->{show_internal_actions} ) );
605 $privates->row( "$prefix$action", $action_obj->class, $action );
609 $walker->( $walker, $_, $prefix ) for $parent->getAllChildren;
612 $walker->( $walker, $self->tree, '' );
613 $c->log->debug( "Loaded Private actions:\n" . $privates->draw . "\n" )
616 # List all public actions
617 $_->list($c) for @{ $self->dispatch_types };
620 sub _load_dispatch_types {
621 my ( $self, @types ) = @_;
625 # Preload action types
626 for my $type (@types) {
628 ( $type =~ /^\+(.*)$/ ) ? $1 : "Catalyst::DispatchType::${type}";
630 eval { Class::MOP::load_class($class) };
631 Catalyst::Exception->throw( message => qq/Couldn't load "$class"/ )
633 push @{ $self->dispatch_types }, $class->new;
635 push @loaded, $class;
642 __PACKAGE__->meta->make_immutable;
650 Catalyst Contributors, see Catalyst.pm
654 This program is free software, you can redistribute it and/or modify it under
655 the same terms as Perl itself.