velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1873097 - in /velocity/site/production/engine: 2.0/ 2.1/ 2.2/ devel/
Date Fri, 24 Jan 2020 09:56:36 GMT
Author: cbrisson
Date: Fri Jan 24 09:56:36 2020
New Revision: 1873097

URL: http://svn.apache.org/viewvc?rev=1873097&view=rev
Log:
[site/engine][prod] Push all previous changes to production

Modified:
    velocity/site/production/engine/2.0/upgrading.html
    velocity/site/production/engine/2.0/user-guide.html
    velocity/site/production/engine/2.1/changes.html
    velocity/site/production/engine/2.1/upgrading.html
    velocity/site/production/engine/2.1/user-guide.html
    velocity/site/production/engine/2.2/changes.html
    velocity/site/production/engine/2.2/dependencies.html
    velocity/site/production/engine/2.2/upgrading.html
    velocity/site/production/engine/2.2/user-guide.html
    velocity/site/production/engine/devel/changes.html
    velocity/site/production/engine/devel/dependencies.html
    velocity/site/production/engine/devel/upgrading.html
    velocity/site/production/engine/devel/user-guide.html

Modified: velocity/site/production/engine/2.0/upgrading.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/upgrading.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.0/upgrading.html (original)
+++ velocity/site/production/engine/2.0/upgrading.html Fri Jan 24 09:56:36 2020
@@ -268,9 +268,11 @@ directive.if.emptycheck = false
 <li>method arguments can be arithmetic expressions</li>
 <li>method arguments are now converted as needed between all main basic Java standard
types (booleans, numbers and strings). If you want to revert to the 1.x behavior, set the
property <code>runtime.conversion.handler = none</code>.</li>
 <li>space gobbling (to control the indentation of generated code) is now configurable
via the <code>space.gobbing</code> configuration key, which can take the following
values: <code>none</code>, <code>bc</code> (aka. backward compatible),
<code>lines</code> and <code>structured</code>. See the related documentation
section for details. To maximize backward compatibility with 1.x, set it to <code>bc</code>.</li>
-<li>The #foreach predefined references <code>$velocityCount</code> and
<code>$velocityHasNext</code> have been removed. Use <code>$foreach.count</code>
(1-based), <code>$foreach.index</code> (0-based) and <code>foreach.hasNext()</code>.</li>
+<li>the #foreach predefined references <code>$velocityCount</code> and
<code>$velocityHasNext</code> have been removed. Use <code>$foreach.count</code>
(1-based), <code>$foreach.index</code> (0-based) and <code>foreach.hasNext()</code>.</li>
+<li>Velocimacro arguments are now evaluated only once (instead of each time they were
referenced inside the macro body as was the case for v1.7) and passed by value (or more precisely
as reference after evaluation).</li>
+<li>Velocimacros do not anymore have a <em>proxy context</em> of their
own - if they do insert new values in the context, and then call an external code changing
those values, they will now see the new values.</li>
 </ul>
-<h3 id="dependency-changes">Dependency changes:<a class="headerlink" href="#dependency-changes"
title="Permanent link">&para;</a></h3>
+<h3 id="dependency-changes">Dependency Changes<a class="headerlink" href="#dependency-changes"
title="Permanent link">&para;</a></h3>
 <ul>
 <li>Velocity now requires a JDK version of 1.7 or higher.</li>
 <li>commons-collections and commons-logging aren't needed any more at runtime.</li>

Modified: velocity/site/production/engine/2.0/user-guide.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/user-guide.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.0/user-guide.html (original)
+++ velocity/site/production/engine/2.0/user-guide.html Fri Jan 24 09:56:36 2020
@@ -1016,7 +1016,7 @@ $foo
 <li>boolean value true</li>
 <li>boolean value false</li>
 </ul>
-<p>When passing references as arguments to Velocimacros, please note that references
are passed 'by name'. This means that their value is 'generated' at each use inside the Velocimacro.
 This feature allows you to pass references with method calls and have the method called at
