<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_stream_map_module"
        link="/ru/docs/stream/ngx_stream_map_module.html"
        lang="ru"
        rev="2">

<section id="summary">

<para>
Модуль <literal>ngx_stream_map_module</literal> (1.11.2) создаёт переменные,
значения которых зависят от значений других переменных.
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
map $remote_addr $limit {
    127.0.0.1    "";
    default      $binary_remote_addr;
}

limit_conn_zone $limit zone=addr:10m;
limit_conn addr 1;
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="map">
<syntax block="yes">
    <value>строка</value>
    <value>$переменная</value></syntax>
<default/>
<context>stream</context>

<para>
Создаёт новую переменную, значение которой
зависит от значений одной или более исходных переменных,
указанных в первом параметре.
</para>

<para>
<note>
Поскольку переменные вычисляются только в момент использования,
само по себе наличие даже большого числа объявлений переменных
“<literal>map</literal>” не влечёт за собой никаких дополнительных
расходов на обработку соединений.
</note>
</para>

<para>
Параметры внутри блока <literal>map</literal> задают соответствие
между исходными и результирующими значениями.
</para>

<para>
Исходные значения задаются строками или регулярными выражениями.
</para>

<para>
Строки проверяются без учёта регистра.
</para>

<para>
Перед регулярным выражением ставится символ “<literal>~</literal>”,
если при сравнении следует учитывать регистр символов, либо символы
“<literal>~*</literal>”, если регистр символов учитывать не нужно.
Регулярное выражение может содержать именованные и позиционные выделения,
которые могут затем использоваться в других директивах совместно с
результирующей переменной.
</para>

<para>
Если исходное значение совпадает с именем одного из специальных параметров,
описанных ниже, перед ним следует поставить символ “<literal>\</literal>”.
</para>

<para>
В качестве результирующего значения можно указать текст,
переменную и их комбинации.
</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>
<tag-desc>
указывает, что в качестве исходных значений можно
использовать маску для первой или последней части имени хоста, например,
<example>
*.example.com 1;
example.*     1;
</example>
Вместо двух записей
<example>
example.com   1;
*.example.com 1;
</example>
можно использовать одну:
<example>
.example.com  1;
</example>
Этот параметр следует указывать перед списком значений.
</tag-desc>

<tag-name><literal>include</literal> <value>файл</value></tag-name>
<tag-desc>
включает файл со значениями.
Включений может быть несколько.
</tag-desc>

<tag-name id="volatile"><literal>volatile</literal></tag-name>
<tag-desc>
указывает, что переменная не кэшируется (1.11.7).
</tag-desc>

</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>


<directive name="map_hash_bucket_size">
<syntax><value>размер</value></syntax>
<default>32|64|128</default>
<context>stream</context>

<para>
Задаёт размер корзины в хэш-таблицах для переменных <link id="map"/>.
Значение по умолчанию зависит от размера строки кэша процессора.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>


<directive name="map_hash_max_size">
<syntax><value>размер</value></syntax>
<default>2048</default>
<context>stream</context>

<para>
Задаёт максимальный размер хэш-таблиц для переменных <link id="map"/>.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>

</section>

</module>