choose - choose a variant of a document to serve (HTTP
content negotiation)
SYNOPSIS
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);
DESCRIPTION
This module provide 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 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
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().
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 just some string that you use as a name for the
variant. The identifier of the preferred variant is
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
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 textual content. 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 the same as those defined by
RFC-1766. 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 reponse to the
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 restrict the set
of natural languages that are preferred as 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
Copyright 1996, 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 <aas@sn.no>