HTTP::Body 1.04, patch from jgoulah for tmpdir() accessor

[catagits/HTTP-Body.git] / README

diff --git a/README b/README
index 37cac15..aeb552d 100644 (file)
--- a/README
+++ b/README
@@ -3,27 +3,99 @@ NAME
 
 SYNOPSIS
         use HTTP::Body;
+        
+    sub handler : method {
+            my ( $class, $r ) = @_;
+
+            my $content_type   = $r->headers_in->get('Content-Type');
+            my $content_length = $r->headers_in->get('Content-Length');
+            
+        my $body   = HTTP::Body->new( $content_type, $content_length );
+            my $length = $content_length;
+
+            while ( $length ) {
+
+                $r->read( my $buffer, ( $length < 8192 ) ? $length : 8192 );
+
+                $length -= length($buffer);
+                
+            $body->add($buffer);
+            }
+            
+        my $uploads = $body->upload; # hashref
+            my $params  = $body->param;  # hashref
+            my $body    = $body->body;   # IO::Handle
+        }
 
 DESCRIPTION
-    HTTP Body Parser.
+    HTTP::Body parses chunks of HTTP POST data and supports
+    application/octet-stream, application/x-www-form-urlencoded, and
+    multipart/form-data.
+
+    Chunked bodies are supported by not passing a length value to new().
+
+    It is currently used by Catalyst to parse POST bodies.
+
+NOTES
+    When parsing multipart bodies, temporary files are created to store any
+    uploaded files. You must delete these temporary files yourself after
+    processing them.
 
 METHODS
-    add
+    new Constructor. Takes content type and content length as parameters,
+        returns a HTTP::Body object.
+
+    add Add string to internal buffer. Will call spin unless done. returns
+        length before adding self.
+
     body
-    buffer
+        accessor for the body.
+
+    chunked
+        Returns 1 if the request is chunked.
+
     content_length
+        Returns the content-length for the body data if known. Returns -1 if
+        the request is chunked.
+
     content_type
+        Returns the content-type of the body data.
+
     init
+        return self.
+
     length
+        Returns the total length of data we expect to read if known. In the
+        case of a chunked request, returns the amount of data read so far.
+
+    trailing_headers
+        If a chunked request body had trailing headers, trailing_headers
+        will return an HTTP::Headers object populated with those headers.
+
     spin
+        Abstract method to spin the io handle.
+
     state
+        Returns the current state of the parser.
+
     param
+        Get/set body parameters.
+
     upload
+        Get/set file uploads.
+
+    tmpdir
+        Specify a different path for temporary files. Defaults to the system
+        temporary path.
 
 AUTHOR
     Christian Hansen, "ch@ngmedia.com"
 
+    Sebastian Riedel, "sri@cpan.org"
+
+    Andy Grundman, "andy@hybridized.org"
+
 LICENSE
-    This library is free software . You can redistribute it and/or modify it
+    This library is free software. You can redistribute it and/or modify it
     under the same terms as perl itself.