use HTTP::Negotiate;
# 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], ];
@prefered = choose($variants, $request_headers); $the_one = choose($variants);
The variants are ordered by preference by calling the function
choose().
The first parameter is a description of the variants that we can choose
among. The variants are described by a reference to an array. Each element
in this array is an array with the values [$id, $qs, $content_type,
$content_encoding, $charset, $content_language, $content_length]. The
meaning of these values 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 a reference to the request headers. This is used to look for ``Accept*'' headers. You can pass a reference to either a HTTP::Request or a HTTP::Headers object. 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 array context, choose()
returns a list of variant
identifier/calculated quality pairs. 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], ['var2', 0.3], ['var3' => 0]);
Note that also zero quality variants are included in the return list even if these should never be served to the client.
In 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().
choose().
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''.
text/html text/html;version=2.0 text/plain image/gif image/jpg
gzip compress
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
The language tags are the same as those defined by RFC-1766. Examples are:
no Norwegian en International English en-US US English en-cockney
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: iso-8859-1, unicode-1-1
Accept-Encoding: compress, gzip
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).
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.