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 2026/06/13 20:39:35 UTC
(velocity-engine) 01/01: VELOCITY-995 VTL syntax deprecation warnings (still off by default)
This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch velocity-995
in repository https://gitbox.apache.org/repos/asf/velocity-engine.git
commit 0b6fa31b2b686e220d9fbebace6b18f4033c3bbe
Author: Claude Brisson <cl...@renegat.net>
AuthorDate: Sat Jun 13 22:38:59 2026 +0200
VELOCITY-995 VTL syntax deprecation warnings (still off by default)
---
.../apache/velocity/runtime/RuntimeConstants.java | 3 ++
.../apache/velocity/runtime/RuntimeInstance.java | 13 +++++
.../velocity/runtime/parser/node/ASTReference.java | 58 ++++++++++++++++++++++
velocity-engine-core/src/main/parser/Parser.jjt | 4 +-
.../velocity/runtime/defaults/velocity.properties | 10 ++++
5 files changed, 86 insertions(+), 2 deletions(-)
diff --git a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeConstants.java b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeConstants.java
index f5894544..78eb512b 100644
--- a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeConstants.java
+++ b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeConstants.java
@@ -473,6 +473,9 @@ public interface RuntimeConstants extends DeprecatedRuntimeConstants
/** Switch for the immutability of integer ranges. */
String IMMUTABLE_RANGES = "runtime.immutable_ranges";
+ /** Whether to warn about deprecated VTL syntax constructs (off by default, will be turned on in the next 2.x release). */
+ String RUNTIME_DEPRECATION_WARN = "runtime.deprecation.warn";
+
/** Switch for ignoring nulls in math equations vs throwing exceptions. */
String STRICT_MATH = "runtime.strict_math";
diff --git a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java
index e77f2df8..074551c6 100644
--- a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java
+++ b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java
@@ -279,6 +279,7 @@ public synchronized void init()
initializeProperties();
initializeSelfProperties();
initializeLog();
+ warnDeprecatedSettings();
initializeResourceManager();
initializeDirectives();
initializeEventHandlers();
@@ -401,6 +402,18 @@ private void initializeSelfProperties()
hyphenAllowedInIdentifiers = getBoolean(PARSER_HYPHEN_ALLOWED, false);
}
+ /**
+ * Warns about deprecated configuration settings, when runtime.deprecation.warn is on.
+ * Kept separate from {@link #initializeSelfProperties()} so it runs after the log is set up.
+ */
+ private void warnDeprecatedSettings()
+ {
+ if (getBoolean(RUNTIME_DEPRECATION_WARN, false) && hyphenAllowedInIdentifiers)
+ {
+ log.warn("the '{}' option is deprecated: hyphenated identifiers (e.g. $foo-bar) cannot be expressed in the next major version", PARSER_HYPHEN_ALLOWED);
+ }
+ }
+
private char getConfiguredCharacter(String configKey, char defaultChar)
{
String configuredChar = getString(configKey);
diff --git a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/parser/node/ASTReference.java b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/parser/node/ASTReference.java
index cca12e7e..37fc13d1 100644
--- a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/parser/node/ASTReference.java
+++ b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/parser/node/ASTReference.java
@@ -101,6 +101,18 @@ public class ASTReference extends SimpleNode
private int numChildren = 0;
+ /**
+ * Whether this reference uses the formal curly-brace notation: ${...} or $!{...}.
+ * Set by the parser; distinguishes ${foo.bar} from the deprecated informal $foo.bar.
+ */
+ private boolean formal = false;
+
+ /**
+ * Whether this reference carries the deprecated extra '$' after '{', as in ${$foo}
+ * (re-added in 2.5 for 1.7 backward compatibility). Set by the parser.
+ */
+ private boolean extraDollar = false;
+
/**
* Whether to trigger an event for invalid quiet references
* @since 2.2
@@ -148,6 +160,24 @@ public Object jjtAccept(StandardParserVisitor visitor, Object data)
return visitor.visit(this, data);
}
+ /**
+ * Marks this reference as using the formal curly-brace notation. Called by the parser.
+ * @param formal formal flag
+ */
+ public void setFormal(boolean formal)
+ {
+ this.formal = formal;
+ }
+
+ /**
+ * Marks this reference as carrying the deprecated extra '$' after '{'. Called by the parser.
+ * @param extraDollar extra-dollar flag
+ */
+ public void setExtraDollar(boolean extraDollar)
+ {
+ this.extraDollar = extraDollar;
+ }
+
/**
* @see org.apache.velocity.runtime.parser.node.SimpleNode#init(org.apache.velocity.context.InternalContextAdapter, java.lang.Object)
*/
@@ -203,6 +233,34 @@ else if (lastNode instanceof ASTExpression)
}
}
+ /*
+ * VTL syntax deprecation warnings (VELOCITY-995), gated and off by default.
+ * The '|' default-value operator is always deprecated. Informal notation is
+ * ambiguous only when rendered to output, so it is flagged solely for
+ * references that are a direct child of a rendered block.
+ */
+ if (rsvc.getBoolean(RuntimeConstants.RUNTIME_DEPRECATION_WARN, false))
+ {
+ if (astAlternateValue != null)
+ {
+ log.warn("the '|' default-value notation is deprecated; use an #if(...)...#{else}...#end block instead - {} [line {}, column {}]",
+ getTemplateName(), getLine(), getColumn());
+ }
+ if (extraDollar)
+ {
+ log.warn("the extra '$' after '{' is deprecated; write ${foo} rather than ${$foo} - {} [line {}, column {}]",
+ getTemplateName(), getLine(), getColumn());
+ }
+ if (!formal && numChildren > 0)
+ {
+ Node parent = jjtGetParent();
+ if (parent instanceof ASTBlock || parent instanceof ASTprocess)
+ {
+ log.warn("the informal notation '{}' is deprecated in output; use the formal notation ${...} instead - {} [line {}, column {}]",
+ literal(), getTemplateName(), getLine(), getColumn());
+ }
+ }
+ }
/*
* make an uberinfo - saves new's later on
diff --git a/velocity-engine-core/src/main/parser/Parser.jjt b/velocity-engine-core/src/main/parser/Parser.jjt
index 319a83e0..ae472d91 100644
--- a/velocity-engine-core/src/main/parser/Parser.jjt
+++ b/velocity-engine-core/src/main/parser/Parser.jjt
@@ -2159,7 +2159,7 @@ void Index() : {}
<INDEX_LBRACKET> IndexParameter() <INDEX_RBRACKET>
}
-void Reference() : {}
+void Reference() : { Token t; }
{
/*
* A reference is either $<FOO> or ${<FOO>} or ${<FOO>'|'<ALTERNATE_VALUE>)
@@ -2171,7 +2171,7 @@ void Reference() : {}
)
|
(
- <LCURLY>
+ t=<LCURLY> { jjtThis.setFormal(true); if (!t.image.endsWith("{")) jjtThis.setExtraDollar(true); }
( <IDENTIFIER> | <OLD_IDENTIFIER> ) (Index())*
(LOOKAHEAD(2) <DOT> (LOOKAHEAD(3) Method() | Identifier() ) (Index())* )*
[ <PIPE> Expression() ]
diff --git a/velocity-engine-core/src/main/resources/org/apache/velocity/runtime/defaults/velocity.properties b/velocity-engine-core/src/main/resources/org/apache/velocity/runtime/defaults/velocity.properties
index fc9d2481..14ee713d 100644
--- a/velocity-engine-core/src/main/resources/org/apache/velocity/runtime/defaults/velocity.properties
+++ b/velocity-engine-core/src/main/resources/org/apache/velocity/runtime/defaults/velocity.properties
@@ -157,6 +157,16 @@ runtime.interpolate_string_literals = true
# ----------------------------------------------------------------------------
runtime.immutable_ranges = true
+# ----------------------------------------------------------------------------
+# DEPRECATION WARNINGS
+# ----------------------------------------------------------------------------
+# Warn about VTL syntax constructs deprecated for the next major version
+# (informal '$foo.bar' notation in output, the '|' default-value operator, ...).
+# OFF by default: this is a drop-in minor release and the informal notation is
+# pervasive; enable it to audit a template base ahead of the next major.
+# ----------------------------------------------------------------------------
+runtime.deprecation.warn = false
+
# ----------------------------------------------------------------------------
# RESOURCE MANAGEMENT