Add support for $bodyContent in macros.

If a macro is invoked not as `#foo()` but as `#@foo() ... #end`, then the variable `$bodyContent` is defined in the macro body to be the `...` content.

RELNOTES=Added support for `#@foo() ... #end`, where the `...` is available in the body of the `foo` macro as `$bodyContent`.
PiperOrigin-RevId: 499509223

Author: eamonnmcmanus

src/main/java/com/google/escapevelocity/DirectiveNode.java

@@ -223,15 +223,18 @@ public int getCount() {
   static class MacroCallNode extends DirectiveNode {
     private final String name;
     private final ImmutableList<ExpressionNode> thunks;
+    private final Node bodyContent;
 
     MacroCallNode(
         String resourceName,
         int lineNumber,
         String name,
-        ImmutableList<ExpressionNode> argumentNodes) {
+        ImmutableList<ExpressionNode> argumentNodes,
+        Node bodyContent) {
       super(resourceName, lineNumber);
       this.name = name;
       this.thunks = argumentNodes;
+      this.bodyContent = bodyContent;
     }
 
     @Override
@@ -250,7 +253,7 @@ void render(EvaluationContext context, StringBuilder output) {
                 + ", got "
                 + thunks.size());
       }
-      macro.render(context, thunks, output);
+      macro.render(context, thunks, bodyContent, output);
     }
   }
 }

src/main/java/com/google/escapevelocity/ExpressionNode.java

@@ -49,7 +49,8 @@ final void render(EvaluationContext context, StringBuilder output) {
       }
       throw evaluationException("Null value for " + this);
     }
