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$ -->
   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</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   <section id="grammar">
  37     <title>Grammar in BNF notation</title>
  38 <blockquote>
  39 <pre>
  40 expr        ::= "<strong>true</strong>" | "<strong>false</strong>"
  41               | "<strong>!</strong>" expr
  42               | expr "<strong>&amp;&amp;</strong>" expr
  43               | expr "<strong>||</strong>" expr
  44               | "<strong>(</strong>" expr "<strong>)</strong>"
  45               | comp
  46
  47 comp        ::= stringcomp
  48               | integercomp
  49               | unaryop word
  50               | word binaryop word
  51               | word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>"
  52               | word "<strong>in</strong>" listfunction
  53               | word "<strong>=~</strong>" regex
  54               | word "<strong>!~</strong>" regex
  55
  56
  57 stringcomp  ::= word "<strong>==</strong>" word | word "<strong>eq</strong>" word
  58               | word "<strong>!=</strong>" word | word "<strong>ne</strong>" word
  59               | word "<strong>&lt;</strong>"  word | word "<strong>lt</strong>" word
  60               | word "<strong>&lt;=</strong>" word | word "<strong>le</strong>" word
  61               | word "<strong>&gt;</strong>"  word | word "<strong>gt</strong>" word
  62               | word "<strong>&gt;=</strong>" word | word "<strong>ge</strong>" word
  63
  64 integercomp ::= word "<strong>-eq</strong>" word | word "<strong>eq</strong>" word
  65               | word "<strong>-ne</strong>" word | word "<strong>ne</strong>" word
  66               | word "<strong>-lt</strong>" word | word "<strong>lt</strong>" word
  67               | word "<strong>-le</strong>" word | word "<strong>le</strong>" word
  68               | word "<strong>-gt</strong>" word | word "<strong>gt</strong>" word
  69               | word "<strong>-ge</strong>" word | word "<strong>ge</strong>" word
  70
  71 wordlist    ::= word
  72               | wordlist "<strong>,</strong>" word
  73
  74 word        ::= word "<strong>.</strong>" word
  75               | digit
  76               | "<strong>'</strong>" string "<strong>'</strong>"
  77               | "<strong>"</strong>" string "<strong>"</strong>"
  78               | variable
  79               | function
  80
  81 string      ::= stringpart
  82               | string stringpart
  83
  84 stringpart  ::= cstring
  85               | variable
  86
  87 cstring     ::= ...
  88 digit       ::= [0-9]+
  89
  90 variable    ::= "<strong>%{</strong>" varname "<strong>}</strong>"
  91               | "<strong>%{</strong>" funcname "<strong>:</strong>" funcargs "<strong>}</strong>"
  92
  93 function     ::= funcname "<strong>(</strong>" word "<strong>)</strong>"
  94
  95 listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>"
  96 </pre>
  97 </blockquote>
  98
  99 </section>
 100
 101 <section id="vars">
 102     <title>Variables</title>
 103 <p>XXX: not all vars are available in all request phases</p>
 104
 105     <p>Request headers (XXX:see req function)</p>
 106
 107     <table border="1" style="zebra">
 108     <columnspec><column width="1"/></columnspec>
 109
 110     <tr><th>Name</th></tr>
 111     <tr><td><code>HTTP_ACCEPT</code></td></tr>
 112     <tr><td><code>HTTP_FORWARDED</code></td></tr>
 113     <tr><td><code>HTTP_HOST</code></td></tr>
 114     <tr><td><code>HTTP_PROXY_CONNECTION</code></td></tr>
 115     <tr><td><code>HTTP_REFERER</code></td></tr>
 116     <tr><td><code>HTTP_USER_AGENT</code></td></tr>
 117
 118     </table>
 119
 120     <p>Other request related variables</p>
 121
 122     <table border="1" style="zebra">
 123     <columnspec><column width=".4"/><column width=".6"/></columnspec>
 124
 125     <tr><th>Name</th><th>Description</th></tr>
 126     <tr><td><code>REQUEST_METHOD</code></td>
 127         <td></td></tr>
 128     <tr><td><code>REQUEST_SCHEME</code></td>
 129         <td></td></tr>
 130     <tr><td><code>REQUEST_URI</code></td>
 131         <td></td></tr>
 132     <tr><td><code>REQUEST_FILENAME</code></td>
 133         <td></td></tr>
 134     <tr><td><code>REMOTE_HOST</code></td>
 135         <td></td></tr>
 136     <tr><td><code>REMOTE_IDENT</code></td>
 137         <td></td></tr>
 138     <tr><td><code>REMOTE_USER</code></td>
 139         <td></td></tr>
 140     <tr><td><code>SERVER_ADMIN</code></td>
 141         <td></td></tr>
 142     <tr><td><code>SERVER_NAME</code></td>
 143         <td></td></tr>
 144     <tr><td><code>SERVER_PORT</code></td>
 145         <td></td></tr>
 146     <tr><td><code>SERVER_PROTOCOL</code></td>
 147         <td></td></tr>
 148     <tr><td><code>SCRIPT_FILENAME</code></td>
 149         <td></td></tr>
 150     <tr><td><code>PATH_INFO</code></td>
 151         <td></td></tr>
 152     <tr><td><code>QUERY_STRING</code></td>
 153         <td></td></tr>
 154     <tr><td><code>IS_SUBREQ</code></td>
 155         <td></td></tr>
 156     <tr><td><code>DOCUMENT_ROOT</code></td>
 157         <td></td></tr>
 158     <tr><td><code>AUTH_TYPE</code></td>
 159         <td></td></tr>
 160     <tr><td><code>THE_REQUEST</code></td>
 161         <td></td></tr>
 162     <tr><td><code>CONTENT_TYPE</code></td>
 163         <td></td></tr>
 164     <tr><td><code>HANDLER</code></td>
 165         <td></td></tr>
 166     <tr><td><code>REMOTE_ADDR</code></td>
 167         <td></td></tr>
 168     <tr><td><code>HTTPS</code></td>
 169         <td></td></tr>
 170     <tr><td><code>IPV6</code></td>
 171         <td></td></tr>
 172
 173     </table>
 174
 175     <p>Misc variables</p>
 176
 177     <table border="1" style="zebra">
 178     <columnspec><column width=".4"/><column width=".6"/></columnspec>
 179
 180     <tr><th>Name</th><th>Description</th></tr>
 181     <tr><td><code>TIME_YEAR</code></td>
 182         <td></td></tr>
 183     <tr><td><code>TIME_MON</code></td>
 184         <td></td></tr>
 185     <tr><td><code>TIME_DAY</code></td>
 186         <td></td></tr>
 187     <tr><td><code>TIME_HOUR</code></td>
 188         <td></td></tr>
 189     <tr><td><code>TIME_MIN</code></td>
 190         <td></td></tr>
 191     <tr><td><code>TIME_SEC</code></td>
 192         <td></td></tr>
 193     <tr><td><code>TIME_WDAY</code></td>
 194         <td></td></tr>
 195     <tr><td><code>TIME</code></td>
 196         <td></td></tr>
 197     <tr><td><code>SERVER_SOFTWARE</code></td>
 198         <td></td></tr>
 199     <tr><td><code>API_VERSION</code></td>
 200         <td></td></tr>
 201     </table>
 202
 203 </section>
 204
 205 <section id="binop">
 206     <title>Binary operators</title>
 207
 208     <p>With the exception of some built-in comparison operators, binary
 209     operators have the form "<code>-[a-zA-Z][a-zA-Z0-9_]+</code>", i.e. a
 210     minus and at least two characters. The name is not case sensitive.
 211     Modules may register additional binary operators.</p>
 212
 213     <table border="1" style="zebra">
 214     <columnspec><column width=".2"/><column width=".2"/><column width=".6"/></columnspec>
 215
 216     <tr><th>Name</th><th>Alternative</th> <th>Description</th></tr>
 217     <tr><td><code>==</code></td>
 218         <td><code>=</code></td>
 219         <td>String equality</td></tr>
 220     <tr><td><code>!=</code></td>
 221         <td></td>
 222         <td>String inequality</td></tr>
 223     <tr><td><code>&lt;</code></td>
 224         <td></td>
 225         <td>String less than</td></tr>
 226     <tr><td><code>&lt;=</code></td>
 227         <td></td>
 228         <td>String less than or equal</td></tr>
 229     <tr><td><code>&gt;</code></td>
 230         <td></td>
 231         <td>String greater than</td></tr>
 232     <tr><td><code>&gt;=</code></td>
 233         <td></td>
 234         <td>String greater than or equal</td></tr>
 235     <tr><td><code>-eq</code></td>
 236         <td><code>eq</code></td>
 237         <td>Integer equality</td></tr>
 238     <tr><td><code>-ne</code></td>
 239         <td><code>ne</code></td>
 240         <td>Integer inequality</td></tr>
 241     <tr><td><code>-lt</code></td>
 242         <td><code>lt</code></td>
 243         <td>Integer less than</td></tr>
 244     <tr><td><code>-le</code></td>
 245         <td><code>le</code></td>
 246         <td>Integer less than or equal</td></tr>
 247     <tr><td><code>-gt</code></td>
 248         <td><code>gt</code></td>
 249         <td>Integer greater than</td></tr>
 250     <tr><td><code>-ge</code></td>
 251         <td><code>ge</code></td>
 252         <td>Integer greater than or equal</td></tr>
 253     </table>
 254
 255 </section>
 256
 257 <section id="unnop">
 258     <title>Unary operators</title>
 259
 260     <p>Unary operators have the form "<code>-[a-zA-Z]</code>", i.e. a
 261     minus and one character. The name <em>is</em> case sensitive.
 262     Modules may register additional unary operators.</p>
 263
 264     <table border="1" style="zebra">
 265     <columnspec><column width=".2"/><column width=".2"/><column width=".6"/></columnspec>
 266
 267     <tr><th>Name</th><th>Description</th></tr>
 268     <tr><td><code>-n</code></td>
 269         <td>String is not empty</td></tr>
 270     <tr><td><code>-z</code></td>
 271         <td>String is empty</td></tr>
 272     </table>
 273
 274 </section>
 275
 276 <section id="functions">
 277     <title>Functions</title>
 278
 279     <p>Normal string-valued functions take one string as argument and return
 280     a string. Functions names are not case sensitive.
 281     Modules may register additional functions.</p>
 282
 283     <table border="1" style="zebra">
 284     <columnspec><column width=".2"/><column width=".8"/></columnspec>
 285
 286     <tr><th>Name</th><th>Description</th></tr>
 287     <tr><td><code>req</code>, <code>http</code></td>
 288         <td>Get HTTP request header</td></tr>
 289     <tr><td><code>resp</code></td>
 290         <td>Get HTTP response header</td></tr>
 291     <tr><td><code>reqenv</code></td>
 292         <td>Lookup request environment variable</td></tr>
 293     <tr><td><code>osenv</code></td>
 294         <td>Lookup operating system environment variable</td></tr>
 295     <tr><td><code>note</code></td>
 296         <td>Lookup request environment variable</td></tr>
 297     <tr><td><code>env</code></td>
 298         <td>Reqturn first match of <code>note</code>, <code>reqenv</code>,
 299             <code>osenv</code></td></tr>
 300     <tr><td><code>tolower</code></td>
 301         <td>Convert string to lower case</td></tr>
 302     <tr><td><code>toupper</code></td>
 303         <td>Convert string to uppser case</td></tr>
 304     <tr><td><code>escape</code></td>
 305         <td>Escape special characters in %hex encoding</td></tr>
 306     <tr><td><code>unescape</code></td>
 307         <td>Unescape %hex encoded string, leaving URL-special characters encoded (XXX: describe better)</td></tr>
 308     <tr><td><code>file</code></td>
 309         <td>Read contents from a file</td></tr>
 310     </table>
 311
 312     <p>In addition to string-valued functions, there are also list-valued functions which
 313     take one string as argument and return a wordlist, i.e. a list of strings. The wordlist
 314     can be used with the special <code>-in</code> operator.
 315     Functions names are not case sensitive.
 316     Modules may register additional functions.</p>
 317
 318     <p>There are no built-in list-valued functions. mod_ssl provides
 319     <code>PeerExtList</code> (XXX: link)</p>
 320
 321 </section>
 322
 323 </manualpage>