remove a confusing and duplicate bit of documentation

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

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index 13218e3..22deaf1 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -49,6 +49,7 @@ our $COUNT     = 1;
 our $START     = time;
 our $RECURSION = 1000;
 our $DETACH    = "catalyst_detach\n";
+our $GO        = "catalyst_go\n";
 
 __PACKAGE__->mk_classdata($_)
   for qw/components arguments dispatcher engine log dispatcher_class
@@ -327,6 +328,20 @@ When called with no arguments it escapes the processing chain entirely.
 
 sub detach { my $c = shift; $c->dispatcher->detach( $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.
+
+C<$c-E<gt>stash> is kept unchanged.
+
+=cut
+
+sub go { my $c = shift; $c->dispatcher->go( $c, @_ ) }
+
 =head2 $c->response
 
 =head2 $c->res
@@ -441,8 +456,8 @@ sub _comp_search_prefixes {
 
     # don't warn if we didn't find any results, it just might not exist
     if( @result ) {
-        $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
-        $c->log->warn( 'is unreliable and unsafe. You have been warned' );
+        $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.' );
     }
 
     return @result;
@@ -481,6 +496,12 @@ Gets a L<Catalyst::Controller> instance by name.
 If the name is omitted, will return the controller for the dispatched
 action.
 
+If you want to search for controllers, pass in a regexp as the argument.
+
+    # find all controllers that start with Foo
+    my @foo_controllers = $c->controller(qr{^Foo});
+
+
 =cut
 
 sub controller {
@@ -509,6 +530,11 @@ If the name is omitted, it will look for
  - a config setting 'default_model', or
  - check if there is only one model, and return it if that's the case.
 
+If you want to search for models, pass in a regexp as the argument.
+
+    # find all models that start with Foo
+    my @foo_models = $c->model(qr{^Foo});
+
 =cut
 
 sub model {
@@ -536,6 +562,7 @@ sub model {
         $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' );
+        $c->log->warn( 'NB: in version 5.80, the "random" behavior will not work at all.' );
     }
 
     return $c->_filter_component( $comp );
@@ -556,6 +583,11 @@ If the name is omitted, it will look for
  - a config setting 'default_view', or
  - check if there is only one view, and return it if that's the case.
 
+If you want to search for views, pass in a regexp as the argument.
+
+    # find all views that start with Foo
+    my @foo_views = $c->view(qr{^Foo});
+
 =cut
 
 sub view {
@@ -583,6 +615,7 @@ sub view {
         $c->log->warn( '* $c->config->{default_view} # the name of the default view to use' );
         $c->log->warn( '* $c->stash->{current_view} # the name of the view to use for this request' );
         $c->log->warn( '* $c->stash->{current_view_instance} # the instance of the view to use for this request' );
+        $c->log->warn( 'NB: in version 5.80, the "random" behavior will not work at all.' );
     }
 
     return $c->_filter_component( $comp );
@@ -631,6 +664,9 @@ unless you want to get a specific component by full
 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
 should be used instead.
 
+If C<$name> is a regexp, a list of components matched against the full
+component name will be returned.
+
 =cut
 
 sub component {
@@ -657,7 +693,12 @@ sub component {
 
         my @result = grep { m{$query} } keys %{ $c->components };
         return @result if ref $name;
-        return $result[ 0 ] if $result[ 0 ];
+
+        if( $result[ 0 ] ) {
+            $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
+            $c->log->warn( 'is unreliable and unsafe. You have been warned' );
+            return $result[ 0 ];
+        }
 
         # I would expect to return an empty list here, but that breaks back-compat
     }
@@ -1234,7 +1275,12 @@ sub execute {
     my $last = pop( @{ $c->stack } );
 
     if ( my $error = $@ ) {
-        if ( !ref($error) and $error eq $DETACH ) { die $DETACH if $c->depth > 1 }
+        if ( !ref($error) and $error eq $DETACH ) {
+            die $DETACH if($c->depth > 1);
+        }
+        elsif ( !ref($error) and $error eq $GO ) {
+            die $GO if($c->depth > 0);
+        }
         else {
             unless ( ref $error ) {
                 no warnings 'uninitialized';