X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FMiddleware%2FStash.pm;h=c8d59451839ff261f655e02cbd4c094be7e89318;hp=f3bbe68bf380d649b5ea97b9ca3387fe7745970f;hb=79fb8f95180a06c51de7f0fde227927b5d864a7f;hpb=e77ad76e30c334b05bdef6cc5e5ef57304d8c309

diff --git a/lib/Catalyst/Middleware/Stash.pm b/lib/Catalyst/Middleware/Stash.pm
index f3bbe68..c8d5945 100644
--- a/lib/Catalyst/Middleware/Stash.pm
+++ b/lib/Catalyst/Middleware/Stash.pm
@@ -9,12 +9,12 @@ use Carp 'croak';
 
 our @EXPORT_OK = qw(stash get_stash);
 
-sub PSGI_KEY { 'Catalyst.Stash.v1' };
+sub PSGI_KEY () { 'Catalyst.Stash.v2' }
 
 sub get_stash {
   my $env = shift;
-  return $env->{PSGI_KEY} ||
-    _init_stash_in($env);
+  return $env->{+PSGI_KEY} ||
+   croak "You requested a stash, but one does not exist.";
 }
 
 sub stash {
@@ -24,6 +24,7 @@ sub stash {
 }
 
 sub _create_stash {
+  my $self = shift;
   my $stash = shift || +{};
   return sub {
     if(@_) {
@@ -38,19 +39,15 @@ sub _create_stash {
   };
 }
 
-sub _init_stash_in {
-  my ($env) = @_;
-  return $env->{PSGI_KEY} ||=
-    _create_stash;
-}
-
 sub call {
   my ($self, $env) = @_;
-  _init_stash_in($env);
+  $env->{+PSGI_KEY} = $self->_create_stash 
+    unless exists($env->{+PSGI_KEY});
+
   return $self->app->($env);
 }
 
-=head1 TITLE
+=head1 NAME
 
 Catalyst::Middleware::Stash - The Catalyst stash - in middleware
 
@@ -61,7 +58,18 @@ directly since it is likely to move off the Catalyst namespace into a stand
 alone distribution
 
 We store a coderef under the C<PSGI_KEY> which can be dereferenced with
-key values or nothing to access the underly hashref.
+key values or nothing to access the underlying hashref.
+
+Anything placed into the stash will be available in the stash of any 'mounted'
+Catalyst applications.  A mounted Catalyst application may set the stash and
+'pass back' information to the parent application.  Non Catalyst applications
+may use this middleware to access and set stash values.
+
+Please note I highly recommend having a stronger interface than a stash key
+between applications.
+
+For more information the current test case t/middleware-stash.t is the best
+documentation.
 
 =head1 SUBROUTINES
 
@@ -104,7 +112,7 @@ clients.  Stash key / value are stored in memory.
         ["I found $stashed in the stash!"]];
     };
 
-If the stash does not yet exist, we initialize one and return that.
+If the stash does not yet exist, an exception is thrown.
 
 =head1 METHODS