each use.  For example, when calling the following Velocimacro as shown</p>
+<p>Since 2.0, Velocimacros arguments are passed by value (or, more precisely, the result
of their evaluation is passed by reference). This means that they are evaluated only once,
even when used several times inside the macro. It means that in the following example:</p>
 <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span
class="p">(</span> <span class="nf">callme</span> <span class="p">$</span><span
class="nv">a</span> <span class="p">)</span><span class="x"></span>
 <span class="x">    </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"></span>
 <span class="cp">#</span><span class="nf">end</span><span class="x"></span>
@@ -1025,14 +1025,7 @@ $foo
 </pre></div>
 
 
-<p>results in the method bar() of the reference $foo being called 3 times.</p>
-<p>At first glance, this feature appears surprising, but when you take into consideration
the original motivation behind Velocimacros -- to eliminate cut'n'paste duplication of commonly
used VTL -- it makes sense.  It allows you to do things like pass stateful objects, such as
an object that generates colors in a repeating sequence for coloring table rows, into the
Velocimacro.</p>
-<p>If you need to circumvent this feature, you can always just get the value from the
method as a new reference and pass that :</p>
-<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span
class="p">(</span> <span class="p">$</span><span class="nv">myval</span>
<span class="o">=</span> <span class="p">$</span><span class="nv">foo</span><span
class="p">.</span><span class="nv">bar</span><span class="p">()</span>
<span class="p">)</span><span class="x"></span>
-<span class="cp">#</span><span class="nf">callme</span><span class="p">(</span>
<span class="p">$</span><span class="nv">myval</span> <span class="p">)</span><span
class="x"></span>
-</pre></div>
-
-
+<p>the method bar() of the reference $foo is only called once.</p>
 <h4 id="velocimacro-properties">Velocimacro Properties<a class="headerlink" href="#velocimacro-properties"
title="Permanent link">&para;</a></h4>
 <p>Several lines in the <code>velocity.properties</code> file allow for
flexible implementation of Velocimacros.  Note that these are also documented in the <a
href="developer-guide.html">Developer Guide</a>.</p>
 <p><code>velocimacro.library</code> - A comma-separated list of all Velocimacro
template libraries. By default, Velocity looks for a single library: <em>VM_global_library.vm</em>.
The configured template path is used to find the Velocimacro libraries.</p>

Modified: velocity/site/production/engine/2.1/changes.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.1/changes.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.1/changes.html (original)
+++ velocity/site/production/engine/2.1/changes.html Fri Jan 24 09:56:36 2020
@@ -325,6 +325,34 @@ h2:hover > .headerlink, h3:hover > .head
     <tbody>
       <tr>
         <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed regression: Macro arguments names cannot collide with external references
names . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-926">VELOCITY-926</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed macro calls without parenthesis eating the following newline in
BC mode . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-925">VELOCITY-925</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed bad cache handling for java.lang.Class methods . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-924">VELOCITY-924</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed parser regression when || follow a Velocity expression . Fixes <a
href="https://issues.apache.org/jira/browse/VELOCITY-923">VELOCITY-923</a>. </td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
           <img src="images/add.png"/>
         </td>
         <td> Added BigInteger and BigDecimal implicit conversions . </td>

Modified: velocity/site/production/engine/2.1/upgrading.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.1/upgrading.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.1/upgrading.html (original)
+++ velocity/site/production/engine/2.1/upgrading.html Fri Jan 24 09:56:36 2020
@@ -335,6 +335,8 @@ Please note that the maven repository pa
 <li>method arguments are now converted as needed between all main basic Java standard
types (booleans, numbers and strings). If you want to revert to the 1.x behavior, set the
property <code>runtime.conversion.handler.class = none</code>.</li>
 <li>space gobbling (to control the indentation of generated code) is now configurable
via the <code>space.gobbing</code> configuration key, which can take the following
values: <code>none</code>, <code>bc</code> (aka. backward compatible),
<code>lines</code> and <code>structured</code>. See the related documentation
section for details. To maximize backward compatibility with 1.x, set it to <code>bc</code>.</li>
 <li>the #foreach predefined references <code>$velocityCount</code> and
