You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2020/01/24 09:56:36 UTC
svn commit: r1873097 - in /velocity/site/production/engine: 2.0/ 2.1/ 2.2/
devel/
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">¶</a></h3>
+<h3 id="dependency-changes">Dependency Changes<a class="headerlink" href="#dependency-changes" title="Permanent link">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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>