Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_map_module.xml @ 572:17ceffcc7ffb
Brought the ngx_http_map_module documentation up to date.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 05 Jul 2012 13:15:08 +0000 |
parents | 9913f1d51c07 |
children | be54c443235a |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_map_module.xml Thu Jul 05 13:13:45 2012 +0000 +++ b/xml/en/docs/http/ngx_http_map_module.xml Thu Jul 05 13:15:08 2012 +0000 @@ -32,6 +32,11 @@ .example.net 3; wap.* 4; } + +map $http_user_agent $mobile { + default 0; + "~Opera Mini" 1; +} </example> </para> @@ -42,20 +47,58 @@ <directive name="map"> <syntax block="yes"> - <value>$variable1</value> - <value>$variable2</value></syntax> + <value>string</value> + <value>$variable</value></syntax> <default/> <context>http</context> <para> -Creates a variable whose value -depends on the value of another variable. -The directive supports three special parameters: +Creates a new variable whose value +depends on values of one or more of the source variables +specified in the first parameter. +<note> +Before version 0.9.0 only a single variable could be +specified in the first parameter. +</note> +</para> + +<para> +Parameters inside the <literal>map</literal> block specify a mapping +between source and resulting values. +</para> + +<para> +Source values are specified as strings or regular expressions (0.9.6). +</para> + +<para> +A regular expression should either start from the “<literal>~</literal>” +symbol for a case-sensitive matching, or from the “<literal>~*</literal>” +symbols (1.0.4) for case-insensitive matching. +A regular expression can contain named and positional captures +that can later be used in other directives along with the +resulting variable. +</para> + +<para> +If a source value matches one of the names of special parameters +(see below), it should be prefixed with the “<literal>\</literal>” symbol. +</para> + +<para> +The resulting value can be a string +or another variable (0.9.0). +</para> + +<para> +The directive also supports three special parameters: <list type="tag"> <tag-name><literal>default</literal> <value>value</value></tag-name> <tag-desc> -sets a value for the second variable when the value -of the first variable cannot be found. +sets the resulting value if the source value matches none +of the specified variants. +When <literal>default</literal> is not specified, the default +resulting value will be an empty string. </tag-desc> <tag-name><literal>hostnames</literal></tag-name> @@ -75,6 +118,7 @@ <example> .example.com 1; </example> +This parameter should be specified before the list of values. </tag-desc> <tag-name><literal>include</literal> <value>file</value></tag-name> @@ -86,6 +130,38 @@ </list> </para> +<para> +If the source value matches more than one of the specified variants, +e.g. both mask and regular expression match, the first matching +variant will be choosen, in the following order of precedence: +<list type="enum"> + +<listitem> +string value without a mask +</listitem> + +<listitem> +longest string value with a prefix mask, +e.g. “<literal>*.example.com</literal>” +</listitem> + +<listitem> +longest string value with a suffix mask, +e.g. “<literal>mail.*</literal>” +</listitem> + +<listitem> +first matching regular expression +(in order of appearance in a configuration file) +</listitem> + +<listitem> +default value +</listitem> + +</list> +</para> + </directive>