<code>$velocityHasNext</code> have been removed. Use <code>$foreach.count</code>
(1-based), <code>$foreach.index</code> (0-based) and <code>foreach.hasNext()</code>.</li>
+<li>Velocimacro arguments are now evaluated only once (instead of each time they were
referenced inside the macro body as was the case for v1.7) and passed by value (or more precisely
as reference after evaluation).</li>
+<li>Velocimacros do not anymore have a <em>proxy context</em> of their
own - if they do insert new values in the context, and then call an external code changing
those values, they will now see the new values.</li>
 </ul>
 <h3 id="dependency-changes_1">Dependency Changes<a class="headerlink" href="#dependency-changes_1"
title="Permanent link">&para;</a></h3>
 <ul>

Modified: velocity/site/production/engine/2.1/user-guide.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.1/user-guide.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.1/user-guide.html (original)
+++ velocity/site/production/engine/2.1/user-guide.html Fri Jan 24 09:56:36 2020
@@ -1026,7 +1026,7 @@ $foo
 <li>boolean value true</li>
 <li>boolean value false</li>
 </ul>
-<p>When passing references as arguments to Velocimacros, please note that references
are passed 'by name'. This means that their value is 'generated' at each use inside the Velocimacro.
 This feature allows you to pass references with method calls and have the method called at
each use.  For example, when calling the following Velocimacro as shown</p>
+<p>Since 2.0, Velocimacros arguments are passed by value (or, more precisely, the result
of their evaluation is passed by reference). This means that they are evaluated only once,
even when used several times inside the macro. It means that in the following example:</p>
 <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span
class="p">(</span> <span class="nf">callme</span> <span class="p">$</span><span
class="nv">a</span> <span class="p">)</span><span class="x"></span>
 <span class="x">    </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"></span>
 <span class="cp">#</span><span class="nf">end</span><span class="x"></span>
@@ -1035,14 +1035,7 @@ $foo
 </pre></div>
 
 
-<p>results in the method bar() of the reference $foo being called 3 times.</p>
-<p>At first glance, this feature appears surprising, but when you take into consideration
the original motivation behind Velocimacros -- to eliminate cut'n'paste duplication of commonly
used VTL -- it makes sense.  It allows you to do things like pass stateful objects, such as
an object that generates colors in a repeating sequence for coloring table rows, into the
Velocimacro.</p>
-<p>If you need to circumvent this feature, you can always just get the value from the
method as a new reference and pass that :</p>
-<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span
class="p">(</span> <span class="p">$</span><span class="nv">myval</span>
<span class="o">=</span> <span class="p">$</span><span class="nv">foo</span><span
class="p">.</span><span class="nv">bar</span><span class="p">()</span>
<span class="p">)</span><span class="x"></span>
-<span class="cp">#</span><span class="nf">callme</span><span class="p">(</span>
<span class="p">$</span><span class="nv">myval</span> <span class="p">)</span><span
class="x"></span>
-</pre></div>
-
-
+<p>the method bar() of the reference $foo is only called once.</p>
 <h4 id="velocimacro-properties">Velocimacro Properties<a class="headerlink" href="#velocimacro-properties"
title="Permanent link">&para;</a></h4>
 <p>Several lines in the <code>velocity.properties</code> file allow for
flexible implementation of Velocimacros.  Note that these are also documented in the <a
href="developer-guide.html">Developer Guide</a>.</p>
 <p><code>velocimacro.library.path</code> - A comma-separated list of all
Velocimacro template libraries. By default, Velocity looks for a single library: <em>velocimacros.vtl</em>
(since 2.1 ; and if not found it will also look at the old default <em>VM_global_library.vm</em>).
The configured template path is used to find the Velocimacro libraries.</p>

Modified: velocity/site/production/engine/2.2/changes.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.2/changes.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.2/changes.html (original)
+++ velocity/site/production/engine/2.2/changes.html Fri Jan 24 09:56:36 2020
@@ -325,6 +325,34 @@ h2:hover > .headerlink, h3:hover > .head
     <tbody>
       <tr>
         <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed regression: Macro arguments names cannot collide with external references
names . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-926">VELOCITY-926</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed macro calls without parenthesis eating the following newline in
BC mode . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-925">VELOCITY-925</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed bad cache handling for java.lang.Class methods . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-924">VELOCITY-924</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed parser regression when || follow a Velocity expression . Fixes <a
href="https://issues.apache.org/jira/browse/VELOCITY-923">VELOCITY-923</a>. </td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
           <img src="images/add.png"/>
         </td>
         <td> Added BigInteger and BigDecimal implicit conversions . </td>

Modified: velocity/site/production/engine/2.2/dependencies.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.2/dependencies.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.2/dependencies.html (original)
+++ velocity/site/production/engine/2.2/dependencies.html Fri Jan 24 09:56:36 2020
@@ -257,7 +257,7 @@ h2:hover > .headerlink, h3:hover > .head
 </tr>
 <tr>
 <td>junit</td>
-<td>4.12</td>
+<td>4.13</td>
 <td>No</td>
 <td>Yes</td>
 <td>No</td>

Modified: velocity/site/production/engine/2.2/upgrading.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.2/upgrading.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.2/upgrading.html (original)
+++ velocity/site/production/engine/2.2/upgrading.html Fri Jan 24 09:56:36 2020
@@ -386,6 +386,8 @@ Please note that the maven repository pa
 <li>method arguments are now converted as needed between all main basic Java standard
types (booleans, numbers and strings). If you want to revert to the 1.x behavior, set the
property <code>runtime.conversion.handler.class = none</code>.</li>
 <li>space gobbling (to control the indentation of generated code) is now configurable
via the <code>space.gobbing</code> configuration key, which can take the following
values: <code>none</code>, <code>bc</code> (aka. backward compatible),
<code>lines</code> and <code>structured</code>. See the related documentation
section for details. To maximize backward compatibility with 1.x, set it to <code>bc</code>.</li>
 <li>the #foreach predefined references <code>$velocityCount</code> and
<code>$velocityHasNext</code> have been removed. Use <code>$foreach.count</code>
(1-based), <code>$foreach.index</code> (0-based) and <code>foreach.hasNext()</code>.</li>
+<li>Velocimacro arguments are now evaluated only once (instead of each time they were
referenced inside the macro body as was the case for v1.7) and passed by value (or more precisely
as reference after evaluation).</li>
+<li>Velocimacros do not anymore have a <em>proxy context</em> of their
own - if they do insert new values in the context, and then call an external code changing
those values, they will now see the new values.</li>
 </ul>
 <h3 id="dependency-changes_2">Dependency Changes<a class="headerlink" href="#dependency-changes_2"
title="Permanent link">&para;</a></h3>
 <ul>

Modified: velocity/site/production/engine/2.2/user-guide.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.2/user-guide.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/2.2/user-guide.html (original)
+++ velocity/site/production/engine/2.2/user-guide.html Fri Jan 24 09:56:36 2020
@@ -1026,7 +1026,7 @@ $foo
 <li>boolean value true</li>
 <li>boolean value false</li>
 </ul>
-<p>When passing references as arguments to Velocimacros, please note that references
are passed 'by name'. This means that their value is 'generated' at each use inside the Velocimacro.
 This feature allows you to pass references with method calls and have the method called at
each use.  For example, when calling the following Velocimacro as shown</p>
+<p>Since 2.0, Velocimacros arguments are passed by value (or, more precisely, the result
of their evaluation is passed by reference). This means that they are evaluated only once,
even when used several times inside the macro. It means that in the following example:</p>
 <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span
class="p">(</span> <span class="nf">callme</span> <span class="p">$</span><span
class="nv">a</span> <span class="p">)</span><span class="x"></span>
 <span class="x">    </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"></span>
 <span class="cp">#</span><span class="nf">end</span><span class="x"></span>
@@ -1035,14 +1035,7 @@ $foo
 </pre></div>
 
 
