HTTP::Parser(3pm)

1Parser(3)             User Contributed Perl Documentation            Parser(3)
2
3
4

NAME

6       HTTP::Parser - parse HTTP/1.1 request into HTTP::Request/Response
7       object
8

SYNOPSIS

10        my $parser = HTTP::Parser->new();
11
12        ...
13
14        my $status = $parser->add($text);
15
16        if(0 == $status) {
17          print "request: ".$parser->request()->as_string();  # HTTP::Request
18        } elsif(-3 == $status) {
19          print "no content length header!\n";
20        } elsif(-2 == $status) {
21          print "need a line of data\n";
22        } elsif(-1 == $status) {
23          print "need more data\n";
24        } else {  # $status > 0
25          print "need $status byte(s)\n";
26        }
27

DESCRIPTION

29       This is an HTTP request parser.  It takes chunks of text as received
30       and returns a 'hint' as to what is required, or returns the
31       HTTP::Request when a complete request has been read.  HTTP/1.1 chunking
32       is supported.  It dies if it finds an error.
33
34   new ( named params... )
35       Create a new HTTP::Parser object.  Takes named parameters, e.g.:
36
37        my $parser = HTTP::Parser->new(request => 1);
38
39       request
40           Allows or denies parsing an HTTP request and returning an
41           "HTTP::Request" object.
42
43       response
44           Allows or denies parsing an HTTP response and returning an
45           "HTTP::Response" object.
46
47       If you pass neither "request" nor "response", only requests are parsed
48       (for backwards compatibility); if you pass either, the other defaults
49       to false (disallowing both requests and responses is a fatal error).
50
51   add ( string )
52       Parse request.  Returns:
53
54       0       if finished (call "object" to get an HTTP::Request or Response
55               object)
56
57       -1      if not finished but not sure how many bytes remain
58
59       -2      if waiting for a line (like 0 with a hint)
60
61       -3      if there was no content-length header, so we can't tell whether
62               we are waiting for more data or not.
63
64               If you are reading from a TCP stream, you can keep adding data
65               until the connection closes gracefully (the HTTP RFC allows
66               this).
67
68               If you are reading from a file, you should keep adding until
69               you have all the data.
70
71               Once you have added all data, you may call "object".  if you
72               are not sure whether you have all the data, the HTTP::Response
73               object might be incomplete.
74
75       count   if waiting for that many bytes
76
77       Dies on error.
78
79       This method of parsing makes it easier to parse a request from an
80       event-based system, on the other hand, it's quite alright to pass in
81       the whole request.  Ideally, the first chunk passed in is the header
82       (up to the double newline), then whatever byte counts are requested.
83
84       When a request object is returned, the X-HTTP-Version header has the
85       HTTP version, the uri() method will always return a URI object, not a
86       string.
87
88       Note that a nonzero return is just a hint, and any amount of data can
89       be passed in to a subsequent add() call.
90
91   data
92       Returns current data not parsed.  Mainly useful after a request has
93       been parsed.  The data is not removed from the object's buffer, and
94       will be seen before the data next passed to add().
95
96   extra
97       Returns the count of extra bytes (length of data()) after a request.
98
99   object
100       Returns the object request.  Only useful after the parse has completed.
101

AUTHOR

103       David Robins <dbrobins@davidrobins.net> Fixes for 0.05 by David
104       Cannings <david@edeca.net>
105

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

SEE ALSO