From: Yann Ylavic Date: Wed, 4 Oct 2017 17:08:13 +0000 (+0000) Subject: Follow up to r1810605. X-Git-Tag: 2.5.0-alpha~62 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f0de48a35e3006cfd7e1e519622560d433558ef4;p=apache Follow up to r1810605. Update docs' BNF, provide a short description of the new %{::} syntax and a few examples. To be continued.. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1811111 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/expr.xml b/docs/manual/expr.xml index 2431f9b113..89811890f1 100644 --- a/docs/manual/expr.xml +++ b/docs/manual/expr.xml @@ -79,29 +79,41 @@ 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 like LogMessage accept expressions + For these, the starting point in the BNF is cond. + Directives like ErrorDocument, + Require, + AuthName, + Redirect, + Header, + CryptoKey or + LogMessage 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 ")"
+expr        ::= cond
+              | string
+
+string      ::= substring
+              | string substring
+
+cond        ::= "true" 
+              | "false"
+              | "!" cond
+              | cond "&&" cond
+              | cond "||" cond
               | comp
+              | "(" cond ")"
 
 comp        ::= stringcomp
               | integercomp
               | unaryop word
               | word binaryop word
-              | word "in" "{" wordlist "}"
-              | word "in" listfunction
+              | word "in" listfunc
               | word "=~" regex
               | word "!~" regex
+              | word "in" "{" list "}"
 
 
 stringcomp  ::= word "==" word
@@ -118,35 +130,64 @@ integercomp ::= word "-eq" word | word "eq" wo
               | word "-gt" word | word "gt" word
               | word "-ge" word | word "ge" word
 
-wordlist    ::= word
-              | wordlist "," word
-
-word        ::= word "." word
-              | digit
+word        ::= digits
               | "'" string "'"
-              | """ string """
+              | '"' string '"'
+              | word "." word
               | variable
-              | rebackref
+              | sub
+              | join
               | function
+              | "(" word ")"
 
-string      ::= stringpart
-              | string stringpart
+list        ::= split
+              | listfunc
+              | "{" words "}"
+              | "(" list ")"
 
-stringpart  ::= cstring
+substring   ::= cstring
               | variable
-              | rebackref
-
-cstring     ::= ...
-digit       ::= [0-9]+
 
 variable    ::= "%{" varname "}"
               | "%{" funcname ":" funcargs "}"
+              | "%{:" word ":}"
+              | "%{:" cond ":}"
+              | rebackref
+
+sub         ::= "sub" ["("] regsub "," word [")"]
+
+join        ::= "join" ["("] list [")"]
+              | "join" ["("] list "," word [")"]
+
+split       ::= "split" ["("] regany "," list [")"]
+              | "split" ["("] regany "," word [")"]
+
+function    ::= funcname "(" words ")"
 
-rebackref   ::= "$" [0-9]
+listfunc    ::= listfuncname "(" words ")"
 
-function     ::= funcname "(" wordlist ")"
+words       ::= word
+              | word "," list
 
-listfunction ::= listfuncname "(" word ")"
+regex       ::= "/" regpattern "/" [regflags]
+              | "m" regsep regpattern regsep [regflags]
+
+regsub      ::= "s" regsep regpattern regsep string regsep [regflags]
+
+regany      ::= regex | regsub
+
+regsep      ::= "/" | "#" | "$" | "%" | "^" | "|" | "?" | "!" | "'" | '"' | "," | ";" | ":" | "." | "_" | "-"
+
+regflags    ::= 1*("i" | "s" | "m" | "g")
+regpattern  ::= cstring ; except enclosing regsep
+
+rebackref   ::= "$" DIGIT
+
+digits      ::= 1*(DIGIT)
+cstring     ::= 0*(TEXT)
+
+TEXT        ::= <any OCTET except CTLs>
+DIGIT       ::= <any US-ASCII digit "0".."9">
@@ -335,6 +376,21 @@ listfunction ::= listfuncname "(" word ")"

Some modules register additional variables, see e.g. mod_ssl.

+

Any variable can be embedded in a string, both in quoted + strings from boolean expressions but also in string expressions, + resulting in the concatenation of the constant and dynamic parts as + expected.

+ +

There exists another form of variables (temporaries) expressed like + %{:word:} and which allow embedding of the more + powerful word syntax (and constructs) in both type of expressions, + without colliding with the constant part of such strings. They are mainly + useful in string expressions though, since the word is directly + available in boolean expressions already. By using this form of variables, + one can evaluate regexes, substitutions, join and/or split strings and + lists in the scope of string expressions, hence construct complex strings + dynamically.

+
@@ -582,7 +638,7 @@ listfunction ::= listfuncname "(" word ")"

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 + list, i.e. a list of strings. The list can be used with the special -in operator. Functions names are not case sensitive. Modules may register additional functions.

@@ -654,6 +710,14 @@ 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$#" +# Add a header to forward client's certificate SAN to some backend +RequestHeader set X-Client-SAN "expr=%{:join PeerExtList('subjectAltName'):}" + +# Require that the remote IP be in the client's certificate SAN +Require expr %{REMOTE_ADDR} -in split s/.*?IP Address:([^,]+)/$1/, PeerExtList('subjectAltName') +# or alternatively: +Require expr "IP Address:%{REMOTE_ADDR}" -in split/, /, join PeerExtList('subjectAltName') +
@@ -666,7 +730,7 @@ Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path NameAlternative Description -in in - string contained in wordlist + string contained in list /regexp/ m#regexp# Regular expression (the second form allows different