.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Parser 3pm"
.TH Parser 3pm "2022-10-16" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::Parser \- parse HTTP/1.1 request into HTTP::Request/Response object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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!\en";
\& } elsif(\-2 == $status) {
\&   print "need a line of data\en";
\& } elsif(\-1 == $status) {
\&   print "need more data\en";
\& } else {  # $status > 0
\&   print "need $status byte(s)\en";
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is an \s-1HTTP\s0 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.  \s-1HTTP/1.1\s0 chunking is supported.  It dies
if it finds an error.
.SS "new ( named params... )"
.IX Subsection "new ( named params... )"
Create a new HTTP::Parser object.  Takes named parameters, e.g.:
.PP
.Vb 1
\& my $parser = HTTP::Parser\->new(request => 1);
.Ve
.IP "request" 4
.IX Item "request"
Allows or denies parsing an \s-1HTTP\s0 request and returning an \f(CW\*(C`HTTP::Request\*(C'\fR
object.
.IP "response" 4
.IX Item "response"
Allows or denies parsing an \s-1HTTP\s0 response and returning an \f(CW\*(C`HTTP::Response\*(C'\fR
object.
.PP
If you pass neither \f(CW\*(C`request\*(C'\fR nor \f(CW\*(C`response\*(C'\fR, 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).
.SS "add ( string )"
.IX Subsection "add ( string )"
Parse request.  Returns:
.IP "0" 8
if finished (call \f(CW\*(C`object\*(C'\fR to get an HTTP::Request or Response object)
.IP "\-1" 8
.IX Item "-1"
if not finished but not sure how many bytes remain
.IP "\-2" 8
.IX Item "-2"
if waiting for a line (like 0 with a hint)
.IP "\-3" 8
.IX Item "-3"
if there was no content-length header, so we can't tell whether we are 
waiting for more data or not.
.Sp
If you are reading from a \s-1TCP\s0 stream, you can keep adding data until 
the connection closes gracefully (the \s-1HTTP RFC\s0 allows this).
.Sp
If you are reading from a file, you should keep adding until you have 
all the data.
.Sp
Once you have added all data, you may call \f(CW\*(C`object\*(C'\fR.  if you are not 
sure whether you have all the data, the HTTP::Response object might be 
incomplete.
.IP "count" 8
.IX Item "count"
if waiting for that many bytes
.PP
Dies on error.
.PP
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.
.PP
When a request object is returned, the X\-HTTP-Version header has the \s-1HTTP\s0
version, the \fBuri()\fR method will always return a \s-1URI\s0 object, not a string.
.PP
Note that a nonzero return is just a hint, and any amount of data can be
passed in to a subsequent \fBadd()\fR call.
.SS "data"
.IX Subsection "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 \fBadd()\fR.
.SS "extra"
.IX Subsection "extra"
Returns the count of extra bytes (length of \fBdata()\fR) after a request.
.SS "object"
.IX Subsection "object"
Returns the object request.  Only useful after the parse has completed.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Robins <dbrobins@davidrobins.net>
Fixes for 0.05 by David Cannings <david@edeca.net>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
HTTP::Request, HTTP::Response.