=encoding utf-8

=head1 NAME

ngx_http_map_module - Module ngx_http_map_module




=head1



The C<ngx_http_map_module> module creates variables
whose values depend on values of other variables.




=head1 Example Configuration




    
    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;
    }






=head1 Directives

=head2 map


B<syntax:> map I<
    I<C<string>>
    I<C<$variable>> { B<...> } >



B<context:> I<http>





Creates a new variable whose value
depends on values of one or more of the source variables
specified in the first parameter.

B<NOTE>

Before version 0.9.0 only a single variable could be
specified in the first parameter.







B<NOTE>

Since variables are evaluated only when they are used, the mere declaration
even of a large number of “C<map>” variables
does not add any extra costs to request processing.






Parameters inside the C<map> block specify a mapping
between source and resulting values.





Source values are specified as strings or regular expressions (0.9.6).





Strings are matched ignoring the case.





A regular expression should either start from the “C<~>”
symbol for a case-sensitive matching, or from the “C<~*>”
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.





If a source value matches one of the names of special parameters
described below, it should be prefixed with the “C<\>” symbol.





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





The following special parameters are also supported:

=over


=item C<default> I<C<value>>




sets the resulting value if the source value matches none
of the specified variants.
When C<default> is not specified, the default
resulting value will be an empty string.



=item C<hostnames>




indicates that source values can be hostnames with a prefix or suffix mask:

    
    *.example.com 1;
    example.*     1;


The following two records

    
    example.com   1;
    *.example.com 1;


can be combined:

    
    .example.com  1;


This parameter should be specified before the list of values.



=item C<include> I<C<file>>




includes a file with values.
There can be several inclusions.



=item C<volatile>




indicates that the variable is not cacheable (1.11.7).




=back







The search is performed in the following order of priority
and terminates on the first matching variant:

=over




=item 1.

the string value without a mask



=item 2.

the longest string value with a prefix mask,
e.g. “C<*.example.com>”



=item 3.

the longest string value with a suffix mask,
e.g. “C<mail.*>”



=item 4.

the first matching regular expression
(in order of appearance in the configuration file)



=item 5.

the default value



=back









=head2 map_hash_bucket_size


B<syntax:> map_hash_bucket_size I<I<C<size>>>


B<default:> I<32E<verbar>64E<verbar>128>


B<context:> I<http>





Sets the bucket size for the L</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
L<document|hash>.







=head2 map_hash_max_size


B<syntax:> map_hash_max_size I<I<C<size>>>


B<default:> I<2048>


B<context:> I<http>





Sets the maximum I<C<size>> of the L</map> variables
hash tables.
The details of setting up hash tables are provided in a separate
L<document|hash>.







