# HG changeset patch
# User Ruslan Ermilov <ru@nginx.com>
# Date 1341494108 0
# Node ID 17ceffcc7ffb43c9513ae35fc54a2ed9a8baa35e
# Parent  71d775bef043050841e93dfc38f3da8e524adf93
Brought the ngx_http_map_module documentation up to date.

diff -r 71d775bef043 -r 17ceffcc7ffb xml/en/docs/http/ngx_http_map_module.xml
--- 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>
 
 
diff -r 71d775bef043 -r 17ceffcc7ffb xml/ru/docs/http/ngx_http_map_module.xml
--- a/xml/ru/docs/http/ngx_http_map_module.xml	Thu Jul 05 13:13:45 2012 +0000
+++ b/xml/ru/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>$переменная1</value>
-    <value>$переменная2</value></syntax>
+    <value>строка</value>
+    <value>$переменная</value></syntax>
 <default/>
 <context>http</context>
 
 <para>
-Создаёт переменную, значение которой
-зависит от значения исходной переменной.
-Директива поддерживает три специальных параметра:
+Создаёт новую переменную, значение которой
+зависит от значений одной или более исходных переменных,
+указанных в первом параметре.
+<note>
+До версии 0.9.0 в качестве первого параметра можно было
+указать только одну переменную.
+</note>
+</para>
+
+<para>
+Параметры внутри блока <literal>map</literal> задают соответствие
+между исходными и результирующими значениями.
+</para>
+
+<para>
+Исходные значения задаются строками или регулярными выражениями (0.9.6).
+</para>
+
+<para>
+Перед регулярным выражением ставится символ “<literal>~</literal>”,
+если при сравнении следует учитывать регистр символов, либо символы
+“<literal>~*</literal>” (1.0.4), если регистр символов учитывать не нужно.
+Регулярное выражение может содержать именованные и позиционные выделения,
+которые могут затем использоваться в других директивах совместно с
+результирующей переменной.
+</para>
+
+<para>
+Если исходное значение совпадает с именем одного из специальных параметров
+(см. ниже), перед ним следует поставить символ “<literal>\</literal>”.
+</para>
+
+<para>
+В качестве результирующего значения можно указать строку
+или другую переменную (0.9.0).
+</para>
+
+<para>
+Директива также поддерживает три специальных параметра:
 <list type="tag">
 <tag-name><literal>default</literal> <value>значение</value></tag-name>
 <tag-desc>
-задаёт значение для второй переменной, если значение
-первой переменной не найдено.
+задаёт результирующее значение, если исходное значение не
+совпадает ни с одним из перечисленных.
+Если параметр <literal>default</literal> не указан, результирующим значением
+по умолчанию будет пустая строка.
 </tag-desc>
 
 <tag-name><literal>hostnames</literal></tag-name>
@@ -75,6 +118,7 @@
 <example>
 .example.com  1;
 </example>
+Этот параметр следует указывать перед списком значений.
 </tag-desc>
 
 <tag-name><literal>include</literal> <value>файл</value></tag-name>
@@ -86,6 +130,38 @@
 </list>
 </para>
 
+<para>
+Если исходному значению соответствует несколько из указанных вариантов,
+например, одновременно подходят и маска, и регулярное выражение,
+будет выбран первый подходящий вариант в следующем порядке приоритета:
+<list type="enum">
+
+<listitem>
+строковое значение без маски
+</listitem>
+
+<listitem>
+самое длинное строковое значение с маской в начале,
+например “<literal>*.example.com</literal>”
+</listitem>
+
+<listitem>
+самое длинное строковое значение с маской в конце,
+например “<literal>mail.*</literal>”
+</listitem>
+
+<listitem>
+первое подходящее регулярное выражение
+(в порядке следования в конфигурационном файле)
+</listitem>
+
+<listitem>
+значение по умолчанию (<literal>default</literal>)
+</listitem>
+
+</list>
+</para>
+
 </directive>