local-lib5/man/man3/HTTP::Negotiate.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "HTTP::Negotiate 3"
 132 .TH HTTP::Negotiate 3 "2008-09-24" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 HTTP::Negotiate \- choose a variant to serve
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \& use HTTP::Negotiate qw(choose);
 139 .Ve
 140 .PP
 141 .Vb 6
 142 \& #  ID       QS     Content\-Type   Encoding Char\-Set        Lang   Size
 143 \& $variants =
 144 \&  [['var1',  1.000, 'text/html',   undef,   'iso\-8859\-1',   'en',   3000],
 145 \&   ['var2',  0.950, 'text/plain',  'gzip',  'us\-ascii',     'no',    400],
 146 \&   ['var3',  0.3,   'image/gif',   undef,   undef,          undef, 43555],
 147 \&  ];
 148 .Ve
 149 .PP
 150 .Vb 2
 151 \& @preferred = choose($variants, $request_headers);
 152 \& $the_one   = choose($variants);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 This module provides a complete implementation of the \s-1HTTP\s0 content
 157 negotiation algorithm specified in \fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR
 158 chapter 12.  Content negotiation allows for the selection of a
 159 preferred content representation based upon attributes of the
 160 negotiable variants and the value of the various Accept* header fields
 161 in the request.
 162 .PP
 163 The variants are ordered by preference by calling the function
 164 \&\fIchoose()\fR.
 165 .PP
 166 The first parameter is reference to an array of the variants to
 167 choose among.
 168 Each element in this array is an array with the values [$id, \f(CW$qs\fR,
 169 \&\f(CW$content_type\fR, \f(CW$content_encoding\fR, \f(CW$charset\fR, \f(CW$content_language\fR,
 170 \&\f(CW$content_length\fR] whose meanings are described
 171 below. The \f(CW$content_encoding\fR and \f(CW$content_language\fR can be either a
 172 single scalar value or an array reference if there are several values.
 173 .PP
 174 The second optional parameter is either a HTTP::Headers or a HTTP::Request
 175 object which is searched for \*(L"Accept*\*(R" headers.  If this
 176 parameter is missing, then the accept specification is initialized
 177 from the \s-1CGI\s0 environment variables \s-1HTTP_ACCEPT\s0, \s-1HTTP_ACCEPT_CHARSET\s0,
 178 \&\s-1HTTP_ACCEPT_ENCODING\s0 and \s-1HTTP_ACCEPT_LANGUAGE\s0.
 179 .PP
 180 In an array context, \fIchoose()\fR returns a list of [variant
 181 identifier, calculated quality, size] tuples.  The values are sorted by
 182 quality, highest quality first.  If the calculated quality is the same
 183 for two variants, then they are sorted by size (smallest first). \fIE.g.\fR:
 184 .PP
 185 .Vb 1
 186 \&  (['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);
 187 .Ve
 188 .PP
 189 Note that also zero quality variants are included in the return list
 190 even if these should never be served to the client.
 191 .PP
 192 In a scalar context, it returns the identifier of the variant with the
 193 highest score or \f(CW\*(C`undef\*(C'\fR if none have non-zero quality.
 194 .PP
 195 If the \f(CW$HTTP::Negotiate::DEBUG\fR variable is set to \s-1TRUE\s0, then a lot of
 196 noise is generated on \s-1STDOUT\s0 during evaluation of \fIchoose()\fR.
 197 .SH "VARIANTS"
 198 .IX Header "VARIANTS"
 199 A variant is described by a list of the following values.  If the
 200 attribute does not make sense or is unknown for a variant, then use
 201 \&\f(CW\*(C`undef\*(C'\fR instead.
 202 .IP "identifier" 3
 203 .IX Item "identifier"
 204 This is a string that you use as the name for the variant.  This
 205 identifier for the preferred variants returned by \fIchoose()\fR.
 206 .IP "qs" 3
 207 .IX Item "qs"
 208 This is a number between 0.000 and 1.000 that describes the \*(L"source
 209 quality\*(R".  This is what \fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR says about this
 210 value:
 211 .Sp
 212 Source quality is measured by the content provider as representing the
 213 amount of degradation from the original source.  For example, a
 214 picture in \s-1JPEG\s0 form would have a lower qs when translated to the \s-1XBM\s0
 215 format, and much lower qs when translated to an ASCII-art
 216 representation.  Note, however, that this is a function of the source
 217 \&\- an original piece of ASCII-art may degrade in quality if it is
 218 captured in \s-1JPEG\s0 form.  The qs values should be assigned to each
 219 variant by the content provider; if no qs value has been assigned, the
 220 default is generally \*(L"qs=1\*(R".
 221 .IP "content-type" 3
 222 .IX Item "content-type"
 223 This is the media type of the variant.  The media type does not
 224 include a charset attribute, but might contain other parameters.
 225 Examples are:
 226 .Sp
 227 .Vb 5
 228 \&  text/html
 229 \&  text/html;version=2.0
 230 \&  text/plain
 231 \&  image/gif
 232 \&  image/jpg
 233 .Ve
 234 .IP "content-encoding" 3
 235 .IX Item "content-encoding"
 236 This is one or more content encodings that has been applied to the
 237 variant.  The content encoding is generally used as a modifier to the
 238 content media type.  The most common content encodings are:
 239 .Sp
 240 .Vb 2
 241 \&  gzip
 242 \&  compress
 243 .Ve
 244 .IP "content-charset" 3
 245 .IX Item "content-charset"
 246 This is the character set used when the variant contains text.
 247 The charset value should generally be \f(CW\*(C`undef\*(C'\fR or one of these:
 248 .Sp
 249 .Vb 8
 250 \&  us\-ascii
 251 \&  iso\-8859\-1 ... iso\-8859\-9
 252 \&  iso\-2022\-jp
 253 \&  iso\-2022\-jp\-2
 254 \&  iso\-2022\-kr
 255 \&  unicode\-1\-1
 256 \&  unicode\-1\-1\-utf\-7
 257 \&  unicode\-1\-1\-utf\-8
 258 .Ve
 259 .IP "content-language" 3
 260 .IX Item "content-language"
 261 This describes one or more languages that are used in the variant.
 262 Language is described like this in \fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR: A
 263 language is in this context a natural language spoken, written, or
 264 otherwise conveyed by human beings for communication of information to
 265 other human beings.  Computer languages are explicitly excluded.
 266 .Sp
 267 The language tags are defined by \s-1RFC\s0 3066.  Examples
 268 are:
 269 .Sp
 270 .Vb 4
 271 \&  no               Norwegian
 272 \&  en               International English
 273 \&  en\-US            US English
 274 \&  en\-cockney
 275 .Ve
 276 .IP "content-length" 3
 277 .IX Item "content-length"
 278 This is the number of bytes used to represent the content.
 279 .SH "ACCEPT HEADERS"
 280 .IX Header "ACCEPT HEADERS"
 281 The following Accept* headers can be used for describing content
 282 preferences in a request (This description is an edited extract from
 283 \&\fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR):
 284 .IP "Accept" 3
 285 .IX Item "Accept"
 286 This header can be used to indicate a list of media ranges which are
 287 acceptable as a response to the request.  The \*(L"*\*(R" character is used to
 288 group media types into ranges, with \*(L"*/*\*(R" indicating all media types
 289 and \*(L"type/*\*(R" indicating all subtypes of that type.
 290 .Sp
 291 The parameter q is used to indicate the quality factor, which
 292 represents the user's preference for that range of media types.  The
 293 parameter mbx gives the maximum acceptable size of the response
 294 content. The default values are: q=1 and mbx=infinity. If no Accept
 295 header is present, then the client accepts all media types with q=1.
 296 .Sp
 297 For example:
 298 .Sp
 299 .Vb 1
 300 \&  Accept: audio/*;q=0.2;mbx=200000, audio/basic
 301 .Ve
 302 .Sp
 303 would mean: \*(L"I prefer audio/basic (of any size), but send me any audio
 304 type if it is the best available after an 80% mark-down in quality and
 305 its size is less than 200000 bytes\*(R"
 306 .IP "Accept-Charset" 3
 307 .IX Item "Accept-Charset"
 308 Used to indicate what character sets are acceptable for the response.
 309 The \*(L"us\-ascii\*(R" character set is assumed to be acceptable for all user
 310 agents.  If no Accept-Charset field is given, the default is that any
 311 charset is acceptable.  Example:
 312 .Sp
 313 .Vb 1
 314 \&  Accept\-Charset: iso\-8859\-1, unicode\-1\-1
 315 .Ve
 316 .IP "Accept-Encoding" 3
 317 .IX Item "Accept-Encoding"
 318 Restricts the Content-Encoding values which are acceptable in the
 319 response.  If no Accept-Encoding field is present, the server may
 320 assume that the client will accept any content encoding.  An empty
 321 Accept-Encoding means that no content encoding is acceptable.  Example:
 322 .Sp
 323 .Vb 1
 324 \&  Accept\-Encoding: compress, gzip
 325 .Ve
 326 .IP "Accept-Language" 3
 327 .IX Item "Accept-Language"
 328 This field is similar to Accept, but restricts the set of natural
 329 languages that are preferred in a response.  Each language may be
 330 given an associated quality value which represents an estimate of the
 331 user's comprehension of that language.  For example:
 332 .Sp
 333 .Vb 1
 334 \&  Accept\-Language: no, en\-gb;q=0.8, de;q=0.55
 335 .Ve
 336 .Sp
 337 would mean: "I prefer Norwegian, but will accept British English (with
 338 80% comprehension) or German (with 55% comprehension).
 339 .SH "COPYRIGHT"
 340 .IX Header "COPYRIGHT"
 341 Copyright 1996,2001 Gisle Aas.
 342 .PP
 343 This library is free software; you can redistribute it and/or
 344 modify it under the same terms as Perl itself.
 345 .SH "AUTHOR"
 346 .IX Header "AUTHOR"
 347 Gisle Aas <gisle@aas.no>