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 2023/09/02 04:05:55 UTC
[groovy] branch master updated: GROOVY-11165: JEP 445 compatibility additional functionality
This is an automated email from the ASF dual-hosted git repository.
paulk 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 a3543ff058 GROOVY-11165: JEP 445 compatibility additional functionality
a3543ff058 is described below
commit a3543ff05824d4230c5a54f89f79b61e52a95d3f
Author: Paul King <pa...@asert.com.au>
AuthorDate: Sat Sep 2 14:05:24 2023 +1000
GROOVY-11165: JEP 445 compatibility additional functionality
---
.../java/org/codehaus/groovy/ast/ModuleNode.java | 6 +++-
.../src/spec/doc/contracts-userguide.adoc | 35 +++++++++++++++++++---
.../src/spec/test/ContractsTest.groovy | 30 ++++++++++++++-----
3 files changed, 59 insertions(+), 12 deletions(-)
diff --git a/src/main/java/org/codehaus/groovy/ast/ModuleNode.java b/src/main/java/org/codehaus/groovy/ast/ModuleNode.java
index 483a97407d..1e9f76c80b 100644
--- a/src/main/java/org/codehaus/groovy/ast/ModuleNode.java
+++ b/src/main/java/org/codehaus/groovy/ast/ModuleNode.java
@@ -384,8 +384,10 @@ public class ModuleNode extends ASTNode {
}
if (existingMain != null && !hasUncontainedStatements) {
+ // this is a JEP-445 compatible class
ClassNode result = new ClassNode(classNode.getName(), 0, ClassHelper.OBJECT_TYPE);
result.addAnnotations(existingMain.getAnnotations());
+ result.setScriptBody(false);
result.putNodeMetaData("_SKIPPABLE_ANNOTATIONS", Boolean.TRUE);
existingMain.putNodeMetaData("_SKIPPABLE_ANNOTATIONS", Boolean.TRUE);
methods.forEach(result::addMethod);
@@ -461,7 +463,9 @@ public class ModuleNode extends ASTNode {
}
/*
- * If a main method is provided by user, account for it under run() as scripts generate their own 'main' so they can run.
+ * We retain the 'main' method if a compatible one is found.
+ * A compatible one has no parameters or 1 (Object or String[]) parameter.
+ * The return type must be void or Object.
*/
private MethodNode handleMainMethodIfPresent(final List<MethodNode> methods) {
boolean foundInstance = false;
diff --git a/subprojects/groovy-contracts/src/spec/doc/contracts-userguide.adoc b/subprojects/groovy-contracts/src/spec/doc/contracts-userguide.adoc
index 712912179e..58e7f5697f 100644
--- a/subprojects/groovy-contracts/src/spec/doc/contracts-userguide.adoc
+++ b/subprojects/groovy-contracts/src/spec/doc/contracts-userguide.adoc
@@ -22,13 +22,15 @@
= Groovy Contracts – design by contract support for Groovy
This module provides contract annotations that support the specification of class-invariants,
-pre- and post-conditions on Groovy classes and interfaces.
+as well as pre- and post-conditions on Groovy classes and interfaces.
Special support is provided so that post-conditions may refer to the old value of variables
or to the result value associated with calling a method.
== Applying @Invariant, @Requires and @Ensures
-With GContracts in your class-path, contracts can be applied on a Groovy class or interface by using one of the assertions found in package org.gcontracts.annotations.
+With Groovy contracts in your classpath, contracts can be applied on a Groovy
+class or interface by using one of the annotations found in the `groovy.contracts`
+package.
[source,groovy]
----
@@ -37,7 +39,7 @@ include::../test/ContractsTest.groovy[tags=basic_example,indent=0]
== More Features
-GContracts supports the following feature set:
+Groovy contracts supports the following feature set:
* definition of class invariants, pre- and post-conditions via @Invariant, @Requires and @Ensures
* inheritance of class invariants, pre- and post-conditions of concrete predecessor classes
@@ -57,7 +59,6 @@ as annotations with closures, where closures allow you to specify arbitrary code
[source,groovy]
----
-include::../test/ContractsTest.groovy[tags=stack_prelim,indent=0]
include::../test/ContractsTest.groovy[tags=stack_example,indent=0]
----
@@ -68,3 +69,29 @@ to the method’s result with the result variable and old instance variables val
Indeed, Groovy AST transformations change these assertion annotations into Java assertion
statements (can be turned on and off with a JVM param) and inject them at appropriate places,
e.g. class-invariants are used to check an object's state before and after each method call.
+
+== Annotation closure rules
+
+* Invariants should reference class fields only.
+* Preconditions may reference class fields and arguments.
+* Postconditions may reference class fields, arguments, the `result` and
+the old value of class fields using the syntax `old.fieldname`.
+
+Old values of class fields will only be stored where Groovy
+contracts knows how to make a copy. Currently, this means
+fields with a `Cloneable` class type, primitives, the primitive
+wrapper types, `BigInteger`, `BigDecimal`, and G/Strings.
+
+== Use within scripts
+
+Currently, Groovy contracts intentionally doesn't support scripts,
+but you can use them with JEP-445 compatible scripts from Groovy 5
+as shown in this example:
+
+[source,groovy]
+----
+include::../test/ContractsTest.groovy[tags=jep445_example,indent=0]
+----
+
+You could even place an `@Invariant` annotation on the `main` method
+and it will be moved to the generated script class.
diff --git a/subprojects/groovy-contracts/src/spec/test/ContractsTest.groovy b/subprojects/groovy-contracts/src/spec/test/ContractsTest.groovy
index f32c45640c..6f10a0371f 100644
--- a/subprojects/groovy-contracts/src/spec/test/ContractsTest.groovy
+++ b/subprojects/groovy-contracts/src/spec/test/ContractsTest.groovy
@@ -36,8 +36,6 @@ class ContractsTest extends GroovyTestCase {
@Ensures({ old.speed < speed })
def accelerate(inc) { speed += inc }
- def isStarted() { started }
-
def speed() { speed }
}
@@ -49,11 +47,6 @@ class ContractsTest extends GroovyTestCase {
void testStackExample() {
assertScript '''
- /*
- // tag::stack_prelim[]
- @Grab(group='org.apache.groovy', module='groovy-contracts', version='4.0.0')
- // end::stack_prelim[]
- */
// tag::stack_example[]
import groovy.contracts.*
@@ -116,4 +109,27 @@ class ContractsTest extends GroovyTestCase {
// end::stack_example[]
'''
}
+
+ void testJep445Script() {
+ runScript '''
+ // tag::jep445_example[]
+ import groovy.contracts.*
+ import org.apache.groovy.contracts.*
+ import static groovy.test.GroovyAssert.shouldFail
+
+ @Requires({ arg > 0 })
+ @Ensures({ result < arg })
+ def sqrt(arg) { Math.sqrt(arg) }
+
+ def main() {
+ assert sqrt(4) == 2
+ shouldFail(PreconditionViolation) { sqrt(-1) }
+ }
+ // end::jep445_example[]
+ '''
+ }
+
+ private static void runScript(String scriptText) {
+ new GroovyShell().run(scriptText, 'ScriptSnippet', [] as String[])
+ }
}