added cookies method to Mojo::Message and document caching behavior

mojolicious · Apr 25, 2012 · 880f4a0 · 880f4a0
1 parent b3470e4
commit 880f4a0
Show file tree

Hide file tree

Showing 5 changed files with 27 additions and 8 deletions.
diff --git a/Changes b/Changes
@@ -1,5 +1,9 @@
 This file documents the revision history for Perl extension Mojolicious.
 
+2.91  2012-04-26
+  - Added cookies method to Mojo::Message.
+  - Improved documentation.
+
 2.90  2012-04-25
   - Fixed small JavaScript bug in Mojolicious::Plugin::PODRenderer.
 

diff --git a/lib/Mojo/Message.pm b/lib/Mojo/Message.pm
@@ -1,6 +1,7 @@
 package Mojo::Message;
 use Mojo::Base 'Mojo::EventEmitter';
 
+use Carp 'croak';
 use Mojo::Asset::Memory;
 use Mojo::Content::Single;
 use Mojo::DOM;
@@ -133,6 +134,8 @@ sub cookie {
   return wantarray ? @cookies : $cookies[0];
 }
 
+sub cookies { croak 'Method "add_chunk" not implemented by subclass' }
+
 sub dom {
   my $self = shift;
   return if $self->is_multipart;
@@ -593,7 +596,8 @@ Access C<content> data or replace all subscribers of the C<read> event.
 
 C<POST> parameters extracted from C<x-application-urlencoded>,
 C<application/x-www-form-urlencoded> or C<multipart/form-data> message body,
-usually a L<Mojo::Parameters> object.
+usually a L<Mojo::Parameters> object. Note that this method caches all data,
+so it should not be called before the entire message body has been received.
 
   say $message->body_params->param('foo');
 
@@ -627,10 +631,17 @@ Render start line.
   my @cookies = $message->cookie('foo');
 
 Access message cookies, usually L<Mojo::Cookie::Request> or
-L<Mojo::Cookie::Response> objects.
+L<Mojo::Cookie::Response> objects. Note that this method caches all data, so
+it should not be called before all headers have been received.
 
   say $message->cookie('foo')->value;
 
+=head2 C<cookies>
+
+  my $cookies = $message->cookies;
+
+Access message cookies, meant to be overloaded in a subclass.
+
 =head2 C<dom>
 
   my $dom        = $message->dom;
@@ -760,7 +771,8 @@ Alias for L<Mojo::Headers/"max_line_size">.
   my $foo   = $message->param('foo');
   my @foo   = $message->param('foo');
 
-Access C<POST> parameters.
+Access C<POST> parameters. Note that this method caches all data, so it should
+not be called before the entire message body has been received.
 
 =head2 C<parse>
 
@@ -792,6 +804,8 @@ Render whole message.
   my @uploads = $message->upload('foo');
 
 Access C<multipart/form-data> file uploads, usually L<Mojo::Upload> objects.
+Note that this method caches all data, so it should not be called before the
+entire message body has been received.
 
   say $message->upload('foo')->asset->slurp;
 

diff --git a/lib/Mojo/Message/Request.pm b/lib/Mojo/Message/Request.pm
@@ -396,7 +396,7 @@ Access request cookies, usually L<Mojo::Cookie::Request> objects.
 
   $req = $req->fix_headers;
 
-Make sure message has all required headers for the current HTTP version.
+Make sure request has all required headers for the current HTTP version.
 
 =head2 C<is_secure>
 
@@ -416,7 +416,8 @@ Check C<X-Requested-With> header for C<XMLHttpRequest> value.
   my $foo   = $req->param('foo');
   my @foo   = $req->param('foo');
 
-Access C<GET> and C<POST> parameters.
+Access C<GET> and C<POST> parameters. Note that this method caches all data,
+so it should not be called before the entire request body has been received.
 
 =head2 C<params>
 
@@ -440,7 +441,7 @@ Parse HTTP request chunks or environment hash.
   $req      = $req->proxy('http://foo:bar@127.0.0.1:3000');
   $req      = $req->proxy(Mojo::URL->new('http://127.0.0.1:3000'));
 
-Proxy URL for message.
+Proxy URL for request.
 
   # Disable proxy
   $req->proxy(0);

diff --git a/lib/Mojo/Message/Response.pm b/lib/Mojo/Message/Response.pm
@@ -217,7 +217,7 @@ Generate default response message for code.
 
   $res = $res->fix_headers;
 
-Make sure message has all required headers for the current HTTP version.
+Make sure response has all required headers for the current HTTP version.
 
 =head2 C<is_status_class>
 

diff --git a/lib/Mojolicious.pm b/lib/Mojolicious.pm
@@ -33,7 +33,7 @@ has static   => sub { Mojolicious::Static->new };
 has types    => sub { Mojolicious::Types->new };
 
 our $CODENAME = 'Leaf Fluttering In Wind';
-our $VERSION  = '2.90';
+our $VERSION  = '2.91';
 
 # "These old doomsday devices are dangerously unstable.
 #  I'll rest easier not knowing where they are."