[engine] Review VELOCITY-926 fix:

deprecate velocimacro.arguments.preserve_literals in favor of the new velocimacro.enable_bc_mode flag,
which mimics 1.7 velocimacro behavior:

- preserve arguments literals:

    #macro(m $arg) $arg #end
    m($null)

will displays $arg w/o bc mode and $null with bc mode

- use global defaults for missing arguments:

    #macro(m $foo) $foo #end
    #set($foo='foo')
    #m()

will display $foo w/o bc mode and 'foo' with bc mode

The following use cases have been left aside from backward compatibility:

- preserving local macro scope values

    #macro(test) #set($foo = 'foo') $some_tool.change_foo_value_in_global_context_to_bar() $foo #end
    #test()

will always display 'bar', while 1.7 displayed 'foo'

- setting a null argument to null, while argument name exists in context, 

    #macro(setnull $foo) #set($foo = $null) #end
    #set($foo='foo')
    #setnull($null)
    $foo

Will always display 'foo' (w or w/o bc mode), while 1.7 did display $foo




git-svn-id: https://svn.apache.org/repos/asf/velocity/engine/trunk@1873244 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 15 insertions, 5 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 9b640e8d..89d3c41f 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
@@ -331,11 +331,21 @@ public interface RuntimeConstants extends DeprecatedRuntimeConstants
     String VM_ARGUMENTS_STRICT = "velocimacro.arguments.strict";
 
     /**
-     * When displaying null or invalid non-quiet references, use the argument literal reference
-     * instead of the one in the macro block. Defaults to false.
-     * @since 2.1
-     **/
-    String VM_PRESERVE_ARGUMENTS_LITERALS = "velocimacro.arguments.preserve_literals";
+     * This flag enable the 1.7 backward compatible mode for velocimacros (defaults to false):
+     * <ul>
+     *     <li>
+     *         preserve argument literals: when displaying null or invalid non-quiet references,
+     *         use the argument literal reference instead of the one in the macro block. Defaults to false.
+     *     </li>
+     *     <li>
+     *         use global values for missing arguments: when calling a macro with fewer arguments than declared,
+     *         if those arguments don't have an explicit default value in the macro definition, default values will
+     *         be looked for in the global context
+     *     </li>
+     * </ul>
+     * @since 2.2
+     */
+    String VM_ENABLE_BC_MODE = "velocimacro.enable_bc_mode";
 
     /**
      * Specify the maximum depth for macro calls