-    if (rendered instanceof Node) { // $x when we earlier did #define ($x) ... #end
+    if (rendered instanceof Node) {
+      // A macro's $bodyContent, or $x when we earlier did #define ($x) ... #end
       ((Node) rendered).render(context, output);
     } else {
       output.append(rendered);

src/main/java/com/google/escapevelocity/Macro.java

@@ -30,34 +30,49 @@
  * means that we need to set each parameter variable to the node in the parse tree that corresponds
  * to it, and arrange for that node to be evaluated when the variable is actually referenced.
  *
+ * <p>There are two ways to invoke a macro. {@code #m('foo', 'bar')} sets $x and $y. {@code
+ * #@m('foo', 'bar') ... #end} sets $x and $y, and also sets $bodyContent to the template text
+ * {@code ...}.
+ *
  * @author [email protected] (Éamonn McManus)
  */
 class Macro {
   private final int definitionLineNumber;
   private final String name;
   private final ImmutableList<String> parameterNames;
-  private final Node body;
+  private final Node macroBody;
 
-  Macro(int definitionLineNumber, String name, List<String> parameterNames, Node body) {
+  Macro(int definitionLineNumber, String name, List<String> parameterNames, Node macroBody) {
     this.definitionLineNumber = definitionLineNumber;
     this.name = name;
     this.parameterNames = ImmutableList.copyOf(parameterNames);
-    this.body = body;
+    this.macroBody = macroBody;
   }
 
   int parameterCount() {
     return parameterNames.size();
   }
 
-  void render(EvaluationContext context, List<ExpressionNode> thunks, StringBuilder output) {
+  /**
+   * Renders a call to this macro with the arguments in {@code thunks} and with a possibly-null
+   * {@code bodyContent}. The {@code bodyContent} is non-null if the macro call looks like
+   * {@code #@foo(...) ... #end}; the {@code #@} indicates that the text up to the matching
+   * {@code #end} should be made available as the variable {@code $bodyContent} inside the macro.
+   */
+  void render(
+      EvaluationContext context,
+      List<ExpressionNode> thunks,
+      Node bodyContent,
+      StringBuilder output) {
     try {
       Verify.verify(thunks.size() == parameterNames.size(), "Argument mismatch for %s", name);
       Map<String, ExpressionNode> parameterThunks = new LinkedHashMap<>();
       for (int i = 0; i < parameterNames.size(); i++) {
         parameterThunks.put(parameterNames.get(i), thunks.get(i));
       }
-      EvaluationContext newContext = new MacroEvaluationContext(parameterThunks, context);
-      body.render(newContext, output);
+      EvaluationContext newContext =
+          new MacroEvaluationContext(parameterThunks, context, bodyContent);
+      macroBody.render(newContext, output);
     } catch (EvaluationException e) {
       EvaluationException newException = new EvaluationException(
           "In macro #" + name + " defined on line " + definitionLineNumber + ": " + e.getMessage());
@@ -85,15 +100,22 @@ void render(EvaluationContext context, List<ExpressionNode> thunks, StringBuilde
   static class MacroEvaluationContext implements EvaluationContext {
     private final Map<String, ExpressionNode> parameterThunks;
     private final EvaluationContext originalEvaluationContext;
+    private final Node bodyContent;
 
     MacroEvaluationContext(
-        Map<String, ExpressionNode> parameterThunks, EvaluationContext originalEvaluationContext) {
+        Map<String, ExpressionNode> parameterThunks,
+        EvaluationContext originalEvaluationContext,
+        Node bodyContent) {
       this.parameterThunks = parameterThunks;
       this.originalEvaluationContext = originalEvaluationContext;
+      this.bodyContent = bodyContent;
     }
 
     @Override
     public Object getVar(String var) {
+      if (bodyContent != null && var.equals("bodyContent")) {
+        return bodyContent;
+      }
       ExpressionNode thunk = parameterThunks.get(var);
       if (thunk == null) {
         return originalEvaluationContext.getVar(var);
@@ -109,7 +131,9 @@ public Object getVar(String var) {
 
     @Override
     public boolean varIsDefined(String var) {
-      return parameterThunks.containsKey(var) || originalEvaluationContext.varIsDefined(var);
+      return parameterThunks.containsKey(var)
+          || (bodyContent != null && var.equals("bodyContent"))
+          || originalEvaluationContext.varIsDefined(var);
     }
 
     @Override

src/main/java/com/google/escapevelocity/Parser.java

@@ -263,6 +263,8 @@ private Node parseNode() throws IOException {
           return parseHashSquare();
         case '{':
           return parseDirective();
+        case '@':
+          return parseMacroCallWithBody();
         default:
           if (isAsciiLetter(c)) {
             return parseDirective();
@@ -385,7 +387,7 @@ private Node parseDirective() throws IOException {
       case "macro":
         return parseMacroDefinition();
       default:
-        node = parsePossibleMacroCall(directive);
+        node = parseMacroCall("#", directive);
     }
     // Velocity skips a newline after any directive. In the case of #if etc, we'll have done this
     // when we stopped scanning the body at #end, so in those cases we return directly rather than
@@ -596,8 +598,9 @@ private Node parseMacroDefinition() throws IOException {
    * ...
    * }</pre>
    */
-  private Node parsePossibleMacroCall(String directive) throws IOException {
-    StringBuilder sb = new StringBuilder("#").append(directive);
+  private Node parseMacroCall(String prefix, String directive) throws IOException {
+    int startLine = lineNumber();
+    StringBuilder sb = new StringBuilder(prefix).append(directive);
     while (Character.isWhitespace(c)) {
       sb.appendCodePoint(c);
       next();
@@ -629,8 +632,27 @@ private Node parsePossibleMacroCall(String directive) throws IOException {
         next();
       }
     }
+    Node bodyContent;
+    if (prefix.equals("#")) {
+      bodyContent = null;
+    } else {
+      ParseResult parseResult =
+          skipNewlineAndParseToStop(
+              END_CLASS, () -> "#@" + directive + " starting on line " + startLine);
+      bodyContent = Node.cons(resourceName, startLine, parseResult.nodes);
+    }
     return new DirectiveNode.MacroCallNode(
-        resourceName, lineNumber(), directive, parameterNodes.build());
+        resourceName, lineNumber(), directive, parameterNodes.build(), bodyContent);
+  }
+
+  private Node parseMacroCallWithBody() throws IOException {
+    assert c == '@';
+    next();
+    if (!isAsciiLetter(c)) {
+      return parsePlainText("#@");
+    }
+    String id = parseId("#@");
+    return parseMacroCall("#@", id);
   }
 
   /**

src/main/java/com/google/escapevelocity/ReferenceNode.java

@@ -52,14 +52,15 @@ EvaluationException evaluationExceptionInThis(String message) {
 
   /**
    * Evaluates the first part of a complex reference, for example {@code $foo} in {@code $foo.bar}.
-   * It must not be null, and it must not be the result of a {@code #define}.
+   * It must not be null, and it must not be a macro's {@code $bodyContent} or the result of a
+   * {@code #define}.
    */
   Object evaluateLhs(ReferenceNode lhs, EvaluationContext context) {
     Object lhsValue = lhs.evaluate(context);
     if (lhsValue == null) {
       throw evaluationExceptionInThis(lhs + " must not be null");
     } else if (lhsValue instanceof Node) {
-      throw evaluationExceptionInThis(lhs + " comes from #define");
+      throw evaluationExceptionInThis(lhs + " comes from #define or is a macro's $bodyContent");
     }
     return lhsValue;
   }

src/test/java/com/google/escapevelocity/TemplateTest.java

@@ -1325,6 +1325,67 @@ public void macroArgumentMismatch() {
     expectException(template, "Wrong number of arguments to #twoArgs: expected 2, got 1");
   }
 
+  @Test
+  public void macroWithBody() {
+    // The #if ($bodyContent) is needed because Velocity treats $bodyContent as undefined if the
+    // macro is invoked as #withBody rather than #@withBody. The documented examples use
+    // $!bodyContent but that doesn't work if there is no body and Velocity is in strict ref mode.
+    String template =
+        "#macro(withBody $x)\n"
+        + "$x\n#if ($bodyContent) $bodyContent #end\n"
+        + "#end\n"
+        + "#withBody('foo')\n"
+        + "#@withBody('bar')\n"
+        + "#if (0 == 1) what #else yes #end\n"
+        + "#end ## end of #@withBody";
+    compare(template);
+  }
+
+  @Test
+  public void nestedMacrosWithBodies() {
+    String template =
+        "#macro(outer $x)\n"
+        + "$x $!bodyContent $x\n"
+        + "#end\n"
+        + "#macro(inner $x)\n"
+        + "[$x] $!bodyContent [$x]\n"
+        + "#end\n"
+        + "#@outer('foo')\n"
+        + "before inner\n"
+        + "#@inner('bar')\n"
+        + "in inner\n"
+        + "#end ## inner\n"
+        + "after inner\n"
+        + "#end ## outer\n";
+    compare(template);
+  }
+
+  @Test
+  public void bodyContentTwice() {
+    String template =
+        "#macro(one)\n"
+        + "[$bodyContent]\n"
+        + "#end\n"
+        + "#macro(two)\n"
+        + "#set($bodyContentCopy = \"$bodyContent\")\n"
+        + "<#@one()$bodyContentCopy#end>\n"
+        + "#end\n"
+        + "#@two()foo#end\n";
+    // Velocity doesn't handle this well. It shouldn't be necessary to make $bodyContentCopy; we
+    // should just be able to use $bodyContent. But that gets an exception: "Reference $bodyContent
+    // evaluated to object org.apache.velocity.runtime.directive.Block$Reference whose toString()
+    // method returned null". By evaluating it into $bodyContentCopy we avoid whatever confusion
+    // that was. This is probably related to
+    // https://issues.apache.org/jira/projects/VELOCITY/issues/VELOCITY-940.
+    compare(template);
+  }
+
+  @Test
+  public void notMacroCall() {
+    compare("#@ foo");
+    compare("#@foo no parens");
+  }
+
   @Test
   public void unclosedBlockQuote() {
     String template = "foo\nbar #[[\nblah\nblah";