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:36 UTC
(groovy) 25/34: GROOVY-11938: {@snippet} per JEP 413 (markup comments: highlight/replace/link/region)
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 7971da0b2b6509ba1050205ea3ad7333e98d8054
Author: Paul King <pa...@asert.com.au>
AuthorDate: Tue Apr 21 06:32:08 2026 +1000
GROOVY-11938: {@snippet} per JEP 413 (markup comments: highlight/replace/link/region)
---
.../groovy/tools/groovydoc/TagRenderer.java | 278 ++++++++++++++++++++-
.../groovy/tools/groovydoc/GroovyDocToolTest.java | 71 ++++++
.../testfiles/ClassWithSnippetMarkup.groovy | 44 ++++
3 files changed, 391 insertions(+), 2 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 aba098dccf..d4f9ea023d 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
@@ -35,7 +35,9 @@ import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
+import java.util.regex.Matcher;
import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
/**
* Single-pass tokenizer and renderer for Javadoc-style inline tags and
@@ -245,7 +247,7 @@ final class TagRenderer {
// 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, rootDoc, classDoc);
+ return renderSnippetAt(text, start, nameEnd, out, links, relPath, rootDoc, classDoc);
}
int bodyStart = skipWhitespace(text, nameEnd);
// Match the previous regex's laxness: body extends to the first '}'.
@@ -280,6 +282,7 @@ final class TagRenderer {
* or 0 if the tag is malformed.
*/
private static int renderSnippetAt(String text, int start, int nameEnd, StringBuilder out,
+ List<LinkArgument> links, String relPath,
GroovyRootDoc rootDoc, SimpleGroovyClassDoc classDoc) {
int n = text.length();
int i = skipWhitespace(text, nameEnd);
@@ -378,11 +381,17 @@ final class TagRenderer {
String combined = (langClass.isEmpty() ? "" : "language-" + langClass)
+ (extraClass.isEmpty() ? "" : (langClass.isEmpty() ? extraClass : " " + extraClass));
String dedented = dedent(body);
+ // GROOVY-11938 stage 3: process JEP 413 markup comments (// @highlight,
+ // // @replace, // @link) inside the snippet body. Markup-comment lines
+ // are stripped from the rendered output; their directives annotate the
+ // target line with bold/italic/highlight wrappers, inline replacements,
+ // or hyperlinks.
+ String processed = processSnippetMarkup(dedented, links, relPath, rootDoc, classDoc);
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>");
+ out.append('>').append(processed).append("</code></pre>");
return endPos - start;
}
@@ -445,6 +454,271 @@ final class TagRenderer {
return sb.toString();
}
+ /**
+ * GROOVY-11938 stage 3: JEP 413 markup-comment processor. Walks the snippet
+ * body line-by-line looking for {@code // @highlight}, {@code // @replace},
+ * and {@code // @link} directives. Directive comments are stripped from
+ * the output. Each directive targets the same line if written after code,
+ * or the next non-directive line if written standalone.
+ *
+ * <p>Directive forms accepted:
+ * <ul>
+ * <li>{@code @highlight [substring="..."|regex="..."] [type="bold|italic|highlighted"]}
+ * — wraps matching text in {@code <b>}/{@code <i>}/{@code <mark>}.
+ * Default type is {@code bold}.</li>
+ * <li>{@code @replace [substring="..."|regex="..."] replacement="..."}
+ * — substitutes matching text.</li>
+ * <li>{@code @link [substring="..."|regex="..."] target="Class[#member]"}
+ * — resolves {@code target} via the existing {@code {@link}} machinery
+ * and wraps matching text in an {@code <a href="...">} anchor.</li>
+ * </ul>
+ *
+ * <p>Out of scope in this pass: region-scoped variants
+ * ({@code region="name"}), which are a natural follow-up layered on top of
+ * the existing external-file region machinery.
+ */
+ private static String processSnippetMarkup(String body, List<LinkArgument> links, String relPath,
+ GroovyRootDoc rootDoc, SimpleGroovyClassDoc classDoc) {
+ String[] lines = body.split("\n", -1);
+ List<Directive> pending = new ArrayList<>();
+ // GROOVY-11938 stage 3 region support: directives that carry a
+ // `region="name"` attribute activate at their own line and remain in
+ // effect until the matching `// @end` marker (or end of snippet).
+ List<Directive> regionActive = new ArrayList<>();
+ StringBuilder out = new StringBuilder();
+ boolean first = true;
+ for (String line : lines) {
+ // Region markers `// @start region="name"` / `// @end [region="name"]`
+ // are stripped from the output regardless of any directive state.
+ if (isRegionStart(line) != null) continue;
+ String endRegion = isRegionEnd(line);
+ if (endRegion != null) {
+ deactivateRegion(regionActive, endRegion);
+ continue;
+ }
+ int commentIdx = findMarkupCommentStart(line);
+ Directive parsed = null;
+ if (commentIdx >= 0) {
+ String commentText = line.substring(commentIdx + 2).trim();
+ parsed = parseDirective(commentText);
+ }
+ if (parsed != null) {
+ String region = parsed.attrs.get("region");
+ String before = line.substring(0, commentIdx);
+ if (region != null && !region.isEmpty()) {
+ // Region-scoped directive — activate, drop this line.
+ regionActive.add(parsed);
+ continue;
+ }
+ if (before.trim().isEmpty()) {
+ // Standalone directive — queue for next code line, drop this line.
+ pending.add(parsed);
+ continue;
+ } else {
+ // EOL directive — apply to the code portion only (trailing
+ // whitespace trimmed off), drop the directive comment.
+ String code = before.replaceFirst("\\s+$", "");
+ List<Directive> effective = new ArrayList<>(regionActive);
+ effective.add(parsed);
+ String rendered = applyDirectives(code, effective, links, relPath, rootDoc, classDoc);
+ if (!first) out.append('\n');
+ out.append(rendered);
+ first = false;
+ continue;
+ }
+ }
+ // Normal line — apply active region directives plus any queued
+ // standalone directives (latter only consumed once).
+ List<Directive> effective = new ArrayList<>(regionActive);
+ effective.addAll(pending);
+ String rendered = applyDirectives(line, effective, links, relPath, rootDoc, classDoc);
+ pending.clear();
+ if (!first) out.append('\n');
+ out.append(rendered);
+ first = false;
+ }
+ return out.toString();
+ }
+
+ /** Return the region name if the line is a `// @start region="name"` marker, else {@code null}. */
+ private static String isRegionStart(String line) {
+ Matcher m = Pattern.compile("^\\s*//\\s*@start\\b([^\\n]*)").matcher(line);
+ if (!m.find()) return null;
+ Matcher r = Pattern.compile("region\\s*=\\s*(['\"]?)([^'\"\\s]+)\\1").matcher(m.group(1));
+ return r.find() ? r.group(2) : "";
+ }
+
+ /** Return the region name if the line is a `// @end [region="name"]` marker, empty string for an unnamed `// @end`, or {@code null} otherwise. */
+ private static String isRegionEnd(String line) {
+ Matcher m = Pattern.compile("^\\s*//\\s*@end\\b([^\\n]*)").matcher(line);
+ if (!m.find()) return null;
+ Matcher r = Pattern.compile("region\\s*=\\s*(['\"]?)([^'\"\\s]+)\\1").matcher(m.group(1));
+ return r.find() ? r.group(2) : "";
+ }
+
+ /** Remove directives from {@code regionActive} that match the given end-region name. An unnamed {@code // @end} deactivates every region-scoped directive. */
+ private static void deactivateRegion(List<Directive> regionActive, String endRegion) {
+ if (endRegion.isEmpty()) { regionActive.clear(); return; }
+ regionActive.removeIf(d -> endRegion.equals(d.attrs.get("region")));
+ }
+
+ /** Scan a line for the start of a recognised markup comment ({@code //} + optional space + {@code @highlight}/{@code @replace}/{@code @link}); returns the offset of the {@code //} or {@code -1}. */
+ private static int findMarkupCommentStart(String line) {
+ int i = 0, n = line.length();
+ while (i <= n - 2) {
+ if (line.charAt(i) == '/' && line.charAt(i + 1) == '/') {
+ int j = i + 2;
+ while (j < n && (line.charAt(j) == ' ' || line.charAt(j) == '\t')) j++;
+ if (j < n && line.charAt(j) == '@') {
+ int k = j + 1;
+ while (k < n && Character.isLetterOrDigit(line.charAt(k))) k++;
+ String name = line.substring(j + 1, k);
+ if ("highlight".equals(name) || "replace".equals(name) || "link".equals(name)) {
+ return i;
+ }
+ }
+ }
+ i++;
+ }
+ return -1;
+ }
+
+ /** Parsed markup directive with name + attributes. */
+ private static final class Directive {
+ final String name;
+ final Map<String, String> attrs;
+ Directive(String name, Map<String, String> attrs) { this.name = name; this.attrs = attrs; }
+ }
+
+ /** Parse a string of the form {@code @name attr1="v1" attr2=v2} into a {@link Directive}. Returns {@code null} on unrecognised names or malformed input. */
+ private static Directive parseDirective(String s) {
+ if (s == null || !s.startsWith("@")) return null;
+ int i = 1, n = s.length();
+ while (i < n && Character.isLetterOrDigit(s.charAt(i))) i++;
+ String name = s.substring(1, i);
+ if (!"highlight".equals(name) && !"replace".equals(name) && !"link".equals(name)) return null;
+ Map<String, String> attrs = new LinkedHashMap<>();
+ while (i < n) {
+ while (i < n && Character.isWhitespace(s.charAt(i))) i++;
+ if (i >= n) break;
+ int nameS = i;
+ while (i < n && (Character.isLetterOrDigit(s.charAt(i)) || s.charAt(i) == '_')) i++;
+ String attrName = s.substring(nameS, i);
+ if (attrName.isEmpty()) break;
+ while (i < n && Character.isWhitespace(s.charAt(i))) i++;
+ String val = "";
+ if (i < n && s.charAt(i) == '=') {
+ i++;
+ while (i < n && Character.isWhitespace(s.charAt(i))) i++;
+ if (i < n && (s.charAt(i) == '"' || s.charAt(i) == '\'')) {
+ char q = s.charAt(i);
+ int close = s.indexOf(q, i + 1);
+ if (close < 0) return null;
+ val = s.substring(i + 1, close);
+ i = close + 1;
+ } else {
+ int valS = i;
+ while (i < n && !Character.isWhitespace(s.charAt(i))) i++;
+ val = s.substring(valS, i);
+ }
+ }
+ attrs.put(attrName, val);
+ }
+ return new Directive(name, attrs);
+ }
+
+ /** Apply a list of directives to a single line, HTML-escaping untouched content. */
+ private static String applyDirectives(String line, List<Directive> directives,
+ List<LinkArgument> links, String relPath,
+ GroovyRootDoc rootDoc, SimpleGroovyClassDoc classDoc) {
+ String escaped = SimpleGroovyClassDoc.encodeAngleBrackets(line);
+ if (directives.isEmpty()) return escaped;
+ for (Directive d : directives) {
+ escaped = applyDirective(escaped, d, links, relPath, rootDoc, classDoc);
+ }
+ return escaped;
+ }
+
+ /** Apply one directive to an already HTML-escaped line. */
+ private static String applyDirective(String escaped, Directive d,
+ List<LinkArgument> links, String relPath,
+ GroovyRootDoc rootDoc, SimpleGroovyClassDoc classDoc) {
+ Pattern pat = buildMatchPattern(d);
+ if (pat == null) return escaped; // no match clause — nothing to do
+ Matcher m = pat.matcher(escaped);
+ StringBuilder sb = new StringBuilder();
+ int last = 0;
+ while (m.find()) {
+ sb.append(escaped, last, m.start());
+ String match = m.group();
+ String wrapped = wrapForDirective(match, d, links, relPath, rootDoc, classDoc);
+ sb.append(wrapped);
+ last = m.end();
+ }
+ sb.append(escaped, last, escaped.length());
+ return sb.toString();
+ }
+
+ /**
+ * Build a regex matching the directive's {@code substring} or {@code regex}
+ * attribute, run against the already-escaped line text. Returns {@code null}
+ * when neither attribute is present.
+ */
+ private static Pattern buildMatchPattern(Directive d) {
+ String substring = d.attrs.get("substring");
+ String regex = d.attrs.get("regex");
+ if (substring != null && !substring.isEmpty()) {
+ // Escape the user's literal substring with the same angle-bracket
+ // encoder applied to the line, then quote for regex.
+ String escapedSub = SimpleGroovyClassDoc.encodeAngleBrackets(substring);
+ return Pattern.compile(Pattern.quote(escapedSub));
+ }
+ if (regex != null && !regex.isEmpty()) {
+ try {
+ return Pattern.compile(regex);
+ } catch (PatternSyntaxException e) {
+ return null;
+ }
+ }
+ return null;
+ }
+
+ /** Produce the HTML wrapping that a directive applies to one match. */
+ private static String wrapForDirective(String match, Directive d,
+ List<LinkArgument> links, String relPath,
+ GroovyRootDoc rootDoc, SimpleGroovyClassDoc classDoc) {
+ switch (d.name) {
+ case "highlight": {
+ String type = d.attrs.getOrDefault("type", "bold");
+ switch (type) {
+ case "italic": return "<i>" + match + "</i>";
+ case "highlighted": return "<mark>" + match + "</mark>";
+ case "bold":
+ default: return "<b>" + match + "</b>";
+ }
+ }
+ case "replace": {
+ String replacement = d.attrs.getOrDefault("replacement", "");
+ return SimpleGroovyClassDoc.encodeAngleBrackets(replacement);
+ }
+ case "link": {
+ String target = d.attrs.getOrDefault("target", "");
+ if (target.isEmpty()) return match;
+ String url = SimpleGroovyClassDoc.getDocUrl(target, false, links, relPath, rootDoc, classDoc);
+ // getDocUrl returns HTML like `<a href='...' title='...'>text</a>` —
+ // pull just the href and wrap the match in our own anchor so the
+ // visible text remains the code's own identifier.
+ Matcher hrefM = Pattern.compile("href='([^']+)'").matcher(url);
+ if (hrefM.find()) {
+ return "<a href=\"" + hrefM.group(1) + "\">" + match + "</a>";
+ }
+ return match;
+ }
+ default:
+ return match;
+ }
+ }
+
/**
* Strip leading blank lines from a snippet body and remove the common
* indentation (smallest non-empty leading-whitespace prefix) — matches
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 739540a40c..17f17296bb 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
@@ -495,6 +495,77 @@ public class GroovyDocToolTest extends GroovyTestCase {
page.contains("the doubled value"));
}
+ // GROOVY-11938 stage 3: {@snippet} markup comments. Recognises three
+ // directives inside a snippet body — @highlight, @replace, @link — in
+ // either EOL (after code) or standalone-line (applies to next line) form.
+ // Markup-comment lines are stripped from the output.
+ public void testSnippetMarkupDirectives() throws Exception {
+ String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
+ htmlTool.add(List.of(base + "/ClassWithSnippetMarkup.groovy",
+ base + "/ScriptWithSiblingClassLinks.groovy"));
+ MockOutputTool output = new MockOutputTool();
+ htmlTool.renderToOutput(output, MOCK_DIR);
+
+ String page = output.getText(MOCK_DIR + "/" + base + "/ClassWithSnippetMarkup.html");
+ assertNotNull(page);
+ int snippetIdx = page.indexOf("<pre><code class=\"language-groovy\">");
+ assertTrue("Snippet block expected in:\n" + page, snippetIdx >= 0);
+ int snippetEnd = page.indexOf("</code></pre>", snippetIdx);
+ String snippet = page.substring(snippetIdx, snippetEnd + "</code></pre>".length());
+
+ // @highlight: "greet" wrapped in <b>.
+ assertTrue("@highlight bold expected around `greet` in:\n" + snippet,
+ snippet.contains("<b>greet</b>"));
+ // @replace: "TODO: fill this in" string substituted with replacement text.
+ assertFalse("Replaced text TODO should NOT appear in snippet:\n" + snippet,
+ snippet.contains("TODO: fill this in"));
+ assertTrue("Replacement text expected in snippet:\n" + snippet,
+ snippet.contains("see SiblingHelper"));
+ // @link: SiblingHelper wrapped in an anchor to its doc page.
+ assertTrue("@link anchor wrapping SiblingHelper expected in:\n" + snippet,
+ snippet.matches("(?s).*<a href=\"[^\"]*SiblingHelper\\.html\">SiblingHelper</a>.*"));
+ // Markup-comment lines themselves must be stripped.
+ assertFalse("// @highlight directive line should be stripped:\n" + snippet,
+ snippet.contains("@highlight"));
+ assertFalse("// @replace directive line should be stripped:\n" + snippet,
+ snippet.contains("@replace"));
+ assertFalse("// @link directive line should be stripped:\n" + snippet,
+ snippet.contains("@link"));
+ }
+
+ // GROOVY-11938 stage 3 region support: a directive with region="name"
+ // activates at its line and applies until the matching // @end marker.
+ public void testSnippetMarkupRegionScoping() throws Exception {
+ String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
+ htmlTool.add(List.of(base + "/ClassWithSnippetMarkup.groovy",
+ base + "/ScriptWithSiblingClassLinks.groovy"));
+ MockOutputTool output = new MockOutputTool();
+ htmlTool.renderToOutput(output, MOCK_DIR);
+
+ String page = output.getText(MOCK_DIR + "/" + base + "/ClassWithSnippetMarkup.html");
+ assertNotNull(page);
+ // Locate the SECOND snippet block (the region-scoped one).
+ int first = page.indexOf("<pre><code class=\"language-groovy\">");
+ int second = page.indexOf("<pre><code class=\"language-groovy\">", first + 1);
+ assertTrue("Second snippet block expected", second > first);
+ int end = page.indexOf("</code></pre>", second);
+ String snippet = page.substring(second, end);
+
+ // Inside region: both `call` and `call2` should have <mark> wrapping "call".
+ assertTrue("Region-scoped highlight should mark `call` inside def call(x):\n" + snippet,
+ snippet.contains("def <mark>call</mark>(x)"));
+ assertTrue("Region-scoped highlight should mark `call` inside def call2(x):\n" + snippet,
+ snippet.contains("def <mark>call</mark>2(x)"));
+ // Outside region: `call` on the afterRegion line should NOT be highlighted.
+ int afterIdx = snippet.indexOf("afterRegion");
+ String afterPortion = snippet.substring(afterIdx);
+ assertFalse("Highlight must not leak past @end into afterRegion line:\n" + afterPortion,
+ afterPortion.contains("<mark>"));
+ // @end / @start marker lines themselves stripped.
+ assertFalse("@end region marker line should be stripped:\n" + snippet,
+ snippet.contains("@end"));
+ }
+
// GROOVY-11938 stage 5: Markdown and {@snippet} interop. A /// doc comment
// containing a Markdown heading, an inline {@snippet}, and a fenced
// Markdown code block emits three distinct HTML chunks without the
diff --git a/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithSnippetMarkup.groovy b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithSnippetMarkup.groovy
new file mode 100644
index 0000000000..7bf8553805
--- /dev/null
+++ b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithSnippetMarkup.groovy
@@ -0,0 +1,44 @@
+/*
+ * 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 stage 3 fixture: {@snippet} markup comments.
+ *
+ * {@snippet lang="groovy" :
+ * def greet(name) { "Hello, $name!" } // @highlight substring="greet" type="bold"
+ * def aside = "TODO: fill this in" // @replace substring="TODO: fill this in" replacement="see SiblingHelper"
+ * // @link substring="SiblingHelper" target="SiblingHelper"
+ * def helper = SiblingHelper.otherMethod()
+ * }
+ *
+ * Region-scoped variant — a {@code region} attribute activates the directive
+ * until a matching {@code // @end} marker:
+ *
+ * {@snippet lang="groovy" :
+ * def regular = 1
+ * // @highlight region="api" substring="call" type="highlighted"
+ * def call(x) { x }
+ * def call2(x) { x + 1 }
+ * // @end region="api"
+ * def afterRegion = "call"
+ * }
+ */
+class ClassWithSnippetMarkup {
+}