Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_map_module.xml @ 572:17ceffcc7ffb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
571:71d775bef043 572:17ceffcc7ffb
30 example.org 2; 30 example.org 2;
31 *.example.org 2; 31 *.example.org 2;
32 .example.net 3; 32 .example.net 3;
33 wap.* 4; 33 wap.* 4;
34 } 34 }
35
36 map $http_user_agent $mobile {
37 default 0;
38 "~Opera Mini" 1;
39 }
35 </example> 40 </example>
36 </para> 41 </para>
37 42
38 </section> 43 </section>
39 44
40 45
41 <section id="directives" name="Directives"> 46 <section id="directives" name="Directives">
42 47
43 <directive name="map"> 48 <directive name="map">
44 <syntax block="yes"> 49 <syntax block="yes">
45 <value>$variable1</value> 50 <value>string</value>
46 <value>$variable2</value></syntax> 51 <value>$variable</value></syntax>
47 <default/> 52 <default/>
48 <context>http</context> 53 <context>http</context>
49 54
50 <para> 55 <para>
51 Creates a variable whose value 56 Creates a new variable whose value
52 depends on the value of another variable. 57 depends on values of one or more of the source variables
53 The directive supports three special parameters: 58 specified in the first parameter.
59 <note>
60 Before version 0.9.0 only a single variable could be
61 specified in the first parameter.
62 </note>
63 </para>
64
65 <para>
66 Parameters inside the <literal>map</literal> block specify a mapping
67 between source and resulting values.
68 </para>
69
70 <para>
71 Source values are specified as strings or regular expressions (0.9.6).
72 </para>
73
74 <para>
75 A regular expression should either start from the “<literal>~</literal>”
76 symbol for a case-sensitive matching, or from the “<literal>~*</literal>”
77 symbols (1.0.4) for case-insensitive matching.
78 A regular expression can contain named and positional captures
79 that can later be used in other directives along with the
80 resulting variable.
81 </para>
82
83 <para>
84 If a source value matches one of the names of special parameters
85 (see below), it should be prefixed with the “<literal>\</literal>” symbol.
86 </para>
87
88 <para>
89 The resulting value can be a string
90 or another variable (0.9.0).
91 </para>
92
93 <para>
94 The directive also supports three special parameters:
54 <list type="tag"> 95 <list type="tag">
55 <tag-name><literal>default</literal> <value>value</value></tag-name> 96 <tag-name><literal>default</literal> <value>value</value></tag-name>
56 <tag-desc> 97 <tag-desc>
57 sets a value for the second variable when the value 98 sets the resulting value if the source value matches none
58 of the first variable cannot be found. 99 of the specified variants.
100 When <literal>default</literal> is not specified, the default
101 resulting value will be an empty string.
59 </tag-desc> 102 </tag-desc>
60 103
61 <tag-name><literal>hostnames</literal></tag-name> 104 <tag-name><literal>hostnames</literal></tag-name>
62 <tag-desc> 105 <tag-desc>
63 allows to specify hostnames with a prefix or suffix mask, as source 106 allows to specify hostnames with a prefix or suffix mask, as source
73 </example> 116 </example>
74 can be combined: 117 can be combined:
75 <example> 118 <example>
76 .example.com 1; 119 .example.com 1;
77 </example> 120 </example>
121 This parameter should be specified before the list of values.
78 </tag-desc> 122 </tag-desc>
79 123
80 <tag-name><literal>include</literal> <value>file</value></tag-name> 124 <tag-name><literal>include</literal> <value>file</value></tag-name>
81 <tag-desc> 125 <tag-desc>
82 includes a file with values. 126 includes a file with values.
83 There can be several inclusions. 127 There can be several inclusions.
84 </tag-desc> 128 </tag-desc>
129
130 </list>
131 </para>
132
133 <para>
134 If the source value matches more than one of the specified variants,
135 e.g. both mask and regular expression match, the first matching
136 variant will be choosen, in the following order of precedence:
137 <list type="enum">
138
139 <listitem>
140 string value without a mask
141 </listitem>
142
143 <listitem>
144 longest string value with a prefix mask,
145 e.g. “<literal>*.example.com</literal>”
146 </listitem>
147
148 <listitem>
149 longest string value with a suffix mask,
150 e.g. “<literal>mail.*</literal>”
151 </listitem>
152
153 <listitem>
154 first matching regular expression
155 (in order of appearance in a configuration file)
156 </listitem>
157
158 <listitem>
159 default value
160 </listitem>
85 161
86 </list> 162 </list>
87 </para> 163 </para>
88 164
89 </directive> 165 </directive>