back out go() so we can ship a 5.7100 with other features and bugfixes

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

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index 4bd707f..ccc996e 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -49,7 +49,6 @@ 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
@@ -98,7 +97,7 @@ documentation and tutorials.
     catalyst.pl MyApp
 
     # add models, views, controllers
-    script/myapp_create.pl model MyDatabase DBIC::Schema create=dynamic dbi:SQLite:/path/to/db
+    script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
     script/myapp_create.pl view MyTemplate TT
     script/myapp_create.pl controller Search
 
@@ -328,20 +327,6 @@ 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
@@ -788,8 +773,7 @@ L<Catalyst::Engine>.
 =head2 $c->path_to(@path)
 
 Merges C<@path> with C<< $c->config->{home} >> and returns a
-L<Path::Class::Dir> object. Must be called after C<< MyApp->setup >>,
-which sets up C<< $c->config->{home} >>.
+L<Path::Class::Dir> object.
 
 For example:
 
@@ -970,23 +954,75 @@ EOF
     $class->setup_finished(1);
 }
 
+=head2 $c->uri_for( $action, \@captures?, @args?, \%query_values? )
+
 =head2 $c->uri_for( $path, @args?, \%query_values? )
 
-Merges path with C<< $c->request->base >> for absolute URIs and with
-C<< $c->namespace >> for relative URIs, then returns a normalized L<URI>
-object. If any args are passed, they are added at the end of the path.
-If the last argument to C<uri_for> is a hash reference, it is assumed to
-contain GET parameter key/value pairs, which will be appended to the URI
-in standard fashion.
+=over
+
+=item $action
+
+A Catalyst::Action object representing the Catalyst action you want to
+create a URI for. To get one for an action in the current controller,
+use C<< $c->action('someactionname') >>. To get one from different
+controller, fetch the controller using C<< $c->controller() >>, then
+call C<action_for> on it.
+
+This method must be used to create URIs for
+L<Catalyst::DispatchType::Chained> actions.
+
+=item $path
+
+The actual path you wish to create a URI for, this is a public path,
+not a private action path.
 
-Note that uri_for is destructive to the passed hashref.  Subsequent calls
-with the same hashref may have unintended results.
+=item \@captures
 
-Instead of C<$path>, you can also optionally pass a C<$action> object
-which will be resolved to a path using
-C<< $c->dispatcher->uri_for_action >>; if the first element of
-C<@args> is an arrayref it is treated as a list of captures to be passed
-to C<uri_for_action>.
+If provided, this argument is used to insert values into a I<Chained>
+action in the parts where the definitions contain I<CaptureArgs>. If
+not needed, leave out this argument.
+
+=item @args
+
+If provided, this is used as a list of further path sections to append
+to the URI. In a I<Chained> action these are the equivalent to the
+endpoint L<Args>.
+
+=item \%query_values
+
+If provided, the query_values hashref is used to add query parameters
+to the URI, with the keys as the names, and the values as the values.
+
+=back
+
+Returns a L<URI> object.
+
+  ## Ex 1: a path with args and a query parameter
+  $c->uri_for('user/list', 'short', { page => 2});
+  ## -> ($c->req->base is 'http://localhost:3000/'
+  URI->new('http://localhost:3000/user/list/short?page=2)
+
+  ## Ex 2: a chained view action that captures the user id
+  ## In controller:
+  sub user : Chained('/'): PathPart('myuser'): CaptureArgs(1) {}
+  sub viewuser : Chained('user'): PathPart('view') {}
+
+  ## In uri creating code:
+  my $uaction = $c->controller('Users')->action_for('viewuser');
+  $c->uri_for($uaction, [ 42 ]);
+  ## outputs:
+  URI->new('http://localhost:3000/myuser/42/view')
+
+Creates a URI object using C<< $c->request->base >> and a path. If an
+Action object is given instead of a path, the path is constructed
+using C<< $c->dispatcher->uri_for_action >> and passing it the
+@captures array, if supplied.
+
+If any query parameters are passed they are added to the end of the
+URI in the usual way.
+
+Note that uri_for is destructive to the passed query values hashref.
+Subsequent calls with the same hashref may have unintended results.
 
 =cut
 
@@ -1288,9 +1324,6 @@ sub execute {
         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';