granicus.if.org Git - apache/blob - docs/manual/expr.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision: 1055507 $ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="expr.xml.meta">
  24
  25   <title>Expressions in Apache HTTP Server</title>
  26
  27   <summary>
  28     <p>Historically, there are several syntax variants for expressions used to express
  29         a condition in the different modules of the Apache HTTP Server.
  30         There is some ongoing effort to only use a single variant, called <em>ap_expr</em>,
  31         for all configuration directives.
  32         This document describes the <em>ap_expr</em> expression parser.
  33     </p>
  34   </summary>
  35
  36 <seealso><directive module="core">If</directive></seealso>
  37 <seealso><module>mod_rewrite</module></seealso>
  38 <seealso><module>mod_include</module></seealso>
  39 <seealso><module>mod_setenvif</module></seealso>
  40 <seealso><directive module="mod_ssl">SSLRequire</directive></seealso>
  41 <seealso><directive module="mod_filter">FilterProvider</directive></seealso>
  42
  43   <section id="grammar">
  44     <title>Grammar in Backus–Naur Form notation</title>
  45       <p><a href="http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form">Backus–Naur Form</a> (BNF) is a notation
  46       technique for context-free grammars, often used to describe the syntax of languages used in computing.
  47       </p>
  48 <blockquote>
  49 <pre>
  50 expr        ::= "<strong>true</strong>" | "<strong>false</strong>"
  51               | "<strong>!</strong>" expr
  52               | expr "<strong>&amp;&amp;</strong>" expr
  53               | expr "<strong>||</strong>" expr
  54               | "<strong>(</strong>" expr "<strong>)</strong>"
  55               | comp
  56
  57 comp        ::= stringcomp
  58               | integercomp
  59               | unaryop word
  60               | word binaryop word
  61               | word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>"
  62               | word "<strong>in</strong>" listfunction
  63               | word "<strong>=~</strong>" regex
  64               | word "<strong>!~</strong>" regex
  65
  66
  67 stringcomp  ::= word "<strong>==</strong>" word
  68               | word "<strong>!=</strong>" word
  69               | word "<strong>&lt;</strong>"  word
  70               | word "<strong>&lt;=</strong>" word
  71               | word "<strong>&gt;</strong>"  word
  72               | word "<strong>&gt;=</strong>" word
  73
  74 integercomp ::= word "<strong>-eq</strong>" word | word "<strong>eq</strong>" word
  75               | word "<strong>-ne</strong>" word | word "<strong>ne</strong>" word
  76               | word "<strong>-lt</strong>" word | word "<strong>lt</strong>" word
  77               | word "<strong>-le</strong>" word | word "<strong>le</strong>" word
  78               | word "<strong>-gt</strong>" word | word "<strong>gt</strong>" word
  79               | word "<strong>-ge</strong>" word | word "<strong>ge</strong>" word
  80
  81 wordlist    ::= word
  82               | wordlist "<strong>,</strong>" word
  83
  84 word        ::= word "<strong>.</strong>" word
  85               | digit
  86               | "<strong>'</strong>" string "<strong>'</strong>"
  87               | "<strong>"</strong>" string "<strong>"</strong>"
  88               | variable
  89               | rebackref
  90               | function
  91
  92 string      ::= stringpart
  93               | string stringpart
  94
  95 stringpart  ::= cstring
  96               | variable
  97               | rebackref
  98
  99 cstring     ::= ...
 100 digit       ::= [0-9]+
 101
 102 variable    ::= "<strong>%{</strong>" varname "<strong>}</strong>"
 103               | "<strong>%{</strong>" funcname "<strong>:</strong>" funcargs "<strong>}</strong>"
 104
 105 rebackref   ::= "<strong>$</strong>" [0-9]
 106
 107 function     ::= funcname "<strong>(</strong>" word "<strong>)</strong>"
 108
 109 listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>"
 110 </pre>
 111 </blockquote>
 112
 113 </section>
 114
 115 <section id="vars">
 116     <title>Variables</title>
 117
 118     <p>The expression parser provides a number of variables of the form
 119     <code>%{HTTP_HOST}</code>. Note that the value of a variable may depend
 120     on the phase of the request processing in which it is evaluated.  For
 121     example, an expression used in an <directive>&lt;If &gt;</directive>
 122     directive is evaluated before authentication is done. Therefore,
 123     <code>%{REMOTE_USER}</code> will not be set in this case.</p>
 124
 125     <p>The following variables provide the values of the named HTTP request
 126     headers. The values of other headers can be obtained witht the
 127     <code>req</code> <a href="#functions">function</a>.</p>
 128
 129     <table border="1" style="zebra">
 130     <columnspec><column width="1"/></columnspec>
 131
 132     <tr><th>Name</th></tr>
 133     <tr><td><code>HTTP_ACCEPT</code></td></tr>
 134     <tr><td><code>HTTP_FORWARDED</code></td></tr>
 135     <tr><td><code>HTTP_HOST</code></td></tr>
 136     <tr><td><code>HTTP_PROXY_CONNECTION</code></td></tr>
 137     <tr><td><code>HTTP_REFERER</code></td></tr>
 138     <tr><td><code>HTTP_USER_AGENT</code></td></tr>
 139
 140     </table>
 141
 142     <p>Other request related variables</p>
 143
 144     <table border="1" style="zebra">
 145     <columnspec><column width=".4"/><column width=".6"/></columnspec>
 146
 147     <tr><th>Name</th><th>Description</th></tr>
 148     <tr><td><code>REQUEST_METHOD</code></td>
 149         <td>The HTTP method of the incoming request (e.g.
 150             <code>GET</code>)</td></tr>
 151     <tr><td><code>REQUEST_SCHEME</code></td>
 152         <td>The scheme part of the request's URI</td></tr>
 153     <tr><td><code>REQUEST_URI</code></td>
 154         <td>The URI of the request</td></tr>
 155     <tr><td><code>REQUEST_FILENAME</code></td>
 156         <td></td></tr>
 157     <tr><td><code>SCRIPT_FILENAME</code></td>
 158         <td>Same as <code>REQUEST_FILENAME</code></td></tr>
 159     <tr><td><code>SCRIPT_USER</code></td>
 160         <td>The user name of the owner of the script.</td></tr>
 161     <tr><td><code>SCRIPT_GROUP</code></td>
 162         <td>The group name of the group of the script.</td></tr>
 163     <tr><td><code>PATH_INFO</code></td>
 164         <td></td></tr>
 165     <tr><td><code>QUERY_STRING</code></td>
 166         <td>The query string of the current request</td></tr>
 167     <tr><td><code>IS_SUBREQ</code></td>
 168         <td>"<code>true</code>" if the current request is a subrequest,
 169             "<code>false</code>" otherwise</td></tr>
 170     <tr><td><code>THE_REQUEST</code></td>
 171         <td>The complete request line (e.g.,
 172             "<code>GET /index.html HTTP/1.1</code>")</td></tr>
 173     <tr><td><code>REMOTE_ADDR</code></td>
 174         <td>The IP address of the remote host</td></tr>
 175     <tr><td><code>REMOTE_HOST</code></td>
 176         <td>The host name of the remote host</td></tr>
 177     <tr><td><code>REMOTE_USER</code></td>
 178         <td>The name of the authenticated user (if any)</td></tr>
 179     <tr><td><code>REMOTE_IDENT</code></td>
 180         <td>The user name set by <module>mod_ident</module></td></tr>
 181     <tr><td><code>SERVER_NAME</code></td>
 182         <td>The <directive module="core">ServerName</directive> of
 183             the current vhost</td></tr>
 184     <tr><td><code>SERVER_PORT</code></td>
 185         <td>The server port of the current vhost, see
 186             <directive module="core">ServerName</directive></td></tr>
 187     <tr><td><code>SERVER_ADMIN</code></td>
 188         <td>The <directive module="core">ServerAdmin</directive> of
 189             the current vhost</td></tr>
 190     <tr><td><code>SERVER_PROTOCOL</code></td>
 191         <td>The protocol used by the request</td></tr>
 192     <tr><td><code>DOCUMENT_ROOT</code></td>
 193         <td>The <directive module="core">DocumentRoot</directive> of
 194             the current vhost</td></tr>
 195     <tr><td><code>AUTH_TYPE</code></td>
 196         <td>The configured <directive module="mod_authn_core">AuthType</directive>
 197             (e.g. "<code>basic</code>")</td></tr>
 198     <tr><td><code>CONTENT_TYPE</code></td>
 199         <td>The content type of the response</td></tr>
 200     <tr><td><code>HANDLER</code></td>
 201         <td>The name of the <a href="handler.html">handler</a> creating
 202             the response</td></tr>
 203     <tr><td><code>HTTPS</code></td>
 204         <td>"<code>on</code>" if the request uses https,
 205             "<code>off</code>" otherwise</td></tr>
 206     <tr><td><code>IPV6</code></td>
 207         <td>"<code>on</code>" if the connection uses IPv6,
 208             "<code>off</code>" otherwise</td></tr>
 209     <tr><td><code>REQUEST_LOG_ID</code></td>
 210         <td>The error log id of the request (see
 211             <directive module="core">ErrorLogFormat</directive>)</td></tr>
 212     <tr><td><code>CONN_LOG_ID</code></td>
 213         <td>The error log id of the connection (see
 214             <directive module="core">ErrorLogFormat</directive>)</td></tr>
 215
 216     </table>
 217
 218     <p>Misc variables</p>
 219
 220     <table border="1" style="zebra">
 221     <columnspec><column width=".4"/><column width=".6"/></columnspec>
 222
 223     <tr><th>Name</th><th>Description</th></tr>
 224     <tr><td><code>TIME_YEAR</code></td>
 225         <td>The current year (e.g. <code>2010</code>)</td></tr>
 226     <tr><td><code>TIME_MON</code></td>
 227         <td>The current month (<code>1</code>, ..., <code>12</code>)</td></tr>
 228     <tr><td><code>TIME_DAY</code></td>
 229         <td>The current day of the month</td></tr>
 230     <tr><td><code>TIME_HOUR</code></td>
 231         <td>The hour part of the current time
 232             (<code>0</code>, ..., <code>23</code>)</td></tr>
 233     <tr><td><code>TIME_MIN</code></td>
 234         <td>The minute part of the current time </td></tr>
 235     <tr><td><code>TIME_SEC</code></td>
 236         <td>The second part of the current time </td></tr>
 237     <tr><td><code>TIME_WDAY</code></td>
 238         <td>The day of the week (starting with <code>0</code>
 239             for Sunday)</td></tr>
 240     <tr><td><code>TIME</code></td>
 241         <td>The date and time in the format <code>20101231235959</code></td></tr>
 242     <tr><td><code>SERVER_SOFTWARE</code></td>
 243         <td>The server version string</td></tr>
 244     <tr><td><code>API_VERSION</code></td>
 245         <td>The date of the API version (module magic number)</td></tr>
 246     </table>
 247
 248     <p>Some modules register additional variables, see e.g. <module>mod_ssl</module>.</p>
 249
 250 </section>
 251
 252 <section id="binop">
 253     <title>Binary operators</title>
 254
 255     <p>With the exception of some built-in comparison operators, binary
 256     operators have the form "<code>-[a-zA-Z][a-zA-Z0-9_]+</code>", i.e. a
 257     minus and at least two characters. The name is not case sensitive.
 258     Modules may register additional binary operators.</p>
 259
 260     <section id="comp">
 261     <title>Comparison operators</title>
 262
 263     <table border="1" style="zebra">
 264     <columnspec><column width=".2"/><column width=".2"/><column width=".6"/></columnspec>
 265
 266     <tr><th>Name</th><th>Alternative</th> <th>Description</th></tr>
 267     <tr><td><code>==</code></td>
 268         <td><code>=</code></td>
 269         <td>String equality</td></tr>
 270     <tr><td><code>!=</code></td>
 271         <td></td>
 272         <td>String inequality</td></tr>
 273     <tr><td><code>&lt;</code></td>
 274         <td></td>
 275         <td>String less than</td></tr>
 276     <tr><td><code>&lt;=</code></td>
 277         <td></td>
 278         <td>String less than or equal</td></tr>
 279     <tr><td><code>&gt;</code></td>
 280         <td></td>
 281         <td>String greater than</td></tr>
 282     <tr><td><code>&gt;=</code></td>
 283         <td></td>
 284         <td>String greater than or equal</td></tr>
 285     <tr><td><code>-eq</code></td>
 286         <td><code>eq</code></td>
 287         <td>Integer equality</td></tr>
 288     <tr><td><code>-ne</code></td>
 289         <td><code>ne</code></td>
 290         <td>Integer inequality</td></tr>
 291     <tr><td><code>-lt</code></td>
 292         <td><code>lt</code></td>
 293         <td>Integer less than</td></tr>
 294     <tr><td><code>-le</code></td>
 295         <td><code>le</code></td>
 296         <td>Integer less than or equal</td></tr>
 297     <tr><td><code>-gt</code></td>
 298         <td><code>gt</code></td>
 299         <td>Integer greater than</td></tr>
 300     <tr><td><code>-ge</code></td>
 301         <td><code>ge</code></td>
 302         <td>Integer greater than or equal</td></tr>
 303     </table>
 304     </section>
 305
 306     <section id="binaryother">
 307     <title>Other binary operators</title>
 308
 309     <table border="1" style="zebra">
 310     <columnspec><column width=".2"/><column width=".8"/></columnspec>
 311
 312     <tr><th>Name</th><th>Description</th></tr>
 313     <tr><td><code>-ipmatch</code></td>
 314         <td>IP address matches address/netmask</td></tr>
 315     <tr><td><code>-strmatch</code></td>
 316         <td>left string matches pattern given by right string (containing
 317             wildcards *, ?, [])</td></tr>
 318     <tr><td><code>-strcmatch</code></td>
 319         <td>same as <code>-strmatch</code>, but case insensitive</td></tr>
 320     <tr><td><code>-fnmatch</code></td>
 321         <td>same as <code>-strmatch</code>, but slashes are not matched by
 322             wildcards</td></tr>
 323     </table>
 324     </section>
 325
 326 </section>
 327
 328 <section id="unnop">
 329     <title>Unary operators</title>
 330
 331     <p>Unary operators have the form "<code>-[a-zA-Z]</code>", i.e. a
 332     minus and one character. The name <em>is</em> case sensitive.
 333     Modules may register additional unary operators.</p>
 334
 335     <table border="1" style="zebra">
 336     <columnspec><column width=".2"/><column width=".2"/><column width=".6"/></columnspec>
 337
 338     <tr><th>Name</th><th>Description</th></tr>
 339     <tr><td><code>-n</code></td>
 340         <td>True if string is not empty</td></tr>
 341     <tr><td><code>-z</code></td>
 342         <td>True if string is empty</td></tr>
 343     <tr><td><code>-T</code></td>
 344         <td>False if string is empty, "<code>0</code>", "<code>off</code>",
 345             "<code>false</code>", or "<code>no</code>" (case insensitive).
 346             True otherwise.</td></tr>
 347     <tr><td><code>-R</code></td>
 348         <td>Same as "<code>%{REMOTE_ADDR} -ipmatch ...</code>", but more efficient
 349         </td></tr>
 350     </table>
 351
 352 </section>
 353
 354 <section id="functions">
 355     <title>Functions</title>
 356
 357     <p>Normal string-valued functions take one string as argument and return
 358     a string. Functions names are not case sensitive.
 359     Modules may register additional functions.</p>
 360
 361     <table border="1" style="zebra">
 362     <columnspec><column width=".2"/><column width=".8"/></columnspec>
 363
 364     <tr><th>Name</th><th>Description</th></tr>
 365     <tr><td><code>req</code>, <code>http</code></td>
 366         <td>Get HTTP request header</td></tr>
 367     <tr><td><code>resp</code></td>
 368         <td>Get HTTP response header</td></tr>
 369     <tr><td><code>reqenv</code></td>
 370         <td>Lookup request environment variable</td></tr>
 371     <tr><td><code>osenv</code></td>
 372         <td>Lookup operating system environment variable</td></tr>
 373     <tr><td><code>note</code></td>
 374         <td>Lookup request note</td></tr>
 375     <tr><td><code>env</code></td>
 376         <td>Return first match of <code>note</code>, <code>reqenv</code>,
 377             <code>osenv</code></td></tr>
 378     <tr><td><code>tolower</code></td>
 379         <td>Convert string to lower case</td></tr>
 380     <tr><td><code>toupper</code></td>
 381         <td>Convert string to uppser case</td></tr>
 382     <tr><td><code>escape</code></td>
 383         <td>Escape special characters in %hex encoding</td></tr>
 384     <tr><td><code>unescape</code></td>
 385         <td>Unescape %hex encoded string, leaving URL-special characters encoded (XXX: describe better)</td></tr>
 386     <tr><td><code>file</code></td>
 387         <td>Read contents from a file</td></tr>
 388     </table>
 389
 390     <p>In addition to string-valued functions, there are also list-valued functions which
 391     take one string as argument and return a wordlist, i.e. a list of strings. The wordlist
 392     can be used with the special <code>-in</code> operator.
 393     Functions names are not case sensitive.
 394     Modules may register additional functions.</p>
 395
 396     <p>There are no built-in list-valued functions. <module>mod_ssl</module>
 397     provides <code>PeerExtList</code>.  See the description of
 398     <directive module="mod_ssl">SSLRequire</directive> for details
 399     (but <code>PeerExtList</code> is also usable outside
 400     of <directive module="mod_ssl">SSLRequire</directive>).</p>
 401
 402 </section>
 403
 404 <section id="other">
 405     <title>Other</title>
 406
 407     <table border="1" style="zebra">
 408     <columnspec><column width=".2"/><column width=".2"/><column width=".6"/></columnspec>
 409
 410     <tr><th>Name</th><th>Alternative</th> <th>Description</th></tr>
 411     <tr><td><code>-in</code></td>
 412         <td><code>in</code></td>
 413         <td>string contained in string list</td></tr>
 414     <tr><td><code>/regexp/</code></td>
 415         <td><code>m#regexp#</code></td>
 416         <td>Regular expression (the second form allows different delimiters than /)</td></tr>
 417     <tr><td><code>/regexp/i</code></td>
 418         <td><code>m#regexp#i</code></td>
 419         <td>Case insensitive regular expression</td></tr>
 420     <tr><td><code>$0 ... $9</code></td>
 421         <td></td>
 422         <td>Regular expression backreferences</td></tr>
 423     </table>
 424
 425     <section id="rebackref">
 426         <title>Regular expression backreferences</title>
 427         <p>The strings <code>$0</code> ... <code>$9</code> allow to reference
 428         the capture groups from a previously executed, successfully
 429         matching regular expressions. They can normally only be used in the
 430         same expression as the matching regex, but some modules allow special
 431         uses.</p>
 432     </section>
 433
 434 </section>
 435
 436 </manualpage>