HTTP::Parser::XS(3pm)					User Contributed Perl Documentation				     HTTP::Parser::XS(3pm)

NAME

       HTTP::Parser::XS - a fast, primitive HTTP request parser

SYNOPSIS

	 use HTTP::Parser::XS qw(parse_http_request);

	 # for HTTP servers
	 my $ret = parse_http_request(
	     "GET / HTTP/1.0
Host: ...

",
	     \%env,
	 );
	 if ($ret == -2) {
	     # request is incomplete
	     ...
	 } elsif ($ret == -1) {
	     # request is broken
	     ...
	 } else {
	     # $ret includes the size of the request, %env now contains a PSGI
	     # request, if it is a POST / PUT request, read request content by
	     # yourself
	     ...
	 }

	 # for HTTP clients
	 use HTTP::Parser::XS qw(parse_http_response HEADERS_AS_ARRAYREF);
	 my %special_headers = (
	   'content-length' => undef,
	 );
	 my($ret, $minor_version, $status, $message, $headers)
	   = parse_http_response($response, HEADERS_AS_ARRAYREF, \%special_headers);

	 if($ret == -1) }
	   # response is incomplete
	 }
	 elsif($ret == -2) {
	   # response is broken
	 }
	 else {
	   # $ret is the length of the headers, starting the content body

	   # the other values are the response messages. For example:
	   # $status  = 200
	   # $message = "OK"
	   # $headers = [ 'content-type' => 'text/html', ... ]

	   # and $special_headers{'content-length'} will be filled in
	 }

DESCRIPTION

       HTTP::Parser::XS is a fast, primitive HTTP request/response parser.

       The request parser can be used either for writing a synchronous HTTP server or a event-driven server.

       The response parser can be used for writing HTTP clients.

       Note that even if this distribution name ends "::XS", pure Perl implementation is supported, so you can use this module on compiler-less
       environments.

FUNCTIONS

       parse_http_request($request_string, \%env)
	   Tries to parse given request string, and if successful, inserts variables into %env.  For the name of the variables inserted, please
	   refer to the PSGI specification.  The return values are:

	   >=0	   length of the request (request line and the request headers), in bytes

	   -1	   given request is corrupt

	   -2	   given request is incomplete

       parse_http_response($response_string, $header_format, \%special_headers)
	   Tries to parse given response string. $header_format must be "HEADERS_AS_ARRAYREF", "HEADERS_AS_HASHREF", or "HEADERS_NONE", which are
	   exportable constants.

	   The optional %special_headers is for headers you specifically require.  You can set any HTTP response header names, which must be
	   lower-cased, and their default values, and then the values are filled in by "parse_http_response()".  For example, if you want the
	   "Cointent-Length" field, set its name with default values like "%h = ('content-length' => undef)" and pass it as %special_headers.
	   After parsing, $h{'content-length'} is set if the response has the "Content-Length" field, otherwise it's not touched.

	   The return values are:

	   $ret    The parsering status, which is the same as "parse_http_response()". i.e.  the length of the response headers in bytes, "-1" for
		   incomplete headers, or "-2" for errors.

		   If the given response string is broken or imcomplete, "parse_http_response()" returns only this value.

	   $minor_version
		   The minor version of the given response.  i.e. 1 for HTTP/1.1, 0 for HTTP/1.0.

	   $status The HTTP status of the given response. e.g. 200 for success.

	   $message
		   The HTTP status message. e.g. "OK" for success.

	   $headers
		   The HTTP headers for the given response. It is an ARRAY reference if $header_format is "HEADERS_AS_ARRAYREF", a HASH reference
		   on "HEADERS_AS_HASHREF", an "undef" on "HEADERS_NONE".

		   The names of the headers are normalized to lower-cased.

LIMITATIONS

       Both "parse_http_request()" and "parse_http_response()" in XS implementation have some size limitations.

   The number of headers
       The number of headers is limited to 128. If it exceeds, both parsing routines report parsing errors, i.e. return "-1" for $ret.

   The size of header names
       The size of header names is limited to 1024, but the parsers do not the same action.

       "parse_http_request()" returns "-1" if too-long header names exist.

       "parse_http_request()" simply ignores too-long header names.

COPYRIGHT

       Copyright 2009- Kazuho Oku

AUTHOR

       Kazuho Oku gfx mala tokuhirom

THANKS TO

       nothingmuch charsbar

SEE ALSO

       <http://github.com/kazuho/picohttpparser>

       HTTP::Parser HTTP::HeaderParser::XS

LICENSE

       This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

perl v5.14.2							    2011-05-26						     HTTP::Parser::XS(3pm)