{ "mode": "perldoc", "parameter": "HTTP::Negotiate", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ANegotiate/json", "generated": "2026-06-14T07:37:31Z", "synopsis": "use HTTP::Negotiate qw(choose);\n# ID QS Content-Type Encoding Char-Set Lang Size\n$variants =\n[['var1', 1.000, 'text/html', undef, 'iso-8859-1', 'en', 3000],\n['var2', 0.950, 'text/plain', 'gzip', 'us-ascii', 'no', 400],\n['var3', 0.3, 'image/gif', undef, undef, undef, 43555],\n];\n@preferred = choose($variants, $requestheaders);\n$theone = choose($variants);", "sections": { "NAME": { "content": "HTTP::Negotiate - choose a variant to serve\n", "subsections": [] }, "SYNOPSIS": { "content": "use HTTP::Negotiate qw(choose);\n\n# ID QS Content-Type Encoding Char-Set Lang Size\n$variants =\n[['var1', 1.000, 'text/html', undef, 'iso-8859-1', 'en', 3000],\n['var2', 0.950, 'text/plain', 'gzip', 'us-ascii', 'no', 400],\n['var3', 0.3, 'image/gif', undef, undef, undef, 43555],\n];\n\n@preferred = choose($variants, $requestheaders);\n$theone = choose($variants);\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides a complete implementation of the HTTP content negotiation algorithm\nspecified in draft-ietf-http-v11-spec-00.ps chapter 12. Content negotiation allows for the\nselection of a preferred content representation based upon attributes of the negotiable variants\nand the value of the various Accept* header fields in the request.\n\nThe variants are ordered by preference by calling the function choose().\n\nThe first parameter is reference to an array of the variants to choose among. Each element in\nthis array is an array with the values [$id, $qs, $contenttype, $contentencoding, $charset,\n$contentlanguage, $contentlength] whose meanings are described below. The $contentencoding\nand $contentlanguage can be either a single scalar value or an array reference if there are\nseveral values.\n\nThe second optional parameter is either a HTTP::Headers or a HTTP::Request object which is\nsearched for \"Accept*\" headers. If this parameter is missing, then the accept specification is\ninitialized from the CGI environment variables HTTPACCEPT, HTTPACCEPTCHARSET,\nHTTPACCEPTENCODING and HTTPACCEPTLANGUAGE.\n\nIn an array context, choose() returns a list of [variant identifier, calculated quality, size]\ntuples. The values are sorted by quality, highest quality first. If the calculated quality is\nthe same for two variants, then they are sorted by size (smallest first). *E.g.*:\n\n(['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);\n\nNote that also zero quality variants are included in the return list even if these should never\nbe served to the client.\n\nIn a scalar context, it returns the identifier of the variant with the highest score or \"undef\"\nif none have non-zero quality.\n\nIf the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of noise is generated on\nSTDOUT during evaluation of choose().\n", "subsections": [] }, "VARIANTS": { "content": "A variant is described by a list of the following values. If the attribute does not make sense\nor is unknown for a variant, then use \"undef\" instead.\n\nidentifier\nThis is a string that you use as the name for the variant. This identifier for the preferred\nvariants returned by choose().\n\nqs This is a number between 0.000 and 1.000 that describes the \"source quality\". This is what\ndraft-ietf-http-v11-spec-00.ps says about this value:\n\nSource quality is measured by the content provider as representing the amount of degradation\nfrom the original source. For example, a picture in JPEG form would have a lower qs when\ntranslated to the XBM format, and much lower qs when translated to an ASCII-art\nrepresentation. Note, however, that this is a function of the source - an original piece of\nASCII-art may degrade in quality if it is captured in JPEG form. The qs values should be\nassigned to each variant by the content provider; if no qs value has been assigned, the\ndefault is generally \"qs=1\".\n\ncontent-type\nThis is the media type of the variant. The media type does not include a charset attribute,\nbut might contain other parameters. Examples are:\n\ntext/html\ntext/html;version=2.0\ntext/plain\nimage/gif\nimage/jpg\n\ncontent-encoding\nThis is one or more content encodings that has been applied to the variant. The content\nencoding is generally used as a modifier to the content media type. The most common content\nencodings are:\n\ngzip\ncompress\n\ncontent-charset\nThis is the character set used when the variant contains text. The charset value should\ngenerally be \"undef\" or one of these:\n\nus-ascii\niso-8859-1 ... iso-8859-9\niso-2022-jp\niso-2022-jp-2\niso-2022-kr\nunicode-1-1\nunicode-1-1-utf-7\nunicode-1-1-utf-8\n\ncontent-language\nThis describes one or more languages that are used in the variant. Language is described like\nthis in draft-ietf-http-v11-spec-00.ps: A language is in this context a natural language\nspoken, written, or otherwise conveyed by human beings for communication of information to\nother human beings. Computer languages are explicitly excluded.\n\nThe language tags are defined by RFC 3066. Examples are:\n\nno Norwegian\nen International English\nen-US US English\nen-cockney\n\ncontent-length\nThis is the number of bytes used to represent the content.\n", "subsections": [] }, "ACCEPT HEADERS": { "content": "The following Accept* headers can be used for describing content preferences in a request (This\ndescription is an edited extract from draft-ietf-http-v11-spec-00.ps):\n\nAccept\nThis header can be used to indicate a list of media ranges which are acceptable as a response\nto the request. The \"*\" character is used to group media types into ranges, with \"*/*\"\nindicating all media types and \"type/*\" indicating all subtypes of that type.\n\nThe parameter q is used to indicate the quality factor, which represents the user's\npreference for that range of media types. The parameter mbx gives the maximum acceptable size\nof the response content. The default values are: q=1 and mbx=infinity. If no Accept header is\npresent, then the client accepts all media types with q=1.\n\nFor example:\n\nAccept: audio/*;q=0.2;mbx=200000, audio/basic\n\nwould mean: \"I prefer audio/basic (of any size), but send me any audio type if it is the best\navailable after an 80% mark-down in quality and its size is less than 200000 bytes\"\n\nAccept-Charset\nUsed to indicate what character sets are acceptable for the response. The \"us-ascii\"\ncharacter set is assumed to be acceptable for all user agents. If no Accept-Charset field is\ngiven, the default is that any charset is acceptable. Example:\n\nAccept-Charset: iso-8859-1, unicode-1-1\n\nAccept-Encoding\nRestricts the Content-Encoding values which are acceptable in the response. If no\nAccept-Encoding field is present, the server may assume that the client will accept any\ncontent encoding. An empty Accept-Encoding means that no content encoding is acceptable.\nExample:\n\nAccept-Encoding: compress, gzip\n\nAccept-Language\nThis field is similar to Accept, but restricts the set of natural languages that are\npreferred in a response. Each language may be given an associated quality value which\nrepresents an estimate of the user's comprehension of that language. For example:\n\nAccept-Language: no, en-gb;q=0.8, de;q=0.55\n\nwould mean: \"I prefer Norwegian, but will accept British English (with 80% comprehension) or\nGerman (with 55% comprehension).\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 1996,2001 Gisle Aas.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] }, "AUTHOR": { "content": "Gisle Aas \n", "subsections": [] } }, "summary": "HTTP::Negotiate - choose a variant to serve", "flags": [], "examples": [], "see_also": [] }