Backport go doc bit

[catagits/Catalyst-Runtime.git] / lib / Catalyst.pm

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index a0f4e75..f3701d6 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -26,7 +26,7 @@ use Tree::Simple qw/use_weak_refs/;
 use Tree::Simple::Visitor::FindByUID;
 use attributes;
 use utf8;
-use Carp qw/croak carp/;
+use Carp qw/croak carp shortmess/;
 
 BEGIN { require 5.008001; }
 
@@ -64,7 +64,7 @@ __PACKAGE__->stats_class('Catalyst::Stats');
 
 # Remember to update this in Catalyst::Runtime as well!
 
-our $VERSION = '5.7099_03';
+our $VERSION = '5.7099_04';
 
 sub import {
     my ( $class, @arguments ) = @_;
@@ -328,13 +328,40 @@ When called with no arguments it escapes the processing chain entirely.
 
 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
 
+=head2 $c->visit( $action [, \@arguments ] )
+
+=head2 $c->visit( $class, $method, [, \@arguments ] )
+
+Almost the same as C<forward>, but does a full dispatch, instead of just
+calling the new C<$action> / C<$class-E<gt>$method>. This means that C<begin>,
+C<auto> and the method you go to are called, just like a new request.
+
+In addition both C<< $c->action >> and C<< $c->namespace >> are localized.
+This means, for example, that $c->action methods such as C<name>, C<class> and
+C<reverse> return information for the visited action when they are invoked
+within the visited action.  This is different from the behavior of C<forward>
+which continues to use the $c->action object from the caller action even when
+invoked from the callee.
+
+C<$c-E<gt>stash> is kept unchanged.
+
+In effect, C<visit> allows you to "wrap" another action, just as it
+would have been called by dispatching from a URL, while the analogous
+C<go> allows you to transfer control to another action as if it had
+been reached directly from a URL.
+
+=cut
+
+sub visit { my $c = shift; $c->dispatcher->visit( $c, @_ ) }
+
 =head2 $c->go( $action [, \@arguments ] )
 
 =head2 $c->go( $class, $method, [, \@arguments ] )
 
-Almost the same as C<detach>, but does a full dispatch, instead of just
-calling the new C<$action> / C<$class-E<gt>$method>. This means that C<begin>,
-C<auto> and the method you go to is called, just like a new request.
+Almost the same as C<detach>, but does a full dispatch like C<visit>,
+instead of just calling the new C<$action> /
+C<$class-E<gt>$method>. This means that C<begin>, C<auto> and the
+method you visit are called, just like a new request.
 
 C<$c-E<gt>stash> is kept unchanged.
 
@@ -461,9 +488,24 @@ sub _comp_search_prefixes {
 
     # don't warn if we didn't find any results, it just might not exist
     if( @result ) {
-        $c->log->warn( qq(Found results for "${name}" using regexp fallback.) );
-        $c->log->warn( 'Relying on the regexp fallback behavior for component resolution is unreliable and unsafe.' );
-        $c->log->warn( 'If you really want to search, pass in a regexp as the argument.' );
+        my $msg = "Used regexp fallback for \$c->model('${name}'), which found '" .
+           (join '", "', @result) . "'. Relying on regexp fallback behavior for " .
+           "component resolution is unreliable and unsafe.";
+        my $short = $result[0];
+        $short =~ s/.*?Model:://;
+        my $shortmess = Carp::shortmess('');
+        if ($shortmess =~ m#Catalyst/Plugin#) {
+           $msg .= " You probably need to set '$short' instead of '${name}' in this " .
+              "plugin's config";
+        } elsif ($shortmess =~ m#Catalyst/lib/(View|Controller)#) {
+           $msg .= " You probably need to set '$short' instead of '${name}' in this " .
+              "component's config";
+        } else {
+           $msg .= " You probably meant \$c->model('$short') instead of \$c->model{'${name}'}, " .
+              "but if you really wanted to search, pass in a regexp as the argument " .
+              "like so: \$c->model(qr/${name}/)";
+        }
+        $c->log->warn( "${msg}$shortmess" );
     }
 
     return @result;
@@ -564,7 +606,7 @@ sub model {
     my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/Model M/);
 
     if( $rest ) {
-        $c->log->warn( 'Calling $c->model() will return a random model unless you specify one of:' );
+        $c->log->warn( Carp::shortmess('Calling $c->model() will return a random model unless you specify one of:') );
         $c->log->warn( '* $c->config->{default_model} # the name of the default model to use' );
         $c->log->warn( '* $c->stash->{current_model} # the name of the model to use for this request' );
         $c->log->warn( '* $c->stash->{current_model_instance} # the instance of the model to use for this request' );
@@ -703,7 +745,7 @@ sub component {
         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 
         if( $result[ 0 ] ) {
-            $c->log->warn( qq(Found results for "${name}" using regexp fallback.) );
+            $c->log->warn( Carp::shortmess(qq(Found results for "${name}" using regexp fallback)) );
             $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
             $c->log->warn( 'is unreliable and unsafe. You have been warned' );
             return $c->_filter_component( $result[ 0 ], @args );
@@ -2519,6 +2561,8 @@ Geoff Richards
 
 jcamacho: Juan Camacho
 
+jhannah: Jay Hannah <jay@jays.net>
+
 Jody Belka
 
 Johan Lindstrom
@@ -2555,6 +2599,8 @@ Ulf Edvinsson
 
 willert: Sebastian Willert <willert@cpan.org>
 
+batman: Jan Henning Thorsen <pm@flodhest.net>
+
 =head1 LICENSE
 
 This library is free software, you can redistribute it and/or modify it under