Parser(3) User Contributed Perl Documentation Parser(3)NAMEHTTP::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().
extra
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.
perl v5.14.1 2011-03-06 Parser(3)
