ap_expr expression parser

Grammar in Backus-Naur Form notation

Backus-Naur Form (BNF) is a notation technique for context-free grammars, often used to describe the syntax of languages used in computing. In most cases, expressions are used to express boolean values. For these, the starting point in the BNF is expr. However, a few directives accept expressions that evaluate to a string value. For those, the starting point in the BNF is string.

expr 

::= "true" | "false"
  | "!" expr
  | expr "&&" expr
  | expr "||" expr
  | "(" expr ")"
  | comp

comp  

::= stringcomp
  | integercomp
  | unaryop word
  | word binaryop word
  | word "in" "{" wordlist "}"
  | word "in" listfunction
  | word "=~" regex
  | word "!~" regex

stringcomp  

::= word "==" word
  | word "!=" word
  | word "<"  word
  | word "<=" word
  | word ">"  word
  | word ">=" word

integercomp  

::= word "-eq" word | word "eq" word
  | word "-ne" word | word "ne" word
  | word "-lt" word | word "lt" word
  | word "-le" word | word "le" word
  | word "-gt" word | word "gt" word
  | word "-ge" word | word "ge" word

wordlist  

::= word
  | wordlist "," word

word  

::= word "." word
  | digit
  | "'" string "'"
  | """ string """
  | variable
  | rebackref
  | function

string  

::= stringpart
  | string stringpart

stringpart  

::= cstring
  | variable
  | rebackref

cstring
digit

::= ...
::= [0-9]+

variable  

::= "%{" varname "}"
  | "%{" funcname ":" funcargs "}"

rebackref  

::= "$" [0-9]

function  

::= funcname "(" wordlist ")"

listfunction  

::= listfuncname "(" word ")"

Variables

The expression parser provides a number of variables of the form %{HTTP_HOST}. Note that the value of a variable may depend on the phase of the request processing in which it is evaluated. For example, an expression used in an <If> directive is evaluated before authentication is done. Therefore, %{REMOTE_USER} will not be set in this case.

The following variables provide the values of the named HTTP request headers. The values of other headers can be obtained with the req function(see below). Using these variables may cause the header name to be added to the Vary header of the HTTP response, except where otherwise noted for the directive accepting the expression. The req_novary function(see below) may be used to circumvent this behavior.

Example:

# Compare the host name to example.com and redirect to www.example.com if it matches
<If "%{HTTP_HOST} == 'example.com'">
    Redirect permanent "/" "http://www.example.com/"
</If>

Example:

# Force text/plain if requesting a file with the query string contains 'forcetext'
<If "%{QUERY_STRING} =~ /forcetext/">
        ForceType text/plain
</If>

See Environment variables set by HTTP Server for more variables information.

Example:

#  Only allow access to this content during business hours
<Directory "/www/webserver/htdocs/business">
        Require expr %{TIME_HOUR} -gt 9 && %{TIME_HOUR} -lt 17
</Directory>

Binary operators

Binary operators have the form "-[a-zA-Z][a-zA-Z0-9_]+", i.e. a minus and at least two characters. The name is not case sensitive.

Example:

# Compare the IP address of the remote host to 127.0.0.1/8 and redirect to localhost:8080 if it matches
<If "%{REMOTE_ADDR} -ipmatch '127.0.0.1/8'">
   Redirect permanent "/" "http://localhost:8080/"
</If>

Unary operators

Unary operators take one argument and have the form "-[a-zA-Z]", i.e. a minus and one character. The name is case sensitive.

Example:

# Check result of URI mapping by running in Directory context with -f
<Directory "/www/webserver/htdocs">
     AddEncoding x-gzip gz
<If "-f '%{REQUEST_FILENAME}.unzipme' && ! %{HTTP:Accept-Encoding} =~ /gzip/">
      SetOutputFilter INFLATE
</If>
</Directory>

Functions

Normal string-valued functions take one string as argument and return a string. Functions names are not case sensitive.

When the functions req or http are used, the header name will automatically be added to the Vary header of the HTTP response, except where otherwise noted for the directive accepting the expression. The req_novary function can be used to prevent names from being added to the Vary header.

In addition to string-valued functions, there are also list-valued functions which take one string as argument and return a wordlist, i.e. a list of strings. The wordlist can be used with the special -in operator (see below). Functions names are not case sensitive. There are no built-in list-valued functions.

Examples:

# Check an environment variable for a regular expression, negated.
<If "! reqenv('REDIRECT_FOO') =~ /bar/">
     Header set matched true
</If>

# Function examples in boolean context
<If "md5('foo') == 'acbd18db4cc2f85cedef654fccc4a4d8'">
     Header set checksum-matched true
</If>
<If "md5('foo') == replace('md5:XXXd18db4cc2f85cedef654fccc4a4d8', 'md5:XXX', 'acb')>
     Header set checksum-matched-2 true
</If>

# Function example in string context
Header set foo-checksum "expr=%{md5:foo}"

# This delays the evaluation of the condition clause compared to <If>
Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path\.php$#"

Other

Example:

# Check a HTTP header for a list of values
<If "%{HTTP:X-example-header} in { 'foo', 'bar', 'baz' }">
     Header set matched true
</If>