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
The following commit(s) were added to refs/heads/master by this push:
new 53181454e0 GROOVY-12029: Graduate Macro and related classes from
incubating to stable
53181454e0 is described below
commit 53181454e08716af1fb76927215775fb75084f56
Author: Paul King <[email protected]>
AuthorDate: Fri May 22 22:22:29 2026 +1000
GROOVY-12029: Graduate Macro and related classes from incubating to stable
---
src/spec/doc/core-metaprogramming.adoc | 21 +++++++++++++++++++++
.../groovy/macrolib/MacroLibGroovyMethods.java | 4 +++-
.../codehaus/groovy/macro/matcher/ASTMatcher.groovy | 9 ++++-----
.../groovy/macro/matcher/MatchingConstraints.groovy | 1 +
.../internal/MatchingConstraintsBuilder.groovy | 3 +++
.../org/codehaus/groovy/macro/runtime/Macro.java | 3 ---
.../codehaus/groovy/macro/runtime/MacroBuilder.java | 3 ---
.../codehaus/groovy/macro/runtime/MacroContext.java | 3 ---
.../codehaus/groovy/macro/transform/MacroClass.java | 3 ---
9 files changed, 32 insertions(+), 18 deletions(-)
diff --git a/src/spec/doc/core-metaprogramming.adoc
b/src/spec/doc/core-metaprogramming.adoc
index 17e21ce42a..41bac4bf5a 100644
--- a/src/spec/doc/core-metaprogramming.adoc
+++ b/src/spec/doc/core-metaprogramming.adoc
@@ -3324,6 +3324,27 @@ def nullObject = null
assert null == safe(safe(nullObject.hashcode()).toString())
----
+===== Disabling macro methods
+
+The `groovy.macro.disable` system property suppresses selected `@Macro`
+methods from extension lookup before macro expansion runs. Its value is a
+comma-separated list of bare method names; any macro method whose name
+appears in the list is filtered out of the macro extension cache. For
+example, compiling with `-Dgroovy.macro.disable=DO,SVI` skips both the `DO`
+and `SVI` macros that ship with the `groovy-macro-library` module.
+
+A few details to be aware of:
+
+* *Bare-name matching only.* Every overload of a disabled name is filtered
+ together, and the same name in different modules collides globally. There
+ is no per-signature form (unlike `groovy.extension.disable`, which accepts
+ `name(type1,type2,...)` for regular extension methods).
+* *Read once at compiler startup.* The property is captured when the macro
+ extension cache is first initialised, so it must be set as a `-D` argument
+ to the JVM that runs the Groovy compiler.
+* *No whitespace trimming.* Entries are split on commas only, so write
+ `-Dgroovy.macro.disable=DO,SVI`, not `-Dgroovy.macro.disable=DO, SVI`.
+
==== Testing AST transformations
===== Separating source trees
diff --git
a/subprojects/groovy-macro-library/src/main/groovy/org/apache/groovy/macrolib/MacroLibGroovyMethods.java
b/subprojects/groovy-macro-library/src/main/groovy/org/apache/groovy/macrolib/MacroLibGroovyMethods.java
index 5a7b08a061..fecdaa89bd 100644
---
a/subprojects/groovy-macro-library/src/main/groovy/org/apache/groovy/macrolib/MacroLibGroovyMethods.java
+++
b/subprojects/groovy-macro-library/src/main/groovy/org/apache/groovy/macrolib/MacroLibGroovyMethods.java
@@ -57,7 +57,7 @@ import static org.codehaus.groovy.ast.tools.GeneralUtils.stmt;
/**
* Macro library helpers for string and named-value expansion.
*
- * @since 2.5.0
+ * @since 4.0.0
*/
public final class MacroLibGroovyMethods {
private MacroLibGroovyMethods() {}
@@ -215,6 +215,7 @@ public final class MacroLibGroovyMethods {
* @param ctx the current macro context
* @param exps the generators (each {@code name in expression}) followed
by the body closure
* @return the nested bind-chain expression
+ * @since 6.0.0
*/
@Macro
public static Expression DO(MacroContext ctx, final Expression... exps) {
@@ -285,6 +286,7 @@ public final class MacroLibGroovyMethods {
* @param self the receiver
* @param args the runtime values
* @return never returns normally
+ * @since 6.0.0
*/
public static Object DO(Object self, Object... args) {
throw new IllegalStateException("MacroLibGroovyMethods.DO(Object...)
should never be called at runtime. Are you sure you are using it correctly?");
diff --git
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/ASTMatcher.groovy
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/ASTMatcher.groovy
index c6b85acb90..feb6c17faa 100644
---
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/ASTMatcher.groovy
+++
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/ASTMatcher.groovy
@@ -1052,15 +1052,14 @@ class ASTMatcher extends ContextualClassCodeVisitor {
}
/**
- * TODO: experimental!
- *
- * Annotates an AST node with matching contraints. This method should be
called
- * on an AST intended to be used as a pattern only. It will put node
metadata on
- * the AST node allowing customized behavior in pattern matching.
+ * Annotates an AST node with matching constraints. Call this on an AST
+ * intended to be used as a pattern only; it attaches node metadata that
+ * customises behaviour during pattern matching.
*
* @param pattern a pattern AST
* @param constraintsSpec a closure specification of matching constraints
* @return the same pattern, annotated with constraints
+ * @since 2.5.0
*/
static ASTNode withConstraints(ASTNode pattern,
@DelegatesTo(value=MatchingConstraintsBuilder, strategy=Closure.DELEGATE_ONLY)
Closure constraintsSpec) {
def builder = new MatchingConstraintsBuilder()
diff --git
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/MatchingConstraints.groovy
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/MatchingConstraints.groovy
index 2bdd033dcd..8b04c7a51c 100644
---
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/MatchingConstraints.groovy
+++
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/MatchingConstraints.groovy
@@ -38,6 +38,7 @@ class MatchingConstraints {
public final static ConstraintPredicate<Token> ANY_TOKEN =
AnyTokenMatch.INSTANCE
final Set<String> placeholders
+ /** @since 5.0.0 */
final Set<String> varargPlaceholders
final ConstraintPredicate<Token> tokenPredicate
final ConstraintPredicate<TreeContext> eventually
diff --git
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/internal/MatchingConstraintsBuilder.groovy
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/internal/MatchingConstraintsBuilder.groovy
index 1816245f38..01ed129330 100644
---
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/internal/MatchingConstraintsBuilder.groovy
+++
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/matcher/internal/MatchingConstraintsBuilder.groovy
@@ -34,6 +34,8 @@ class MatchingConstraintsBuilder {
Set<String> placeholders = new LinkedHashSet<>()
/**
* Placeholder names that can absorb multiple arguments.
+ *
+ * @since 5.0.0
*/
Set<String> varargPlaceholders = new LinkedHashSet<>()
/**
@@ -92,6 +94,7 @@ class MatchingConstraintsBuilder {
*
* @param names the vararg placeholder names
* @return this builder
+ * @since 5.0.0
*/
MatchingConstraintsBuilder varargPlaceholder(String... names) {
names.each { String it -> varargPlaceholders.add(it) }
diff --git
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/Macro.java
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/Macro.java
index 6d76564a5d..ce660c9b34 100644
---
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/Macro.java
+++
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/Macro.java
@@ -18,8 +18,6 @@
*/
package org.codehaus.groovy.macro.runtime;
-import org.apache.groovy.lang.annotation.Incubating;
-
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@@ -30,6 +28,5 @@ import java.lang.annotation.Target;
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
-@Incubating
public @interface Macro {
}
diff --git
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroBuilder.java
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroBuilder.java
index ed84ca97c5..4a329ed74f 100644
---
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroBuilder.java
+++
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroBuilder.java
@@ -19,7 +19,6 @@
package org.codehaus.groovy.macro.runtime;
import groovy.lang.Closure;
-import org.apache.groovy.lang.annotation.Incubating;
import org.codehaus.groovy.ast.ASTNode;
import org.codehaus.groovy.ast.ClassCodeExpressionTransformer;
import org.codehaus.groovy.ast.ClassNode;
@@ -43,8 +42,6 @@ import static
org.codehaus.groovy.macro.methods.MacroGroovyMethods.DOLLAR_VALUE;
*
* @since 2.5.0
*/
-
-@Incubating
public enum MacroBuilder {
/** Shared macro builder instance. */
INSTANCE;
diff --git
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroContext.java
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroContext.java
index 4f210a24c3..31fe84510a 100644
---
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroContext.java
+++
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/runtime/MacroContext.java
@@ -18,7 +18,6 @@
*/
package org.codehaus.groovy.macro.runtime;
-import org.apache.groovy.lang.annotation.Incubating;
import org.codehaus.groovy.ast.expr.MethodCallExpression;
import org.codehaus.groovy.control.CompilationUnit;
import org.codehaus.groovy.control.SourceUnit;
@@ -28,8 +27,6 @@ import org.codehaus.groovy.control.SourceUnit;
*
* @since 2.5.0
*/
-
-@Incubating
public class MacroContext {
private final MethodCallExpression call;
diff --git
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/transform/MacroClass.java
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/transform/MacroClass.java
index 5a3b031eaa..37745f3d4d 100644
---
a/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/transform/MacroClass.java
+++
b/subprojects/groovy-macro/src/main/groovy/org/codehaus/groovy/macro/transform/MacroClass.java
@@ -18,13 +18,10 @@
*/
package org.codehaus.groovy.macro.transform;
-import org.apache.groovy.lang.annotation.Incubating;
-
/**
* Marker base class for anonymous classes expanded into {@link
org.codehaus.groovy.ast.ClassNode} instances.
*
* @since 2.5.0
*/
-@Incubating
public abstract class MacroClass {
}
