You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2026/04/21 06:13:23 UTC

(groovy) 12/34: GROOVY-11938: {@snippet} per JEP 413 (phase 1: inline {@snippet} with attributes, HTML escape, dedent )

This is an automated email from the ASF dual-hosted git repository.

paulk-asert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git

commit d27df886a293350b7785e5acc50fc99bec089a79
Author: Paul King <pa...@asert.com.au>
AuthorDate: Mon Apr 20 18:57:55 2026 +1000

    GROOVY-11938: {@snippet} per JEP 413 (phase 1: inline {@snippet} with attributes, HTML escape, dedent )
---
 .../groovy/tools/groovydoc/TagRenderer.java        | 182 ++++++++++++++++++++-
 .../groovy/tools/groovydoc/GroovyDocToolTest.java  |  36 ++++
 .../groovydoc/testfiles/ClassWithSnippetTag.groovy |  38 +++++
 3 files changed, 249 insertions(+), 7 deletions(-)

diff --git a/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java b/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java
index 50ce5b7d9f..8bb6a701e3 100644
--- a/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java
+++ b/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java
@@ -38,7 +38,11 @@ import java.util.Map;
  * <p>Supported inline tags: {@code {@link ...}}, {@code {@see ...}},
  * {@code {@code ...}}, {@code {@literal ...}} (class-level only),
  * {@code {@interface ...}} (swallowed), {@code {@value #FIELD}} /
- * {@code {@value pkg.Class#FIELD}} (GROOVY-6016).
+ * {@code {@value pkg.Class#FIELD}} (GROOVY-6016),
+ * {@code {@inheritDoc}} (GROOVY-3782 — inline form, full parent comment
+ * substituted), inline {@code {@snippet}} (GROOVY-11938 stage 1 — renders
+ * as {@code <pre><code>} with language/id/class attributes and
+ * HTML-escaped body).
  *
  * <p>Supported block tags: {@code @see}, {@code @param}, {@code @return},
  * {@code @throws} / {@code @exception}, {@code @since}, {@code @author},
@@ -49,12 +53,21 @@ import java.util.Map;
  * <h2>Known limitations / pending work</h2>
  * <ul>
  *   <li>Bare {@code {@value}} (no body, referencing the current field's own
- *       constant value) is not yet supported. It requires threading the
- *       current member through {@code TagRenderer}; the tag currently falls
- *       through to verbatim emission. {@code {@value #FIELD}} and
- *       {@code {@value Class#FIELD}} both work.</li>
- *   <li>{@code {@inheritDoc}} — GROOVY-3782, pending.</li>
- *   <li>{@code {@snippet}} — GROOVY-11938, pending.</li>
+ *       constant value) is not yet supported — see task #25. The forms
+ *       {@code {@value #FIELD}} and {@code {@value Class#FIELD}} both work.</li>
+ *   <li>{@code {@snippet}} external form ({@code file="..."} /
+ *       {@code region="..."} reading from a package's
+ *       {@code snippet-files/} directory) not yet implemented — stage 2
+ *       of GROOVY-11938.</li>
+ *   <li>{@code {@snippet}} markup comments ({@code // @highlight},
+ *       {@code @replace}, {@code @link}, {@code @start}/{@code @end})
+ *       not yet implemented — stage 3 of GROOVY-11938.</li>
+ *   <li>Client-side syntax highlighting assets (Prism.js / highlight.js)
+ *       not yet wired in — stage 4 of GROOVY-11938.</li>
+ *   <li>{@code {@inheritDoc}} inherits the full parent comment rather than
+ *       position-aware substitution inside specific block tags (e.g.
+ *       {@code @param x {@inheritDoc}} inheriting just the parent's
+ *       {@code @param x}). Reasonable initial implementation.</li>
  *   <li>JEP 467 Markdown reference links — GROOVY-11542, pending.</li>
  * </ul>
  *
@@ -222,6 +235,12 @@ final class TagRenderer {
         if (nameEnd == nameStart) return 0;
         String name = text.substring(nameStart, nameEnd);
         if (!isKnownInlineTag(name, cfg)) return 0;
+        // GROOVY-11938: {@snippet} has JEP 413 body-parsing rules — attributes
+        // before an optional `:`, then a brace-balanced body that may contain
+        // source code with its own `{`/`}`. Needs its own parser.
+        if ("snippet".equals(name)) {
+            return renderSnippetAt(text, start, nameEnd, out);
+        }
         int bodyStart = skipWhitespace(text, nameEnd);
         // Match the previous regex's laxness: body extends to the first '}'.
         int close = text.indexOf('}', bodyStart);
@@ -231,6 +250,154 @@ final class TagRenderer {
         return close + 1 - start;
     }
 
+    /**
+     * GROOVY-11938: render a {@code {@snippet}} tag per JEP 413.
+     *
+     * <p>Stage 1 supports the inline form:
+     * <pre>
+     *   {@snippet [attr=value ...] :
+     *       ... code body (may contain matched braces) ...
+     *   }
+     * </pre>
+     * Emitted as {@code <pre><code class="language-xxx">...escaped body...</code></pre>}
+     * with HTML-safe angle-bracket encoding of the body so code is preserved
+     * verbatim. Attributes recognised so far: {@code lang} (→ language class),
+     * {@code id}, {@code class} (attribute merged with language).
+     *
+     * <p>Deferred stages: external form with {@code file=...}/{@code region=...}
+     * reading from a package's {@code snippet-files/} directory; markup comments
+     * {@code // @highlight}, {@code // @replace}, {@code // @link},
+     * {@code // @start}/{@code // @end} for annotated regions; client-side
+     * syntax highlighting assets. See the ticket for the full scope.
+     *
+     * @return characters consumed starting from {@code start} (the {@code '{'})
+     *         or 0 if the tag is malformed.
+     */
+    private static int renderSnippetAt(String text, int start, int nameEnd, StringBuilder out) {
+        int n = text.length();
+        int i = skipWhitespace(text, nameEnd);
+
+        java.util.Map<String, String> attrs = new LinkedHashMap<>();
+        while (i < n) {
+            char c = text.charAt(i);
+            if (c == ':' || c == '}') break;
+            if (Character.isWhitespace(c)) { i++; continue; }
+            // Read attribute name.
+            int nameS = i;
+            while (i < n) {
+                char ch = text.charAt(i);
+                if (ch == '=' || ch == ':' || ch == '}' || Character.isWhitespace(ch)) break;
+                i++;
+            }
+            String attrName = text.substring(nameS, i);
+            i = skipWhitespace(text, i);
+            String attrValue = "";
+            if (i < n && text.charAt(i) == '=') {
+                i++;
+                i = skipWhitespace(text, i);
+                if (i >= n) return 0;
+                char q = text.charAt(i);
+                if (q == '"' || q == '\'') {
+                    int close = text.indexOf(q, i + 1);
+                    if (close < 0) return 0;
+                    attrValue = text.substring(i + 1, close);
+                    i = close + 1;
+                } else {
+                    int valS = i;
+                    while (i < n) {
+                        char ch = text.charAt(i);
+                        if (ch == ':' || ch == '}' || Character.isWhitespace(ch)) break;
+                        i++;
+                    }
+                    attrValue = text.substring(valS, i);
+                }
+            }
+            if (!attrName.isEmpty()) attrs.put(attrName, attrValue);
+        }
+        if (i >= n) return 0;
+
+        String body;
+        int endPos;
+        if (text.charAt(i) == ':') {
+            int bodyStart = i + 1;
+            // Brace-balanced body — consume until the matching close of the
+            // outer {@snippet ...}.
+            int depth = 1;
+            int j = bodyStart;
+            while (j < n && depth > 0) {
+                char c = text.charAt(j);
+                if (c == '{') depth++;
+                else if (c == '}') {
+                    depth--;
+                    if (depth == 0) break;
+                }
+                j++;
+            }
+            if (depth != 0) return 0; // unterminated
+            body = text.substring(bodyStart, j);
+            endPos = j + 1; // past the final '}'
+        } else {
+            // External form ({@snippet file="..." region="..."}) — not yet
+            // implemented. Bail and let the outer caller emit verbatim.
+            return 0;
+        }
+
+        String langClass = attrs.getOrDefault("lang", "");
+        String extraClass = attrs.getOrDefault("class", "");
+        String combined = (langClass.isEmpty() ? "" : "language-" + langClass)
+                + (extraClass.isEmpty() ? "" : (langClass.isEmpty() ? extraClass : " " + extraClass));
+        String dedented = dedent(body);
+        out.append("<pre><code");
+        if (!combined.isEmpty()) out.append(" class=\"").append(combined).append('"');
+        String id = attrs.get("id");
+        if (id != null && !id.isEmpty()) out.append(" id=\"").append(id).append('"');
+        out.append('>').append(SimpleGroovyClassDoc.encodeAngleBrackets(dedented)).append("</code></pre>");
+        return endPos - start;
+    }
+
+    /**
+     * Strip leading blank lines from a snippet body and remove the common
+     * indentation (smallest non-empty leading-whitespace prefix) — matches
+     * JEP 413's convention so indentation in the source doesn't leak into
+     * the rendered snippet.
+     */
+    private static String dedent(String body) {
+        // Drop the first line if it's only whitespace (typical when the body
+        // starts right after the `:` with a newline).
+        int firstNl = body.indexOf('\n');
+        if (firstNl >= 0) {
+            boolean firstLineBlank = true;
+            for (int k = 0; k < firstNl; k++) {
+                if (!Character.isWhitespace(body.charAt(k))) { firstLineBlank = false; break; }
+            }
+            if (firstLineBlank) body = body.substring(firstNl + 1);
+        }
+        // Strip trailing whitespace on the final line (body text before the
+        // closing `}` often has one) so `</code></pre>` lands cleanly.
+        int end = body.length();
+        while (end > 0 && (body.charAt(end - 1) == ' ' || body.charAt(end - 1) == '\t')) end--;
+        body = body.substring(0, end);
+        // Compute common leading indentation across non-blank lines.
+        String[] lines = body.split("\n", -1);
+        int common = Integer.MAX_VALUE;
+        for (String line : lines) {
+            if (line.isEmpty()) continue;
+            int lead = 0;
+            while (lead < line.length() && (line.charAt(lead) == ' ' || line.charAt(lead) == '\t')) lead++;
+            if (lead == line.length()) continue; // all-whitespace line
+            if (lead < common) common = lead;
+        }
+        if (common == Integer.MAX_VALUE || common == 0) return body;
+        StringBuilder sb = new StringBuilder(body.length());
+        for (int li = 0; li < lines.length; li++) {
+            if (li > 0) sb.append('\n');
+            String line = lines[li];
+            if (line.length() >= common) sb.append(line, common, line.length());
+            else sb.append(line);
+        }
+        return sb.toString();
+    }
+
     private static boolean isKnownInlineTag(String name, Config cfg) {
         switch (name) {
             case "link":
@@ -239,6 +406,7 @@ final class TagRenderer {
             case "interface":
             case "value":
             case "inheritDoc":
+            case "snippet":
                 return true;
             case "literal":
                 return cfg.literalEnabled;
diff --git a/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java
index eca92b1b49..6ef31fdd59 100644
--- a/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java
+++ b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java
@@ -147,6 +147,42 @@ public class GroovyDocToolTest extends GroovyTestCase {
                 doc.contains("{<DL><DT><B>inheritDoc") || doc.contains("inheritDoc:</B>"));
     }
 
+    // GROOVY-11938 stage 1: the inline {@snippet} tag renders its body as a
+    // verbatim <pre><code>...</code></pre> block with HTML-escaped content,
+    // an optional language class, id, and extra class.
+    public void testSnippetTagInlineFormRendersAsPreCode() throws Exception {
+        String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
+        htmlTool.add(List.of(base + "/ClassWithSnippetTag.groovy"));
+
+        MockOutputTool output = new MockOutputTool();
+        htmlTool.renderToOutput(output, MOCK_DIR);
+
+        String doc = output.getText(MOCK_DIR + "/" + base + "/ClassWithSnippetTag.html");
+        assertNotNull(doc);
+        // Groovy snippet: check <pre><code class="language-groovy"> wrapping.
+        assertTrue("Expected <pre><code class='language-groovy'> in:\n" + doc,
+                doc.contains("<pre><code class=\"language-groovy\">"));
+        // Body content preserved: the `def greet` line should appear escape-free
+        // (Groovy has no angle brackets in this snippet).
+        assertTrue("Expected snippet body content in:\n" + doc,
+                doc.contains("def greet(String name)"));
+        // HTML escaping: `<` in the Java snippet must appear as &lt;
+        assertTrue("Expected HTML-escaped '<' in snippet body in:\n" + doc,
+                doc.contains("if (x &lt; y)"));
+        // Language + class merged.
+        assertTrue("Expected language-java + example class merged in:\n" + doc,
+                doc.contains("class=\"language-java example\""));
+        // id attribute emitted.
+        assertTrue("Expected id=\"hello\" in:\n" + doc,
+                doc.contains("id=\"hello\""));
+        // No literal `{@snippet lang=...` with attributes (i.e. an unprocessed
+        // real snippet tag). Note that `{@code {@snippet}}` patterns in the
+        // surrounding description legitimately render as literal text inside
+        // a <CODE> block, so checking for bare `{@snippet` is too strict.
+        assertFalse("{@snippet ... } with attributes should be substituted in:\n" + doc,
+                doc.contains("{@snippet lang="));
+    }
+
     // GROOVY-3782 (the actual {@inheritDoc} tag): the child method's doc
     // should be expanded with the parent's rendered description plus tags.
     public void testInheritDocSubstitutesParentMethodDoc() throws Exception {
diff --git a/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithSnippetTag.groovy b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithSnippetTag.groovy
new file mode 100644
index 0000000000..acd1da078d
--- /dev/null
+++ b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithSnippetTag.groovy
@@ -0,0 +1,38 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.codehaus.groovy.tools.groovydoc.testfiles
+
+/**
+ * GROOVY-11938: exercise the inline {@code {@snippet}} tag per JEP 413.
+ *
+ * {@snippet lang=groovy :
+ *     def greet(String name) {
+ *         "hello $name"
+ *     }
+ *     assert greet('world') == 'hello world'
+ * }
+ *
+ * Also with a class attribute and id:
+ *
+ * {@snippet lang=java class="example" id=hello :
+ *     if (x < y) { System.out.println("ok"); }
+ * }
+ */
+class ClassWithSnippetTag {
+}