-<p>results in the method bar() of the reference $foo being called 3 times.</p>
-<p>At first glance, this feature appears surprising, but when you take into consideration
the original motivation behind Velocimacros -- to eliminate cut'n'paste duplication of commonly
used VTL -- it makes sense.  It allows you to do things like pass stateful objects, such as
an object that generates colors in a repeating sequence for coloring table rows, into the
Velocimacro.</p>
-<p>If you need to circumvent this feature, you can always just get the value from the
method as a new reference and pass that :</p>
-<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span
class="p">(</span> <span class="p">$</span><span class="nv">myval</span>
<span class="o">=</span> <span class="p">$</span><span class="nv">foo</span><span
class="p">.</span><span class="nv">bar</span><span class="p">()</span>
<span class="p">)</span><span class="x"></span>
-<span class="cp">#</span><span class="nf">callme</span><span class="p">(</span>
<span class="p">$</span><span class="nv">myval</span> <span class="p">)</span><span
class="x"></span>
-</pre></div>
-
-
+<p>the method bar() of the reference $foo is only called once.</p>
 <h4 id="velocimacro-properties">Velocimacro Properties<a class="headerlink" href="#velocimacro-properties"
title="Permanent link">&para;</a></h4>
 <p>Several lines in the <code>velocity.properties</code> file allow for
flexible implementation of Velocimacros.  Note that these are also documented in the <a
href="developer-guide.html">Developer Guide</a>.</p>
 <p><code>velocimacro.library.path</code> - A comma-separated list of all
Velocimacro template libraries. By default, Velocity looks for a single library: <em>velocimacros.vtl</em>
(since 2.1 ; and if not found it will also look at the old default <em>VM_global_library.vm</em>).
The configured template path is used to find the Velocimacro libraries.</p>

Modified: velocity/site/production/engine/devel/changes.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/changes.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/devel/changes.html (original)
+++ velocity/site/production/engine/devel/changes.html Fri Jan 24 09:56:36 2020
@@ -325,6 +325,34 @@ h2:hover > .headerlink, h3:hover > .head
     <tbody>
       <tr>
         <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed regression: Macro arguments names cannot collide with external references
names . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-926">VELOCITY-926</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed macro calls without parenthesis eating the following newline in
BC mode . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-925">VELOCITY-925</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed bad cache handling for java.lang.Class methods . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-924">VELOCITY-924</a>.
</td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
+          <img src="images/fix.png"/>
+        </td>
+        <td> Fixed parser regression when || follow a Velocity expression . Fixes <a
href="https://issues.apache.org/jira/browse/VELOCITY-923">VELOCITY-923</a>. </td>
+        <td>cbrisson</td>
+      </tr>
+      <tr>
+        <td>
           <img src="images/add.png"/>
         </td>
         <td> Added BigInteger and BigDecimal implicit conversions . </td>

Modified: velocity/site/production/engine/devel/dependencies.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/dependencies.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/devel/dependencies.html (original)
+++ velocity/site/production/engine/devel/dependencies.html Fri Jan 24 09:56:36 2020
@@ -257,7 +257,7 @@ h2:hover > .headerlink, h3:hover > .head
 </tr>
 <tr>
 <td>junit</td>
-<td>4.12</td>
+<td>4.13</td>
 <td>No</td>
 <td>Yes</td>
 <td>No</td>

Modified: velocity/site/production/engine/devel/upgrading.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/upgrading.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/devel/upgrading.html (original)
+++ velocity/site/production/engine/devel/upgrading.html Fri Jan 24 09:56:36 2020
@@ -386,6 +386,8 @@ Please note that the maven repository pa
 <li>method arguments are now converted as needed between all main basic Java standard
types (booleans, numbers and strings). If you want to revert to the 1.x behavior, set the
property <code>runtime.conversion.handler.class = none</code>.</li>
 <li>space gobbling (to control the indentation of generated code) is now configurable
via the <code>space.gobbing</code> configuration key, which can take the following
values: <code>none</code>, <code>bc</code> (aka. backward compatible),
<code>lines</code> and <code>structured</code>. See the related documentation
section for details. To maximize backward compatibility with 1.x, set it to <code>bc</code>.</li>
 <li>the #foreach predefined references <code>$velocityCount</code> and
