joes 2004/07/30 08:59:33
Modified: glue/perl/docs Request.pod
Log:
Add $req->parse docs
Revision Changes Path
1.6 +30 -0 httpd-apreq-2/glue/perl/docs/Request.pod
Index: Request.pod
===================================================================
RCS file: /home/cvs/httpd-apreq-2/glue/perl/docs/Request.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Request.pod 29 Jul 2004 17:31:05 -0000 1.5
+++ Request.pod 30 Jul 2004 15:59:33 -0000 1.6
@@ -420,6 +420,36 @@
+=head2 parse
+
+ $req->parse()
+
+Forces the request to be parsed immediately. In void context,
+this will throw an Apache::Request::Error, otherwise it will
+return the parser's final I<APR> status code.
+
+However C<parse> should be avoided in most normal situations.
+For example, in a mod_perl content handler it is more efficient
+to write
+
+ sub handler {
+ my $r = shift;
+ $req = Apache::Request->new($r);
+ $r->discard_request_body; # efficiently parses the request body
+ my $parser_status = $req->body_status;
+
+ #...
+ }
+
+Calling C<< $r->discard_request_body >> outside the content handler
+is generally a mistake, so use C<< $req->parse >> there, but
+B<only as a last resort>. The Apache::Request API is designed
+around a lazy-parsing scheme, so calling C<parse> should not
+affect the behavior of any other methods.
+
+
+
+
=head1 SUBCLASSING Apache::Request
If the instances of your subclass are hash references then you can actually
