This is an automated email from the ASF dual-hosted git repository.
cbrisson pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/velocity-site.git
The following commit(s) were added to refs/heads/main by this push:
new fbbf750 Document upcoming runtime.immutable_ranges configuration flag
fbbf750 is described below
commit fbbf750ca7dde67decb19f8066798a1c0c4b8389
Author: Claude Brisson <[email protected]>
AuthorDate: Fri Aug 23 18:21:14 2024 +0200
Document upcoming runtime.immutable_ranges configuration flag
---
src/content/engine/devel/configuration.mdtext | 7 +++++++
src/content/engine/devel/developer-guide.mdtext | 4 +++-
src/content/engine/devel/user-guide.mdtext | 2 --
3 files changed, 10 insertions(+), 3 deletions(-)
diff --git a/src/content/engine/devel/configuration.mdtext
b/src/content/engine/devel/configuration.mdtext
index ad49f7a..ace74f0 100644
--- a/src/content/engine/devel/configuration.mdtext
+++ b/src/content/engine/devel/configuration.mdtext
@@ -67,6 +67,7 @@ The following tree gathers all non deprecated configuration
properties with thei
+-- log_when_found = true
runtime. +-- custom_directives = *classname*, *classname* ...
+ +-- immutable_ranges = true
+-- interpolate_string_literals = true
+-- log. +-- instance = *Java Object instance*
| +-- log_invalid_method_calls = true
@@ -300,6 +301,12 @@ The following resource management configuration keys only
apply to the default R
> Controls interpolation mechanism of VTL String Literals. Note that a VTL
> StringLiteral is specifically a string using double quotes that is used in a
> #set() statement, a method call of a reference, a parameter to a VM, or as
> an argument to a VTL directive in general. See the VTL reference for
> further information.
+## Ranges
+
+**`runtime.immutable_ranges = true`**
+
+> Controls whether the `java.util.List` object return by the VTL range
operator [ *a* .. *b* ] is an immutable list (the default since Velocity 2.1)
or a mutable list backed by a `java.util.ArrayList` object.
+
## Math
**`runtime.strict_math = false`**
diff --git a/src/content/engine/devel/developer-guide.mdtext
b/src/content/engine/devel/developer-guide.mdtext
index 90127c4..5200cf5 100644
--- a/src/content/engine/devel/developer-guide.mdtext
+++ b/src/content/engine/devel/developer-guide.mdtext
@@ -305,11 +305,13 @@ When a template adds objects to the context, the Java
code can access those obje
Dealing with these cases if very straighforward, as there are just a few
things to know:
-+ The VTL RangeOperator [ 1..10 ] and ObjectArray ["a","b"] are
`java.util.ArrayList` objects when placed in the context or passed to methods.
Therefore, your methods that are designed to accept arrays created in the
template should be written with this in mind.
++ The VTL array literal `[ "a", "b" ]` and the VTL range operator `[ 1..10 ]`
are `java.util.List` objects<sup>(`*`)</sup> when placed in the context or
passed to methods. Therefore, your methods that are designed to accept arrays
created in the template should be written with this in mind.
+ VTL Map references are unsurprisingly stored as `java.util.Map`.
+ Decimal numbers will be Doubles or BigDecimals in the context, integer
numbers will be Integer, Long, or BigIntegers, and strings will be, of course,
Strings.
+ Since version 2.0, Velocity will convert method arguments between all main
Java standard types (booleans, numbers and strings). If you want to revert to
the Velocity 1.x behavior, where provided conversions were restricted to
implicit Java conversions, you can set the property
`runtime.conversion.handler` to `none`.
+**(`*`)** While an array literal always produces a **mutable** `ArrayList`,
the range operator produces an **immutable** `List` since Velocity 2.1. You can
revert this default to get a mutable list with the configuration:
`runtime.immutable_ranges = false`
+
### Other Context Issues
One of the features provided by the VelocityContext (or any Context derived
from AbstractContext) is node specific introspection caching. Generally, you
as a the developer don't need to worry about this when using the
VelocityContext as your context. However, there is currently one known usage
pattern where you must be aware of this feature.
diff --git a/src/content/engine/devel/user-guide.mdtext
b/src/content/engine/devel/user-guide.mdtext
index c281ceb..cbde76e 100644
--- a/src/content/engine/devel/user-guide.mdtext
+++ b/src/content/engine/devel/user-guide.mdtext
@@ -1104,8 +1104,6 @@ Produces the following output:
Note that the range operator only produces the array when used in conjunction
with *#set* and *#foreach* directives, as demonstrated in the fourth example.
-Web page designers concerned with making tables a standard size, but where
some will not have enough data to fill the table, will find the range operator
particularly useful.
-
### Advanced Issues: Escaping and !
When a reference is silenced with the *!* character and the *!* character
preceded by an *\* escape character, the reference is handled in a special way.
Note the differences between regular escaping, and the special case where *\*
precedes *!* follows it:
