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 <
+ assertTrue("Expected HTML-escaped '<' in snippet body in:\n" + doc,
+ doc.contains("if (x < 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 {
+}