NAME¶
HTTP::Parser - parse HTTP/1.1 request into HTTP::Request/Response object
SYNOPSIS¶
my $parser = HTTP::Parser->new();
...
my $status = $parser->add($text);
if(0 == $status) {
print "request: ".$parser->request()->as_string(); # HTTP::Request
} elsif(-3 == $status) {
print "no content length header!\n";
} elsif(-2 == $status) {
print "need a line of data\n";
} elsif(-1 == $status) {
print "need more data\n";
} else { # $status > 0
print "need $status byte(s)\n";
}
DESCRIPTION¶
This is an HTTP request parser. It takes chunks of text as received and returns
a 'hint' as to what is required, or returns the HTTP::Request when a complete
request has been read. HTTP/1.1 chunking is supported. It dies if it finds an
error.
new ( named params... )¶
Create a new HTTP::Parser object. Takes named parameters, e.g.:
my $parser = HTTP::Parser->new(request => 1);
- request
- Allows or denies parsing an HTTP request and returning an
"HTTP::Request" object.
- response
- Allows or denies parsing an HTTP response and returning an
"HTTP::Response" object.
If you pass neither "request" nor "response", only requests
are parsed (for backwards compatibility); if you pass either, the other
defaults to false (disallowing both requests and responses is a fatal error).
add ( string )¶
Parse request. Returns:
- 0
- if finished (call "object" to get an HTTP::Request or Response
object)
- -1
- if not finished but not sure how many bytes remain
- -2
- if waiting for a line (like 0 with a hint)
- -3
- if there was no content-length header, so we can't tell whether we are
waiting for more data or not.
If you are reading from a TCP stream, you can keep adding data until the
connection closes gracefully (the HTTP RFC allows this).
If you are reading from a file, you should keep adding until you have all
the data.
Once you have added all data, you may call "object". if you are
not sure whether you have all the data, the HTTP::Response object might be
incomplete.
- count
- if waiting for that many bytes
Dies on error.
This method of parsing makes it easier to parse a request from an event-based
system, on the other hand, it's quite alright to pass in the whole request.
Ideally, the first chunk passed in is the header (up to the double newline),
then whatever byte counts are requested.
When a request object is returned, the X-HTTP-Version header has the HTTP
version, the
uri() method will always return a URI object, not a
string.
Note that a nonzero return is just a hint, and any amount of data can be passed
in to a subsequent
add() call.
data¶
Returns current data not parsed. Mainly useful after a request has been parsed.
The data is not removed from the object's buffer, and will be seen before the
data next passed to
add().
Returns the count of extra bytes (length of
data()) after a request.
object¶
Returns the object request. Only useful after the parse has completed.
AUTHOR¶
David Robins <dbrobins@davidrobins.net> Fixes for 0.05 by David Cannings
<david@edeca.net>
SEE ALSO¶
HTTP::Request, HTTP::Response.