Added cleanup flag to auto-delete temp files

[catagits/HTTP-Body.git] / README

NAME
    HTTP::Body - HTTP Body Parser

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 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
    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
        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
    under the same terms as perl itself.