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>
