From: Matt S Trout <mst@shadowcat.co.uk>
Date: Wed, 15 Oct 2008 19:18:29 +0000 (+0000)
Subject: Improve docs for uri_for
X-Git-Tag: 5.8000_03~39
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=8a27f8606cae3ecb2c064accf2ce0f1138a5ab7b

Improve docs for uri_for

back out go() so we can ship a 5.7100 with other features and bugfixes
r24814@agaton (orig r8494):  castaway | 2008-10-01 20:25:32 +0100
r24851@agaton (orig r8531):  matthewt | 2008-10-15 20:17:30 +0100
---

diff --git a/Changes b/Changes
index 8ec4ae3..758629f 100644
--- a/Changes
+++ b/Changes
@@ -19,6 +19,7 @@
         - Add visit, a returning ->go
 
 5.7XXXXXX XXXX
+        - Back out go() since that feature's been pushed to 5.80
         - Fix some Win32 test failures
         - Add pt translation of error message (wreis)
         - Make :Chained('../action') work (Florian Ragwitz)
diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index 96b44a4..4fd4da2 100644
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -59,7 +59,6 @@ our $COUNT     = 1;
 our $START     = time;
 our $RECURSION = 1000;
 our $DETACH    = "catalyst_detach\n";
-our $GO        = "catalyst_go\n";
 
 #I imagine that very few of these really need to be class variables. if any.
 #maybe we should just make them attributes with a default?
@@ -1013,23 +1012,19 @@ 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
 
-Note that uri_for is destructive to the passed hashref.  Subsequent calls
-with the same hashref may have unintended results.
+=item $action
 
-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>.
+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.
 
 You can maintain the arguments captured by an action (e.g.: Regex, Chained)
 using C<< $c->req->captures >>. 
@@ -1340,9 +1335,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';