add information about the == operator, && / || priorities and

expression optimization/debugging

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@101124 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/mod/mod_include.html.en b/docs/manual/mod/mod_include.html.en
index cfa8e1c41bbf076b095096c87897c17e5603115c..5e0fde9454845b5e5bb81328485b0f7313562968 100644 (file)
--- a/docs/manual/mod/mod_include.html.en
+++ b/docs/manual/mod/mod_include.html.en
@@ -507,6 +507,7 @@
       <dd>true if <var>string</var> is not empty</dd>
 
       <dt><code><var>string1</var> = <var>string2</var><br />
+      <var>string1</var> == <var>string2</var><br />
       <var>string1</var> != <var>string2</var></code></dt>
       
       <dd><p>Compare <var>string1</var> with <var>string2</var>. If
@@ -514,11 +515,12 @@
       then it is treated as a regular expression. Regular expressions are
       implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
       have the same syntax as those in <a href="http://www.perl.com">perl
-      5</a>.</p>
+      5</a>. Note that <code>==</code> is just an alias for <code>=</code>
+      and behaves exactly the same way.</p>
 
-      <p>If you are matching positive (<code>=</code>), you can capture
-      grouped parts of the regular expression. The captured parts are
-      stored in the special variables <code>$1</code> ..
+      <p>If you are matching positive (<code>=</code> or <code>==</code>), you
+      can capture grouped parts of the regular expression. The captured parts
+      are stored in the special variables <code>$1</code> ..
       <code>$9</code>.</p>
 
       <div class="example"><h3>Example</h3><p><code>
@@ -566,6 +568,10 @@
       &lt;!--#if expr="($a = test1) &amp;&amp; ($b = test2)" --&gt;
     </code></p></div>
 
+    <p>The boolean operators <code>&amp;&amp;</code> and <code>||</code>
+    share the same priority. So if you want to bind such an operator more
+    tightly, you should use parentheses.</p>
+
     <p>Anything that's not recognized as a variable or an operator
     is treated as a string. Strings can also be quoted:
     <code>'string'</code>. Unquoted strings can't contain whitespace
@@ -578,6 +584,30 @@
       and<br />
       <br />
       <code>'<var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var>'</code> results in <code><var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var></code>.</p></div>
+
+    <div class="note"><h3>Optimization of Boolean Expressions</h3>
+      <p>If the expressions become more complex and slow down processing
+      significantly, you can try to optimize them according to the
+      evaluation rules:</p>
+      <ul>
+      <li>Expressions are evaluated from left to right</li>
+      <li>Binary boolean operators (<code>&amp;&amp;</code> and <code>||</code>)
+          are short circuited whereever possible. In conclusion with the rule
+          above that means, <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> evaluates at first
+          the left expression. If the left result if sufficient to determine
+          the end result, processing stops here. Otherwise it evaluates the
+          right side and computes the end result from both left and right
+          results.</li>
+      <li>Short circuit evaluation is turned off as long as there are regular
+          expressions to deal with. These must be evaluated to fill in the
+          backreference variables (<code>$1</code> .. <code>$9</code>).</li>
+      </ul>
+      <p>If you want to look how a particular expression is handled, you can
+      recompile <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> using the
+      <code>-DDEBUG_INCLUDE</code> compiler option. This inserts for every
+      parsed expression tokenizer information, the parse tree and how it is
+      evaluated into the output sent to the client.</p>
+    </div>
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="directive-section"><h2><a name="SSIEndTag" id="SSIEndTag">SSIEndTag</a> <a name="ssiendtag" id="ssiendtag">Directive</a></h2>

diff --git a/docs/manual/mod/mod_include.xml b/docs/manual/mod/mod_include.xml
index becbc262dcaa8feee1866338ed06d0e3f05a817f..66141d64b7d159bac951cfe1499a899df0e3b638 100644 (file)
--- a/docs/manual/mod/mod_include.xml
+++ b/docs/manual/mod/mod_include.xml
@@ -474,6 +474,7 @@
       <dd>true if <var>string</var> is not empty</dd>
 
       <dt><code><var>string1</var> = <var>string2</var><br />
+      <var>string1</var> == <var>string2</var><br />
       <var>string1</var> != <var>string2</var></code></dt>
       
       <dd><p>Compare <var>string1</var> with <var>string2</var>. If
@@ -481,11 +482,12 @@
       then it is treated as a regular expression. Regular expressions are
       implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
       have the same syntax as those in <a href="http://www.perl.com">perl
-      5</a>.</p>
+      5</a>. Note that <code>==</code> is just an alias for <code>=</code>
+      and behaves exactly the same way.</p>
 
-      <p>If you are matching positive (<code>=</code>), you can capture
-      grouped parts of the regular expression. The captured parts are
-      stored in the special variables <code>$1</code> ..
+      <p>If you are matching positive (<code>=</code> or <code>==</code>), you
+      can capture grouped parts of the regular expression. The captured parts
+      are stored in the special variables <code>$1</code> ..
       <code>$9</code>.</p>
 
       <example><title>Example</title>
@@ -533,6 +535,10 @@
       &lt;!--#if expr="($a = test1) &amp;&amp; ($b = test2)" --&gt;
     </example>
 
+    <p>The boolean operators <code>&amp;&amp;</code> and <code>||</code>
+    share the same priority. So if you want to bind such an operator more
+    tightly, you should use parentheses.</p>
+
     <p>Anything that's not recognized as a variable or an operator
     is treated as a string. Strings can also be quoted:
     <code>'string'</code>. Unquoted strings can't contain whitespace
@@ -551,6 +557,30 @@
       >string2</var>'</code> results in <code><var
       >string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var></code>.</p>
     </example>
+
+    <note><title>Optimization of Boolean Expressions</title>
+      <p>If the expressions become more complex and slow down processing
+      significantly, you can try to optimize them according to the
+      evaluation rules:</p>
+      <ul>
+      <li>Expressions are evaluated from left to right</li>
+      <li>Binary boolean operators (<code>&amp;&amp;</code> and <code>||</code>)
+          are short circuited whereever possible. In conclusion with the rule
+          above that means, <module>mod_include</module> evaluates at first
+          the left expression. If the left result if sufficient to determine
+          the end result, processing stops here. Otherwise it evaluates the
+          right side and computes the end result from both left and right
+          results.</li>
+      <li>Short circuit evaluation is turned off as long as there are regular
+          expressions to deal with. These must be evaluated to fill in the
+          backreference variables (<code>$1</code> .. <code>$9</code>).</li>
+      </ul>
+      <p>If you want to look how a particular expression is handled, you can
+      recompile <module>mod_include</module> using the
+      <code>-DDEBUG_INCLUDE</code> compiler option. This inserts for every
+      parsed expression tokenizer information, the parse tree and how it is
+      evaluated into the output sent to the client.</p>
+    </note>
 </section>
 
 <directivesynopsis>