diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 188 |
1 files changed, 188 insertions, 0 deletions
@@ -0,0 +1,188 @@ +NAME + HTTP::Negotiate - choose a variant to serve + +SYNOPSIS + use HTTP::Negotiate qw(choose); + + # ID QS Content-Type Encoding Char-Set Lang Size + $variants = + [['var1', 1.000, 'text/html', undef, 'iso-8859-1', 'en', 3000], + ['var2', 0.950, 'text/plain', 'gzip', 'us-ascii', 'no', 400], + ['var3', 0.3, 'image/gif', undef, undef, undef, 43555], + ]; + + @preferred = choose($variants, $request_headers); + $the_one = choose($variants); + +DESCRIPTION + This module provides a complete implementation of the HTTP content + negotiation algorithm specified in draft-ietf-http-v11-spec-00.ps + chapter 12. Content negotiation allows for the selection of a preferred + content representation based upon attributes of the negotiable variants + and the value of the various Accept* header fields in the request. + + The variants are ordered by preference by calling the function choose(). + + The first parameter is reference to an array of the variants to choose + among. Each element in this array is an array with the values [$id, $qs, + $content_type, $content_encoding, $charset, $content_language, + $content_length] whose meanings are described below. The + $content_encoding and $content_language can be either a single scalar + value or an array reference if there are several values. + + The second optional parameter is either a HTTP::Headers or a + HTTP::Request object which is searched for "Accept*" headers. If this + parameter is missing, then the accept specification is initialized from + the CGI environment variables HTTP_ACCEPT, HTTP_ACCEPT_CHARSET, + HTTP_ACCEPT_ENCODING and HTTP_ACCEPT_LANGUAGE. + + In an array context, choose() returns a list of [variant identifier, + calculated quality, size] tuples. The values are sorted by quality, + highest quality first. If the calculated quality is the same for two + variants, then they are sorted by size (smallest first). *E.g.*: + + (['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]); + + Note that also zero quality variants are included in the return list + even if these should never be served to the client. + + In a scalar context, it returns the identifier of the variant with the + highest score or `undef' if none have non-zero quality. + + If the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of + noise is generated on STDOUT during evaluation of choose(). + +VARIANTS + A variant is described by a list of the following values. If the + attribute does not make sense or is unknown for a variant, then use + `undef' instead. + + identifier + This is a string that you use as the name for the variant. This + identifier for the preferred variants returned by choose(). + + qs This is a number between 0.000 and 1.000 that describes the "source + quality". This is what draft-ietf-http-v11-spec-00.ps says about this + value: + + Source quality is measured by the content provider as representing + the amount of degradation from the original source. For example, a + picture in JPEG form would have a lower qs when translated to the XBM + format, and much lower qs when translated to an ASCII-art + representation. Note, however, that this is a function of the source + - an original piece of ASCII-art may degrade in quality if it is + captured in JPEG form. The qs values should be assigned to each + variant by the content provider; if no qs value has been assigned, + the default is generally "qs=1". + + content-type + This is the media type of the variant. The media type does not + include a charset attribute, but might contain other parameters. + Examples are: + + text/html + text/html;version=2.0 + text/plain + image/gif + image/jpg + + content-encoding + This is one or more content encodings that has been applied to the + variant. The content encoding is generally used as a modifier to the + content media type. The most common content encodings are: + + gzip + compress + + content-charset + This is the character set used when the variant contains text. The + charset value should generally be `undef' or one of these: + + us-ascii + iso-8859-1 ... iso-8859-9 + iso-2022-jp + iso-2022-jp-2 + iso-2022-kr + unicode-1-1 + unicode-1-1-utf-7 + unicode-1-1-utf-8 + + content-language + This describes one or more languages that are used in the variant. + Language is described like this in draft-ietf-http-v11-spec-00.ps: A + language is in this context a natural language spoken, written, or + otherwise conveyed by human beings for communication of information + to other human beings. Computer languages are explicitly excluded. + + The language tags are defined by RFC 3066. Examples are: + + no Norwegian + en International English + en-US US English + en-cockney + + content-length + This is the number of bytes used to represent the content. + +ACCEPT HEADERS + The following Accept* headers can be used for describing content + preferences in a request (This description is an edited extract from + draft-ietf-http-v11-spec-00.ps): + + Accept + This header can be used to indicate a list of media ranges which are + acceptable as a response to the request. The "*" character is used to + group media types into ranges, with "*/*" indicating all media types + and "type/*" indicating all subtypes of that type. + + The parameter q is used to indicate the quality factor, which + represents the user's preference for that range of media types. The + parameter mbx gives the maximum acceptable size of the response + content. The default values are: q=1 and mbx=infinity. If no Accept + header is present, then the client accepts all media types with q=1. + + For example: + + Accept: audio/*;q=0.2;mbx=200000, audio/basic + + would mean: "I prefer audio/basic (of any size), but send me any + audio type if it is the best available after an 80% mark-down in + quality and its size is less than 200000 bytes" + + Accept-Charset + Used to indicate what character sets are acceptable for the response. + The "us-ascii" character set is assumed to be acceptable for all user + agents. If no Accept-Charset field is given, the default is that any + charset is acceptable. Example: + + Accept-Charset: iso-8859-1, unicode-1-1 + + Accept-Encoding + Restricts the Content-Encoding values which are acceptable in the + response. If no Accept-Encoding field is present, the server may + assume that the client will accept any content encoding. An empty + Accept-Encoding means that no content encoding is acceptable. + Example: + + Accept-Encoding: compress, gzip + + Accept-Language + This field is similar to Accept, but restricts the set of natural + languages that are preferred in a response. Each language may be + given an associated quality value which represents an estimate of the + user's comprehension of that language. For example: + + Accept-Language: no, en-gb;q=0.8, de;q=0.55 + + would mean: "I prefer Norwegian, but will accept British English + (with 80% comprehension) or German (with 55% comprehension). + +COPYRIGHT + Copyright 1996,2001 Gisle Aas. + + This library is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. + +AUTHOR + Gisle Aas <gisle@aas.no> + |