From: Tomas Doran <bobtfish@bobtfish.net>
Date: Thu, 3 Nov 2011 09:54:48 +0000 (+0000)
Subject: Sort out the Request docs
X-Git-Tag: 5.90008~16^2~7
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=47b9d68e304e9cb305974bc15aa8e60f4bfb6c45

Sort out the Request docs
---

diff --git a/lib/Catalyst/Engine.pm b/lib/Catalyst/Engine.pm
index a66847a..fac70cd 100644
--- a/lib/Catalyst/Engine.pm
+++ b/lib/Catalyst/Engine.pm
@@ -522,7 +522,7 @@ sub prepare_query_parameters {
 
 =head2 $self->prepare_read($c)
 
-prepare to read from the engine.
+Prepare to read by initializing the Content-Length from headers.
 
 =cut
 
diff --git a/lib/Catalyst/Request.pm b/lib/Catalyst/Request.pm
index 442f888..3c9dee1 100644
--- a/lib/Catalyst/Request.pm
+++ b/lib/Catalyst/Request.pm
@@ -15,9 +15,22 @@ use namespace::clean -except => 'meta';
 with 'MooseX::Emulate::Class::Accessor::Fast';
 
 has env => (is => 'ro', writer => '_set_env');
+# XXX Deprecated crap here - warn?
+has action => (is => 'rw');
+# XXX: Deprecated in docs ages ago (2006), deprecated with warning in 5.8000 due
+# to confusion between Engines and Plugin::Authentication. Remove in 5.8100?
+has user => (is => 'rw');
+sub snippets        { shift->captures(@_) }
 
-has _read_position => ( is => 'rw', default => 0 );
-has _read_length => ( is => 'ro',
+has _read_position => (
+    init_arg => undef,
+    is => 'ro',
+    writer => '_set_read_position',
+    default => 0,
+);
+has _read_length => (
+    init_arg => undef,
+    is => 'ro',
     default => sub {
         my $self = shift;
         $self->header('Content-Length') || 0;
@@ -25,17 +38,10 @@ has _read_length => ( is => 'ro',
     lazy => 1,
 );
 
-has action => (is => 'rw'); # XXX Deprecated - warn?
 has address => (is => 'rw');
 has arguments => (is => 'rw', default => sub { [] });
 has cookies => (is => 'ro', builder => 'prepare_cookies', lazy => 1);
 
-=head2 $self->prepare_cookies($c)
-
-Parse cookies from header. Sets a L<CGI::Simple::Cookie> object.
-
-=cut
-
 sub prepare_cookies {
     my ( $self ) = @_;
 
@@ -62,10 +68,6 @@ has headers => (
   lazy => 1,
 );
 
-=head2 $self->prepare_headers($c)
-
-=cut
-
 sub prepare_headers {
     my ($self) = @_;
 
@@ -107,7 +109,7 @@ sub read {
                         # said there should be.
             return;
         }
-        $self->_read_position( $self->_read_position + $rc );
+        $self->_set_read_position( $self->_read_position + $rc );
         return $buffer;
     }
     else {
@@ -179,12 +181,6 @@ before body_parameters => sub {
     $self->prepare_body_parameters;
 };
 
-=head2 $self->prepare_body()
-
-sets up the L<Catalyst::Request> object body using L<HTTP::Body>
-
-=cut
-
 has _uploadtmp => (
     is => 'ro',
     predicate => '_has_uploadtmp',
@@ -220,24 +216,12 @@ sub prepare_body {
     }
 }
 
-=head2 $self->prepare_body_chunk()
-
-Add a chunk to the request body.
-
-=cut
-
 sub prepare_body_chunk {
     my ( $self, $chunk ) = @_;
 
     $self->_body->add($chunk);
 }
 
-=head2 $self->prepare_body_parameters()
-
-Sets up parameters from body.
-
-=cut
-
 sub prepare_body_parameters {
     my ( $self ) = @_;
 
@@ -310,19 +294,14 @@ has hostname => (
 
 has _path => ( is => 'rw', predicate => '_has_path', clearer => '_clear_path' );
 
-# XXX: Deprecated in docs ages ago (2006), deprecated with warning in 5.8000 due
-# to confusion between Engines and Plugin::Authentication. Remove in 5.8100?
-has user => (is => 'rw');
-
 sub args            { shift->arguments(@_) }
 sub body_params     { shift->body_parameters(@_) }
 sub input           { shift->body(@_) }
 sub params          { shift->parameters(@_) }
 sub query_params    { shift->query_parameters(@_) }
 sub path_info       { shift->path(@_) }
-sub snippets        { shift->captures(@_) }
 
-=for stopwords param params
+=for stopwords param params snippets
 
 =head1 NAME
 
@@ -358,7 +337,7 @@ Catalyst::Request - provides information about the current client request
     $req->read;
     $req->referer;
     $req->secure;
-    $req->captures; # previously knows as snippets
+    $req->captures;
     $req->upload;
     $req->uploads;
     $req->uri;
@@ -681,11 +660,6 @@ actions or regex captures.
 
     my @captures = @{ $c->request->captures };
 
-=head2 $req->snippets
-
-C<captures> used to be called snippets. This is still available for backwards
-compatibility, but is considered deprecated.
-
 =head2 $req->upload
 
 A convenient method to access $req->uploads.
@@ -867,6 +841,31 @@ Returns the value of the C<REMOTE_USER> environment variable.
 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
 version string.
 
+=head1 SETUP METHODS
+
+You should never need to call these yourself in application code,
+however they are useful if extending Catalyst by applying a request role.
+
+=head2 $self->prepare_headers()
+
+Sets up the C<< $res->headers >> accessor.
+
+=head2 $self->prepare_body()
+
+Sets up the body using L<HTTP::Body>
+
+=head2 $self->prepare_body_chunk()
+
+Add a chunk to the request body.
+
+=head2 $self->prepare_body_parameters()
+
+Sets up parameters from body.
+
+=head2 $self->prepare_cookies($c)
+
+Parse cookies from header. Sets up a L<CGI::Simple::Cookie> object.
+
 =head2 meta
 
 Provided by Moose