<code>$velocityHasNext</code> have been removed. Use <code>$foreach.count</code>
(1-based), <code>$foreach.index</code> (0-based) and <code>foreach.hasNext()</code>.</li>
+<li>Velocimacro arguments are now evaluated only once (instead of each time they were
referenced inside the macro body as was the case for v1.7) and passed by value (or more precisely
as reference after evaluation).</li>
+<li>Velocimacros do not anymore have a <em>proxy context</em> of their
own - if they do insert new values in the context, and then call an external code changing
those values, they will now see the new values.</li>
 </ul>
 <h3 id="dependency-changes_2">Dependency Changes<a class="headerlink" href="#dependency-changes_2"
title="Permanent link">&para;</a></h3>
 <ul>

Modified: velocity/site/production/engine/devel/user-guide.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/user-guide.html?rev=1873097&r1=1873096&r2=1873097&view=diff
==============================================================================
--- velocity/site/production/engine/devel/user-guide.html (original)
+++ velocity/site/production/engine/devel/user-guide.html Fri Jan 24 09:56:36 2020
@@ -1026,7 +1026,7 @@ $foo
 <li>boolean value true</li>
 <li>boolean value false</li>
 </ul>
-<p>When passing references as arguments to Velocimacros, please note that references
are passed 'by name'. This means that their value is 'generated' at each use inside the Velocimacro.
 This feature allows you to pass references with method calls and have the method called at
each use.  For example, when calling the following Velocimacro as shown</p>
+<p>Since 2.0, Velocimacros arguments are passed by value (or, more precisely, the result
of their evaluation is passed by reference). This means that they are evaluated only once,
even when used several times inside the macro. It means that in the following example:</p>
 <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span
class="p">(</span> <span class="nf">callme</span> <span class="p">$</span><span
class="nv">a</span> <span class="p">)</span><span class="x"></span>
 <span class="x">    </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"> </span><span class="p">$</span><span class="nv">a</span><span
class="x"></span>
 <span class="cp">#</span><span class="nf">end</span><span class="x"></span>
@@ -1035,14 +1035,7 @@ $foo
 </pre></div>
 
 
-<p>results in the method bar() of the reference $foo being called 3 times.</p>
-<p>At first glance, this feature appears surprising, but when you take into consideration
the original motivation behind Velocimacros -- to eliminate cut'n'paste duplication of commonly
used VTL -- it makes sense.  It allows you to do things like pass stateful objects, such as
an object that generates colors in a repeating sequence for coloring table rows, into the
Velocimacro.</p>
-<p>If you need to circumvent this feature, you can always just get the value from the
method as a new reference and pass that :</p>
-<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span
class="p">(</span> <span class="p">$</span><span class="nv">myval</span>
<span class="o">=</span> <span class="p">$</span><span class="nv">foo</span><span
class="p">.</span><span class="nv">bar</span><span class="p">()</span>
<span class="p">)</span><span class="x"></span>
-<span class="cp">#</span><span class="nf">callme</span><span class="p">(</span>
<span class="p">$</span><span class="nv">myval</span> <span class="p">)</span><span
class="x"></span>
-</pre></div>
-
-
+<p>the method bar() of the reference $foo is only called once.</p>
 <h4 id="velocimacro-properties">Velocimacro Properties<a class="headerlink" href="#velocimacro-properties"
title="Permanent link">&para;</a></h4>
 <p>Several lines in the <code>velocity.properties</code> file allow for
flexible implementation of Velocimacros.  Note that these are also documented in the <a
href="developer-guide.html">Developer Guide</a>.</p>
 <p><code>velocimacro.library.path</code> - A comma-separated list of all
Velocimacro template libraries. By default, Velocity looks for a single library: <em>velocimacros.vtl</em>
(since 2.1 ; and if not found it will also look at the old default <em>VM_global_library.vm</em>).
The configured template path is used to find the Velocimacro libraries.</p>



Mime
View raw message