<?xml version="1.0"?>

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

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

<module name="Module ngx_http_map_module"
        link="/en/docs/http/ngx_http_map_module.html"
        lang="en"
        rev="5">

<section id="summary">

<para>
The <literal>ngx_http_map_module</literal> module creates variables
whose values depend on values of other variables.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
map $http_host $name {
    hostnames;

    default       0;

    example.com   1;
    *.example.com 1;
    example.org   2;
    *.example.org 2;
    .example.net  3;
    wap.*         4;
}

map $http_user_agent $mobile {
    default       0;
    "~Opera Mini" 1;
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="map">
<syntax block="yes">
    <value>string</value>
    <value>$variable</value></syntax>
<default/>
<context>http</context>

<para>
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>
<note>
Since variables are evaluated only when they are used, the mere declaration
even of a large number of “<literal>map</literal>” variables
does not add any extra costs to request processing.
</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>
Strings are matched ignoring the case.
</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
described below, it should be prefixed with the “<literal>\</literal>” symbol.
</para>

<para>
The resulting value can contain text,
variable (0.9.0), and their combination (1.11.0).
</para>

<para>
The following special parameters are also supported:
<list type="tag">
<tag-name><literal>default</literal> <value>value</value></tag-name>
<tag-desc>
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>
<tag-desc>
indicates that source values can be hostnames with a prefix or suffix mask:
<example>
*.example.com 1;
example.*     1;
</example>
The following two records
<example>
example.com   1;
*.example.com 1;
</example>
can be combined:
<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>
<tag-desc>
includes a file with values.
There can be several inclusions.
</tag-desc>

<tag-name id="volatile"><literal>volatile</literal></tag-name>
<tag-desc>
indicates that the variable is not cacheable (1.11.7).
</tag-desc>

</list>
</para>

<para>
If the source value matches more than one of the specified variants,
e.g. both a mask and a regular expression match, the first matching
variant will be chosen, in the following order of priority:
<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>


<directive name="map_hash_bucket_size">
<syntax><value>size</value></syntax>
<default>32|64|128</default>
<context>http</context>

<para>
Sets the bucket size for the <link id="map"/> variables hash tables.
Default value depends on the processor’s cache line size.
The details of setting up hash tables are provided in a separate
<link doc="../hash.xml">document</link>.
</para>

</directive>


<directive name="map_hash_max_size">
<syntax><value>size</value></syntax>
<default>2048</default>
<context>http</context>

<para>
Sets the maximum <value>size</value> of the <link id="map"/> variables
hash tables.
The details of setting up hash tables are provided in a separate
<link doc="../hash.xml">document</link>.
</para>

</directive>

</section>

</module>