From: Mateu X. Hunter <hunter@missoula.org>
Date: Mon, 21 Sep 2009 18:57:14 +0000 (+0000)
Subject: Update $c->forward and $c->state documentation to address scalar context.
X-Git-Tag: 5.80014~42
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=2e60292e80cede2e0ba4350d77733457f09f9b9a

Update $c->forward and $c->state documentation to address scalar context.
---

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index e5b1882..c4a39f8 100644
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -349,6 +349,21 @@ Or make sure to always return true values from your actions and write
 your code like this:
 
     $c->forward('foo') || return;
+    
+Another note is that C<< $c->forward >> always returns a scalar because it
+actually returns $c->state which operates in a scalar context.
+Thus, something like:
+
+    return @array;
+    
+in an action that is forwarded to is going to return a scalar, 
+i.e. how many items are in that array, which is probably not what you want.
+If you need to return an array then return a reference to it, 
+or stash it like so:
+
+    $c->stash->{array} = \@array;
+
+and access it from the stash.
 
 =cut
 
@@ -490,7 +505,9 @@ sub error {
 
 =head2 $c->state
 
-Contains the return value of the last executed action.
+Contains the return value of the last executed action.   
+Note that << $c->state >> operates in a scalar context which means that all
+values it returns are scalar.
 
 =head2 $c->clear_errors