updates in prep for 5.0.0
diff --git a/site/src/site/releasenotes/groovy-5.0.adoc b/site/src/site/releasenotes/groovy-5.0.adoc
index de06a68..910b8c3 100644
--- a/site/src/site/releasenotes/groovy-5.0.adoc
+++ b/site/src/site/releasenotes/groovy-5.0.adoc
@@ -9,308 +9,34 @@
Groovy 5 builds upon existing features of earlier versions of Groovy.
In addition, it incorporates numerous new features and streamlines various legacy aspects of the Groovy codebase.
-NOTE: Material on this page is still under development!
-We are currently working on release candidates for Groovy 5.0 with a goal of gathering
-final feedback on the language changes from our community.
-Groovy 5 is feature complete and largely locked down but be warned there might
-still be some changes before final release that could impact early adopters.
-
== Highlights
Key highlights of Groovy 5.0 include:
-* Support for JDK 11-25
-* Over 350 new _extension method_ additions and improvements including highly performant array operations
-* _AST Transform_ additions and improvements
-* New and improved _groovysh_ Repl based on JLine 3
-* _Java compatibility_ improvements including pattern matching for `instanceof`
-* Additional _scripting variations_ to support JEP-512 compact source files and instance main methods in addition to Groovy's shorter scripts
-* Improved Web Content Creation supporting Jakarta standards
-* Other improvements like infinite iterator generation, and index variables in loops
-
-== Additional Scripting Variations
-
-https://openjdk.org/jeps/512[JEP 512], targeted for JDK25
-(and previewed in earlier JDKs:
-https://openjdk.org/jeps/445[JEP 445]
-https://openjdk.org/jeps/463[JEP 463]
-https://openjdk.org/jeps/477[JEP 477]
-https://openjdk.org/jeps/495[JEP 495]
-),
-introduces a new `main` method signature and compact source notation for Java classes.
-Groovy 5 supports this new notation, as well as Groovy's traditional scripts,
-and an alternative abbreviated form.
-
-Let's recap the story so far. First, a traditional (Java) class:
-
-[source,java]
-----
-public class HelloWorld { // Java (also Groovy)
- public static void main(String[] args) {
- System.out.println("Hello, World!");
- }
-}
-----
-
-Second, a traditional Groovy script:
-
-[source,groovy]
-----
-println 'Hello, World!'
-----
-
-Groovy scripts are given implicit `main` and `run` methods and an implicit class definition.
-Variable declarations in scripts are local variable declarations in the implicit `run` method
-unless annotated with `@Field`, in which case they become field definitions of the implicit class.
-
-Third, the "instance main" method proposed for JEP 512 in Java with an implicit class definition:
-
-[source,java]
-----
-void main() { // Java JDK25 (also Groovy 5+)
- IO.println("Hello, World!");
-}
-----
-
-Variants with arguments are also supported as are "static main" methods.
-
-Groovy supports such methods on JDK11+ and supports some slight simplifications:
-
-[source,groovy]
-----
-def main() {
- println 'Hello, World!'
-}
-----
-
-Finally, Groovy also provides an "instance run" method as an alternative form:
-
-[source,groovy]
-----
-def run() {
- println 'Hello, World!'
-}
-----
-
-You may wonder why Groovy supports the JEP 512 notation when the traditional Groovy script
-is shorter? Firstly, there is Java compatibility, but also there are scenarios where we might like
-to use method or class annotations, and that is hard to do for an implicit method or an implicit class.
-
-`TYPE` targeted annotations on the `main` or `run` method will be moved to the generated
-script class. `METHOD` targeted annotations remain on the method.
-
-Classes created with an "instance main" method (like above) are JEP 512 compatible
-classes and will need to be invoked from the JDK with JEP 512 capability enabled
-or using the Groovy runner which now supports such classes from JDK11+.
-
-For backwards compatibility, classes created with a static `main` method are
-_promoted_ to have the normal public static void main signature. They can be run
-like normal Java or Groovy classes.
-
-There are variants in Java and Groovy to also have arguments available:
-
-[source,groovy]
-----
-@CompileStatic
-static main(args) {
- println 'Groovy world!'
-}
-----
-
-JEP 512 compatible classes may also contain other field and method definitions as shown here:
-
-[source,groovy]
-----
-def main() {
- assert upper(foo) + lower(bar) == 'FOObar'
-}
-
-def upper(s) { s.toUpperCase() }
-
-def lower = String::toLowerCase
-def (foo, bar) = ['Foo', 'Bar']
-----
-
-But they can't contain any other "uncontained" statements, otherwise they
-are treated like a normal Groovy script. Another important distinction for JEP 512
-compatible classes is that fields (like `lower`, `foo`, and `bar` in the above example)
-don't need to be annotated with `@Field`.
-
-An additional form is also supported which involves supplying a `run` method
-instead of a `main` method.
-This provides an alternate form to the earlier shown `main` variants.
-The difference is that rather than producing a JEP 512 compatible class, Groovy
-produces a script class which extends the `Script` class in the normal way and has
-access to the normal script binding and context. The use case is again where you
-might want to supply annotations, e.g.:
-
-[source,groovy]
-----
-@JsonIgnoreProperties(["binding"])
-def run() {
- var mapper = new ObjectMapper()
- assert mapper.writeValueAsString(this) == '{"pets":["cat","dog"]}'
-}
-
-public pets = ['cat', 'dog']
-----
-
-To summarise:
-
-* If you need access to the script binding or context, write a traditional class that extends the `Script` class,
-or a traditional Groovy script, or use the `run` method.
-* If you use the supported `main` or `run` method variants, you can have field definitions and other methods,
-and you don't need `@Field`. Consider these if you don't like `@Field` or you want to use annotations on the
-implicit class or the main/run method.
-* If your source file has any statements outside methods that aren't field declarations,
-it will be treated as a traditional Groovy script.
-* Use the "instance main" method variant if you want the generated bytecode to follow JEP 512 conventions.
-You will need JDK25+ to run from Java, or JDK11+ to run from Groovy.
-
-== Improved Web Content Creation
-
-=== Jakarta EE support
-
-The `groovy-servlet` module supports:
-
-* Writing servlets as Groovy scripts (_Groovlets_), e.g.:
-+
-[source,groovy]
-----
-html.html {
- head {
- title 'My first Groovlet'
- }
- body { h1 'Welcome to Groovlets!' }
-}
-----
-* Writing servlets as Groovy classes (typically extending `AbstractHttpServlet`)
-* Writing Template-style, JSP-like _Groovy Server Pages_ which combine (typically) HTML with Groovy control-logic within special tags
-
-Groovy 5 defaults to Jakarta EE versions of the Servlet-related standards.
-This mostly involves using versions of the underlying classes with different
-package names.
-
-When writing Groovlets or GSPs, the change in package name might not be apparent,
-since for simple examples, like the one shown above, the package names don't appear, but the underlying classes being used would change.
-If you are using Groovylets, your transition to Jakarta EE should be a little
-easier.
-
-You can still obtain the older Javax EE versions of the relevant classes using
-the "javax" classifier when specifying your dependency on `groovy-servlet`.
-
-== Improved Type Checking
-
-Groovy's type checking is extensible. This allows you to weaken or strengthen
-type checking. In Groovy 5, we've added a type checker for format strings.
-Errors in such strings are often not detected until runtime, but now you
-can check them at compile time. It adds to the existing regex checking
-capabilities.
-
-=== An Optional Type Checker for Format Strings
-
-The `format` methods in `java.util.Formatter`, and other similar methods,
-support formatted printing in the style of C's `printf` method with a
-format string and zero or more arguments.
-
-Let's consider an example which produces a string comprised of three terms:
-
-* a floating-point representation (`%f`) of PI (with 2 decimal places of precision),
-* the hex representation (`%X`) of 15 (as two uppercase digits with a leading 0),
-* and the Boolean (`%B`) `True` (in uppercase).
-
-The assertion checks our expectations:
-
-[source,groovy]
-----
-assert String.format('%4.2f %02X %B', Math.PI, 15, true) == '3.14 0F TRUE'
-----
-
-This is a powerful method supporting numerous conversions and flags.
-If the developer supplies incorrect conversions or flags,
-they will receive one of numerous possible runtime errors.
-As examples, consider the following mistakes and resulting runtime exceptions:
-
-* supplying a String as the parameter for either of the first two arguments results in an
-`IllegalFormatConversionException`,
-* leaving out the last argument results in a
-`MissingFormatArgumentException`,
-* supplying the _leading zero_ flag for the Boolean parameter results in a
-`FlagsConversionMismatchException`.
-
-The goal of the `FormatStringChecker` is to eliminate
-a large number of such runtime errors. If the API call passes type checking,
-it will be guaranteed to succeed at runtime.
-
-== AST transform additions and improvements
-
-=== Making Operators More Groovy
-
-There is a new `OperatorRename` AST transform.
-This is very useful when using third-party libraries which use different
-names to those used by Groovy's operator overloading functionality.
-For example, using the Apache Commons Numbers Fraction library:
-
-[source,groovy]
-----
-@OperatorRename(plus='add')
-def testAddOfTwoFractions() {
- var half = Fraction.of(1, 2)
- var third = Fraction.of(1, 3)
- assert half.add(third) == Fraction.of(5, 6) // old style still works
- assert half + third == Fraction.of(5, 6) // fraction '+' operator!
-}
-----
-
-This transform is quite handy when using various matrix packages.
-Such packages often align with Groovy's operator overloading conventions
-for many, but usually not all, operators.
-For instance, you might like to rename:
-
-* `mult` to `multiply` if using Ejml
-* `add` to `plus` if using Commons Math matrices
-* `sub` to `minus` if using Nd4j matrices
-
-Groovy has excellent support for writing Domain Specific Languages (DSLs),
-but using the `@OperatorRename` transform means we can skip constructing our own DSL in simple cases.
-
-=== Additional type safety for generated map constructors and copyWith methods
-
-Groovy provides named parameter support through a convention of using a Map as the first parameter
-for a Groovy or Java method. Such methods annotated with `@NamedParam` allow
-Groovy's static compiler to provide full compile-time type safety including detecting unknown arguments.
-Good IDEs will also provide auto-completion and checking for such methods.
-
-Groovy has a couple of dozen methods annotated in this way and also automatically generates
-such annotations already when using the `@NamedVariant` annotation or for records.
-With Groovy 5, the `@NamedParam` annotation is now also added automatically when using
-`@MapConstructor` (used by `@Immutable` and `@Canonical`) and the `copyWith` option for `@Immutable`.
-
-[source,groovy]
-----
-@Immutable(copyWith = true)
-class DoctorWho {
- String first, last
- Integer number
-}
-----
-
-If we try to create a `DoctorWho` object with an unknown parameter, or use the `copyWith` method
-with incorrect types, we will get runtime errors for dynamic Groovy and compile-time errors
-for static Groovy (shown below):
-
-----
-[Static type checking] - unexpected named arg: born
- @ line 11, column 65.
-def dr4 = new DoctorWho(first: 'Tom', last: 'Baker', number: 4, born: 1934)
- ^
-
-[Static type checking] - argument for named param 'number' has type 'java.lang.String' but expected 'java.lang.Integer'.
- @ line 12, column 40.
-def dr6 = dr4.copyWith(first: 'Colin', number: 'six')
- ^
-2 errors
-----
+* Support for JDK 11-25, including:
+** Support for many JDK 17-25 features on earlier JDK versions including JDK11
+* Over 350 new _extension method_ additions and improvements to increase developer productivity and offer greater performance, including:
+** highly performant array operations offering an order of magnitude greater speed
+** stream equivalent lazy iterator methods without stream overheads
+** a range of methods not available in the JDK for greater out-of-the box functionality
+* _AST Transform_ additions and improvements, including:
+** `@OperatorRename` to allow third-party libraries to maximally use Groovy's operator overloading
+without changing the libraries or needing to write glue code
+* New and improved _groovysh_ Repl based on JLine 3 with many features, including:
+** Cross-platform terminal support with rich shell-like commands
+** Colorized syntax highlighting and intelligent output formatting
+** Command history and completion
+* _Java compatibility_ improvements, including:
+** pattern matching for `instanceof`
+* Additional _scripting variations_
+** To support JEP-512 compact source files and instance main methods in addition to Groovy's shorter scripts
+* Improved web content creation
+** Supporting Jakarta as well as legacy Javax standards
+* Type checking improvements, including:
+** "Stronger than Java" type checking for format strings
+* Other improvements like:
+** Infinite iterator generation
+** Index variables in loops
== Extension method additions and improvements
@@ -643,7 +369,7 @@
for subsequent calls. This might sound like a flaw, but it's more like
the case where for Java streams, some custom functionality could be
implemented using either intermediate (Gatherer) or terminal (Collector) operators. +
- +
++
Having said that, a future release of Groovy may improve this
situation. It might provide aliases, like `map` for `collect`,
`filter` for `findAll`, etc. Alternatively, it might provide methods like
@@ -774,6 +500,290 @@
assert BitSet.valueOf(21) == fortyTwo >> 1
----
+== Additional Scripting Variations
+
+https://openjdk.org/jeps/512[JEP 512], targeted for JDK25
+(and previewed in earlier JDKs:
+https://openjdk.org/jeps/445[JEP 445]
+https://openjdk.org/jeps/463[JEP 463]
+https://openjdk.org/jeps/477[JEP 477]
+https://openjdk.org/jeps/495[JEP 495]
+),
+introduces a new `main` method signature and compact source notation for Java classes.
+Groovy 5 supports this new notation, as well as Groovy's traditional scripts,
+and an alternative abbreviated form.
+
+Let's recap the story so far. First, a traditional (Java) class:
+
+[source,java]
+----
+public class HelloWorld { // Java (also Groovy)
+ public static void main(String[] args) {
+ System.out.println("Hello, World!");
+ }
+}
+----
+
+Second, a traditional Groovy script:
+
+[source,groovy]
+----
+println 'Hello, World!'
+----
+
+Groovy scripts are given implicit `main` and `run` methods and an implicit class definition.
+Variable declarations in scripts are local variable declarations in the implicit `run` method
+unless annotated with `@Field`, in which case they become field definitions of the implicit class.
+
+Third, the "instance main" method proposed for JEP 512 in Java with an implicit class definition:
+
+[source,java]
+----
+void main() { // Java JDK25 (also Groovy 5+)
+ IO.println("Hello, World!");
+}
+----
+
+Variants with arguments are also supported as are "static main" methods.
+
+Groovy supports such methods on JDK11+ and supports some slight simplifications:
+
+[source,groovy]
+----
+def main() {
+ println 'Hello, World!'
+}
+----
+
+Finally, Groovy also provides an "instance run" method as an alternative form:
+
+[source,groovy]
+----
+def run() {
+ println 'Hello, World!'
+}
+----
+
+You may wonder why Groovy supports the JEP 512 notation when the traditional Groovy script
+is shorter? Firstly, there is Java compatibility, but also there are scenarios where we might like
+to use method or class annotations, and that is hard to do for an implicit method or an implicit class.
+
+`TYPE` targeted annotations on the `main` or `run` method will be moved to the generated
+script class. `METHOD` targeted annotations remain on the method.
+
+Classes created with an "instance main" method (like above) are JEP 512 compatible
+classes and will need to be invoked from the JDK with JEP 512 capability enabled
+or using the Groovy runner which now supports such classes from JDK11+.
+
+For backwards compatibility, classes created with a static `main` method are
+_promoted_ to have the normal public static void main signature. They can be run
+like normal Java or Groovy classes.
+
+There are variants in Java and Groovy to also have arguments available:
+
+[source,groovy]
+----
+@CompileStatic
+static main(args) {
+ println 'Groovy world!'
+}
+----
+
+JEP 512 compatible classes may also contain other field and method definitions as shown here:
+
+[source,groovy]
+----
+def main() {
+ assert upper(foo) + lower(bar) == 'FOObar'
+}
+
+def upper(s) { s.toUpperCase() }
+
+def lower = String::toLowerCase
+def (foo, bar) = ['Foo', 'Bar']
+----
+
+But they can't contain any other "uncontained" statements, otherwise they
+are treated like a normal Groovy script. Another important distinction for JEP 512
+compatible classes is that fields (like `lower`, `foo`, and `bar` in the above example)
+don't need to be annotated with `@Field`.
+
+An additional form is also supported which involves supplying a `run` method
+instead of a `main` method.
+This provides an alternate form to the earlier shown `main` variants.
+The difference is that rather than producing a JEP 512 compatible class, Groovy
+produces a script class which extends the `Script` class in the normal way and has
+access to the normal script binding and context. The use case is again where you
+might want to supply annotations, e.g.:
+
+[source,groovy]
+----
+@JsonIgnoreProperties(["binding"])
+def run() {
+ var mapper = new ObjectMapper()
+ assert mapper.writeValueAsString(this) == '{"pets":["cat","dog"]}'
+}
+
+public pets = ['cat', 'dog']
+----
+
+To summarise:
+
+* If you need access to the script binding or context, write a traditional class that extends the `Script` class,
+or a traditional Groovy script, or use the `run` method.
+* If you use the supported `main` or `run` method variants, you can have field definitions and other methods,
+and you don't need `@Field`. Consider these if you don't like `@Field` or you want to use annotations on the
+implicit class or the main/run method.
+* If your source file has any statements outside methods that aren't field declarations,
+it will be treated as a traditional Groovy script.
+* Use the "instance main" method variant if you want the generated bytecode to follow JEP 512 conventions.
+You will need JDK25+ to run from Java, or JDK11+ to run from Groovy.
+
+== Improved Web Content Creation
+
+=== Jakarta EE support
+
+The `groovy-servlet` module supports:
+
+* Writing servlets as Groovy scripts (_Groovlets_), e.g.:
++
+[source,groovy]
+----
+html.html {
+ head {
+ title 'My first Groovlet'
+ }
+ body { h1 'Welcome to Groovlets!' }
+}
+----
+* Writing servlets as Groovy classes (typically extending `AbstractHttpServlet`)
+* Writing Template-style, JSP-like _Groovy Server Pages_ which combine (typically) HTML with Groovy control-logic within special tags
+
+Groovy 5 defaults to Jakarta EE versions of the Servlet-related standards.
+This mostly involves using versions of the underlying classes with different
+package names.
+
+When writing Groovlets or GSPs, the change in package name might not be apparent,
+since for simple examples, like the one shown above, the package names don't appear, but the underlying classes being used would change.
+If you are using Groovylets, your transition to Jakarta EE should be a little
+easier.
+
+You can still obtain the older Javax EE versions of the relevant classes using
+the "javax" classifier when specifying your dependency on `groovy-servlet`.
+
+== Improved Type Checking
+
+Groovy's type checking is extensible. This allows you to weaken or strengthen
+type checking. In Groovy 5, we've added a type checker for format strings.
+Errors in such strings are often not detected until runtime, but now you
+can check them at compile time. It adds to the existing regex checking
+capabilities.
+
+=== An Optional Type Checker for Format Strings
+
+The `format` methods in `java.util.Formatter`, and other similar methods,
+support formatted printing in the style of C's `printf` method with a
+format string and zero or more arguments.
+
+Let's consider an example which produces a string comprised of three terms:
+
+* a floating-point representation (`%f`) of PI (with 2 decimal places of precision),
+* the hex representation (`%X`) of 15 (as two uppercase digits with a leading 0),
+* and the Boolean (`%B`) `True` (in uppercase).
+
+The assertion checks our expectations:
+
+[source,groovy]
+----
+assert String.format('%4.2f %02X %B', Math.PI, 15, true) == '3.14 0F TRUE'
+----
+
+This is a powerful method supporting numerous conversions and flags.
+If the developer supplies incorrect conversions or flags,
+they will receive one of numerous possible runtime errors.
+As examples, consider the following mistakes and resulting runtime exceptions:
+
+* supplying a String as the parameter for either of the first two arguments results in an
+`IllegalFormatConversionException`,
+* leaving out the last argument results in a
+`MissingFormatArgumentException`,
+* supplying the _leading zero_ flag for the Boolean parameter results in a
+`FlagsConversionMismatchException`.
+
+The goal of the `FormatStringChecker` is to eliminate
+a large number of such runtime errors. If the API call passes type checking,
+it will be guaranteed to succeed at runtime.
+
+== AST transform additions and improvements
+
+=== Making Operators More Groovy
+
+There is a new `OperatorRename` AST transform.
+This is very useful when using third-party libraries which use different
+names to those used by Groovy's operator overloading functionality.
+For example, using the Apache Commons Numbers Fraction library:
+
+[source,groovy]
+----
+@OperatorRename(plus='add')
+def testAddOfTwoFractions() {
+ var half = Fraction.of(1, 2)
+ var third = Fraction.of(1, 3)
+ assert half.add(third) == Fraction.of(5, 6) // old style still works
+ assert half + third == Fraction.of(5, 6) // fraction '+' operator!
+}
+----
+
+This transform is quite handy when using various matrix packages.
+Such packages often align with Groovy's operator overloading conventions
+for many, but usually not all, operators.
+For instance, you might like to rename:
+
+* `mult` to `multiply` if using Ejml
+* `add` to `plus` if using Commons Math matrices
+* `sub` to `minus` if using Nd4j matrices
+
+Groovy has excellent support for writing Domain Specific Languages (DSLs),
+but using the `@OperatorRename` transform means we can skip constructing our own DSL in simple cases.
+
+=== Additional type safety for generated map constructors and copyWith methods
+
+Groovy provides named parameter support through a convention of using a Map as the first parameter
+for a Groovy or Java method. Such methods annotated with `@NamedParam` allow
+Groovy's static compiler to provide full compile-time type safety including detecting unknown arguments.
+Good IDEs will also provide auto-completion and checking for such methods.
+
+Groovy has a couple of dozen methods annotated in this way and also automatically generates
+such annotations already when using the `@NamedVariant` annotation or for records.
+With Groovy 5, the `@NamedParam` annotation is now also added automatically when using
+`@MapConstructor` (used by `@Immutable` and `@Canonical`) and the `copyWith` option for `@Immutable`.
+
+[source,groovy]
+----
+@Immutable(copyWith = true)
+class DoctorWho {
+ String first, last
+ Integer number
+}
+----
+
+If we try to create a `DoctorWho` object with an unknown parameter, or use the `copyWith` method
+with incorrect types, we will get runtime errors for dynamic Groovy and compile-time errors
+for static Groovy (shown below):
+
+----
+[Static type checking] - unexpected named arg: born
+ @ line 11, column 65.
+def dr4 = new DoctorWho(first: 'Tom', last: 'Baker', number: 4, born: 1934)
+ ^
+
+[Static type checking] - argument for named param 'number' has type 'java.lang.String' but expected 'java.lang.Integer'.
+ @ line 12, column 40.
+def dr6 = dr4.copyWith(first: 'Colin', number: 'six')
+ ^
+2 errors
+----
+
[[Groovy5.0-groovysh]]
== New and improved Groovysh Repl
