Modernize baseline to Java 21, adopt Java 21 features, remove NotCharacterPredicate, and add CHANGELOG

- Bump compiler release to 21 in pom.xml, update GitHub Actions CI matrix to Java 21, and remove legacy Travis CI section.
- Adopt Java 21 switch expressions in Tuple2..Tuple9 and pattern matching for instanceof across tuples, character predicates, and grammar visitors.
- Leverage Sequenced Collections (getFirst, getLast, removeLast) across CharacterPredicate, Analyzer, and GrammarDefinition.
- Remove deprecated NotCharacterPredicate alias and associated test in favor of NotCharPredicate.
- Add CHANGELOG.md covering highlights for 2.5.0 and all previous x.y.0 releases.

Author: renggli

.github/workflows/maven.yml

@@ -19,13 +19,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        java: [ '11', '11.0.3', '14', '14.0.1' ]
-    name: Java ${{ matrix.Java }}
+        java: [ '21' ]
+    name: Java ${{ matrix.java }}
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-java@v5
         with:
           distribution: 'zulu'
-          java-version: ${{ matrix.Java }}
+          java-version: ${{ matrix.java }}
       - name: Build with Maven
         run: mvn -B package --file pom.xml

AGENTS.md

@@ -5,7 +5,7 @@
 - Deliver code, tests, and documentation directly with zero introductory fluff or pleasantries.
 - Strictly adhere to 2 spaces for indentation.
 - Preserve zero external runtime dependencies for `petitparser-core` (rely exclusively on the Java standard library).
-- Target Java 11 bytecode compatibility (`<maven.compiler.release>11</maven.compiler.release>`).
+- Target Java 21 bytecode compatibility (`<maven.compiler.release>21</maven.compiler.release>`).
 
 ---
 
@@ -28,7 +28,7 @@
 
 ### Type System & Generics Guidelines
 
-- **Dual-Nature Tuples**: Java 11 lacks language-level tuples/records. Implement `Tuple2<T1, T2>` through `Tuple9` extending `AbstractList<Object>`.
+- **Dual-Nature Tuples**: Implement `Tuple2<T1, T2>` through `Tuple9` extending `AbstractList<Object>`.
   - Enables strongly-typed accessors (`tuple.first()`, `tuple.second()`, etc.) without losing compatibility with APIs expecting `List<Object>`.
   - Seamlessly passes equality against standard lists (`tuple.equals(Arrays.asList(...)) == true`).
 - **Direct-Mapped Sequences**: Provide fluent `.then()` sequence chaining returning `SequenceParser2` through `SequenceParser9`, offering direct multi-argument mapping (`.map((a, b) -> ...)` via `BiFunction`, `Function3`, etc.) so users rarely need to inspect the underlying `Tuple`.

CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 2.5.0
+
+- Upgraded baseline to Java 21 LTS (`<maven.compiler.release>21</maven.compiler.release>`) and modernized GitHub Actions CI.
+- Added fluent `.then(...)` sequence chaining with strongly-typed `SequenceParser2` through `SequenceParser9`.
+- Added multi-arity `.map(...)` callbacks (`BiFunction`, `Function3` through `Function9`) for type-safe sequence unpacking.
+- Introduced dual-nature tuples (`Tuple2` through `Tuple9`) extending `AbstractList<Object>` with typed accessors and standard list compatibility.
+- Added type-safe grammar productions with `Production<T>` keys and `GrammarParser` typed lookup.
+- Modernized `ExpressionBuilder<T>` with full generic typing, builder-level primitive helpers, loopback access, optional operator groups, `foldLeft`/`foldRight`, and typed action callbacks.
+- Added zero-list repeating character parsers (`starString()`, `plusString()`, `timesString()`, `repeatString()`) with SIMD string matching.
+- Added full Unicode code point and surrogate pair parsing with `UnicodeCharacterParser`.
+- Added `CharacterPredicate` AST hierarchy with range merging and automatic lookup table optimization.
+- Added indentation-sensitive parsing engine (`Indent`) for indentation-aware grammars (`Indent.during`, `equal`, `greater`, etc.).
+- Added grammar `Analyzer` for computing reachability, cycles, nullability, FIRST sets, and FOLLOW sets.
+- Added grammar `Linter` with 13 automated rules detecting anti-patterns.
+- Added grammar `Optimizer` rule engine with choice flattening, character repeater rewriting, and delegate removal.
+- Added `Progress` visual execution debugger and `ProgressFrame` for inspecting parser backtracking and execution graphs.
+- Added lazy stream matching (`matchesAsStream()`) and offset-based searching on `Parser`.
+- Added zero-allocation fast parse (`fastParseOn`) across all parsers.
+- Added `skip(...)` and delimiter combinators, `where(...)` filtering combinator, `label(...)` parser, and `position()` / `newline()` primitives.
+- Comprehensive documentation rewrite and examples modernization in `README.md` and `ExamplesTest.java`.
+- Near 100% test coverage across all reactor modules.
+
+## 2.4.0
+
+- Added Java Platform Module System (JPMS) support with `module-info.java`.
+- Added configurable failure join strategy on `ChoiceParser` (`FailureJoiner`).
+- Improved character parser failure messages and XML grammar performance.
+- Migrated continuous integration pipelines to GitHub Actions.
+
+## 2.3.0
+
+- Introduced zero-allocation fast parse mode (`fastParseOn`).
+- Added parenthesis expression support to `ExpressionBuilder`.
+- Optimized XML and JSON grammars to take advantage of fast parsing.
+- Improved Java 11 (LTS) compatibility.
+
+## 2.2.0
+
+- Preserved parser generic types during `copy()`.
+- Cleaned up build configuration for Maven Central publication.
+- Code cleanups, static analysis fixes, and dependency upgrades.
+
+## 2.1.0
+
+- Introduced `GrammarDefinition` and `GrammarParser` following the Dart architecture.
+- Migrated XML and Smalltalk example grammars to grammar definitions.
+- Modernized internal collections, replacing legacy synchronized classes.
+
+## 2.0.0
+
+- Major rewrite modernizing PetitParser for Java 8+ with lambda expressions.
+- Package structure reorganization into `context`, `actions`, `combinators`, `primitive`, and `repeating`.
+- Rebuilt character predicate hierarchy with optimized range checks and bitmask lookups.
+- Added expression builder and composite grammar tools.

TASKS.md

@@ -1,6 +1,6 @@
 # PetitParser Java Parity Tasks
 
-Roadmap to bring `petitparser-core` to feature parity with the canonical Dart implementation while maintaining strict backward compatibility with existing code and adopting modern Java best practices (Java 11 baseline, standard functional interfaces, and stream idioms).
+Roadmap to bring `petitparser-core` to feature parity with the canonical Dart implementation while maintaining strict backward compatibility with existing code and adopting modern Java best practices (Java 21 baseline, standard functional interfaces, and stream idioms).
 
 ---
 
@@ -135,7 +135,7 @@ Roadmap to bring `petitparser-core` to feature parity with the canonical Dart im
 - [x] **Task 3.2: Multi-Arity Functional Interfaces**
   - Create standard functional interfaces in `org.petitparser.utils.functions`:
     - `Function3<T1, T2, T3, R>`, `Function4<T1, T2, T3, T4, R>`, ... `Function9<...>`.
-  - Ensure compatibility with Java 11 `BiFunction` for arity-2 sequences.
+  - Ensure compatibility with Java `BiFunction` for arity-2 sequences.
 
 - [x] **Task 3.3: Typed Sequence Combinators (`SequenceParser2` to `SequenceParser9`)**
   - Implement `SequenceParser2<T1, T2>` through `SequenceParser9<...>` implementing `SequentialParser`.

petitparser-core/src/main/java/org/petitparser/parser/Parser.java

@@ -883,9 +883,8 @@ public <A, B> Parser map(Function<A, B> function) {
   public <T1, T2, R> Parser map(BiFunction<? super T1, ? super T2, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple2) {
-        Tuple2<T1, T2> tuple = (Tuple2<T1, T2>) input;
-        return function.apply(tuple.first(), tuple.second());
+      if (input instanceof Tuple2<?, ?> tuple) {
+        return function.apply((T1) tuple.first(), (T2) tuple.second());
       }
       List<?> list = (List<?>) input;
       return function.apply((T1) list.get(0), (T2) list.get(1));
@@ -899,9 +898,9 @@ public <T1, T2, R> Parser map(BiFunction<? super T1, ? super T2, ? extends R> fu
   public <T1, T2, T3, R> Parser map(Function3<? super T1, ? super T2, ? super T3, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple3) {
-        Tuple3<T1, T2, T3> tuple = (Tuple3<T1, T2, T3>) input;
-        return function.apply(tuple.first(), tuple.second(), tuple.third());
+      if (input instanceof Tuple3<?, ?, ?> tuple) {
+        return function.apply(
+            (T1) tuple.first(), (T2) tuple.second(), (T3) tuple.third());
       }
       List<?> list = (List<?>) input;
       return function.apply((T1) list.get(0), (T2) list.get(1), (T3) list.get(2));
@@ -916,9 +915,9 @@ public <T1, T2, T3, T4, R> Parser map(
       Function4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple4) {
-        Tuple4<T1, T2, T3, T4> tuple = (Tuple4<T1, T2, T3, T4>) input;
-        return function.apply(tuple.first(), tuple.second(), tuple.third(), tuple.fourth());
+      if (input instanceof Tuple4<?, ?, ?, ?> tuple) {
+        return function.apply(
+            (T1) tuple.first(), (T2) tuple.second(), (T3) tuple.third(), (T4) tuple.fourth());
       }
       List<?> list = (List<?>) input;
       return function.apply((T1) list.get(0), (T2) list.get(1), (T3) list.get(2), (T4) list.get(3));
@@ -933,10 +932,10 @@ public <T1, T2, T3, T4, T5, R> Parser map(
       Function5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple5) {
-        Tuple5<T1, T2, T3, T4, T5> tuple = (Tuple5<T1, T2, T3, T4, T5>) input;
+      if (input instanceof Tuple5<?, ?, ?, ?, ?> tuple) {
         return function.apply(
-            tuple.first(), tuple.second(), tuple.third(), tuple.fourth(), tuple.fifth());
+            (T1) tuple.first(), (T2) tuple.second(), (T3) tuple.third(), (T4) tuple.fourth(),
+            (T5) tuple.fifth());
       }
       List<?> list = (List<?>) input;
       return function.apply(
@@ -953,11 +952,10 @@ public <T1, T2, T3, T4, T5, T6, R> Parser map(
       Function6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple6) {
-        Tuple6<T1, T2, T3, T4, T5, T6> tuple = (Tuple6<T1, T2, T3, T4, T5, T6>) input;
+      if (input instanceof Tuple6<?, ?, ?, ?, ?, ?> tuple) {
         return function.apply(
-            tuple.first(), tuple.second(), tuple.third(), tuple.fourth(), tuple.fifth(),
-            tuple.sixth());
+            (T1) tuple.first(), (T2) tuple.second(), (T3) tuple.third(), (T4) tuple.fourth(),
+            (T5) tuple.fifth(), (T6) tuple.sixth());
       }
       List<?> list = (List<?>) input;
       return function.apply(
@@ -974,11 +972,10 @@ public <T1, T2, T3, T4, T5, T6, T7, R> Parser map(
       Function7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple7) {
-        Tuple7<T1, T2, T3, T4, T5, T6, T7> tuple = (Tuple7<T1, T2, T3, T4, T5, T6, T7>) input;
+      if (input instanceof Tuple7<?, ?, ?, ?, ?, ?, ?> tuple) {
         return function.apply(
-            tuple.first(), tuple.second(), tuple.third(), tuple.fourth(), tuple.fifth(),
-            tuple.sixth(), tuple.seventh());
+            (T1) tuple.first(), (T2) tuple.second(), (T3) tuple.third(), (T4) tuple.fourth(),
+            (T5) tuple.fifth(), (T6) tuple.sixth(), (T7) tuple.seventh());
       }
       List<?> list = (List<?>) input;
       return function.apply(
@@ -995,11 +992,10 @@ public <T1, T2, T3, T4, T5, T6, T7, T8, R> Parser map(
       Function8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple8) {
-        Tuple8<T1, T2, T3, T4, T5, T6, T7, T8> tuple = (Tuple8<T1, T2, T3, T4, T5, T6, T7, T8>) input;
+      if (input instanceof Tuple8<?, ?, ?, ?, ?, ?, ?, ?> tuple) {
         return function.apply(
-            tuple.first(), tuple.second(), tuple.third(), tuple.fourth(), tuple.fifth(),
-            tuple.sixth(), tuple.seventh(), tuple.eighth());
+            (T1) tuple.first(), (T2) tuple.second(), (T3) tuple.third(), (T4) tuple.fourth(),
+            (T5) tuple.fifth(), (T6) tuple.sixth(), (T7) tuple.seventh(), (T8) tuple.eighth());
       }
       List<?> list = (List<?>) input;
       return function.apply(
@@ -1016,12 +1012,11 @@ public <T1, T2, T3, T4, T5, T6, T7, T8, T9, R> Parser map(
       Function9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> function) {
     Objects.requireNonNull(function, "Undefined map function");
     return map(input -> {
-      if (input instanceof Tuple9) {
-        Tuple9<T1, T2, T3, T4, T5, T6, T7, T8, T9> tuple =
-            (Tuple9<T1, T2, T3, T4, T5, T6, T7, T8, T9>) input;
+      if (input instanceof Tuple9<?, ?, ?, ?, ?, ?, ?, ?, ?> tuple) {
         return function.apply(
-            tuple.first(), tuple.second(), tuple.third(), tuple.fourth(), tuple.fifth(),
-            tuple.sixth(), tuple.seventh(), tuple.eighth(), tuple.ninth());
+            (T1) tuple.first(), (T2) tuple.second(), (T3) tuple.third(), (T4) tuple.fourth(),
+            (T5) tuple.fifth(), (T6) tuple.sixth(), (T7) tuple.seventh(), (T8) tuple.eighth(),
+            (T9) tuple.ninth());
       }
       List<?> list = (List<?>) input;
       return function.apply(

petitparser-core/src/main/java/org/petitparser/parser/actions/PermuteParser.java

@@ -4,8 +4,6 @@
 import org.petitparser.context.Result;
 import org.petitparser.parser.Parser;
 import org.petitparser.parser.combinators.DelegateParser;
-import org.petitparser.utils.tuples.Tuple;
-
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;

petitparser-core/src/main/java/org/petitparser/parser/primitive/CharacterPredicate.java

@@ -202,7 +202,7 @@ static CharacterPredicate optimizedRanges(
       if (mergedRanges.isEmpty()) {
         mergedRanges.add(thisRange);
       } else {
-        RangeCharPredicate lastRange = mergedRanges.get(mergedRanges.size() - 1);
+        RangeCharPredicate lastRange = mergedRanges.getLast();
         if ((long) lastRange.getStop() + 1 >= thisRange.getStart()) {
           RangeCharPredicate merged = new RangeCharPredicate(
               lastRange.getStart(),
@@ -218,7 +218,7 @@ static CharacterPredicate optimizedRanges(
     if (mergedRanges.isEmpty()) {
       return ConstantCharPredicate.none();
     } else if (mergedRanges.size() == 1) {
-      RangeCharPredicate range = mergedRanges.get(0);
+      RangeCharPredicate range = mergedRanges.getFirst();
       if (range.getStart() <= 0 &&
           range.getStop() >= (unicode ? 0x10ffff : 0xffff)) {
         return ConstantCharPredicate.any();
@@ -228,8 +228,8 @@ static CharacterPredicate optimizedRanges(
         return range;
       }
     } else {
-      int lookupBytes = (mergedRanges.get(mergedRanges.size() - 1).getStop()
-          - mergedRanges.get(0).getStart() + 32) >> 3;
+      int lookupBytes = (mergedRanges.getLast().getStop()
+          - mergedRanges.getFirst().getStart() + 32) >> 3;
       int rangesBytes = mergedRanges.size() * 8;
       if (lookupBytes > 1024 && rangesBytes < (lookupBytes >> 3)) {
         return RangesCharPredicate.fromRanges(mergedRanges);
@@ -282,17 +282,4 @@ default CharacterPredicate not() {
   default boolean isEqualTo(CharacterPredicate other) {
     return equals(other);
   }
-
-  /**
-   * Backward compatibility alias for {@link NotCharPredicate}.
-   *
-   * @deprecated Use {@link NotCharPredicate} or {@link CharacterPredicate#not()} instead.
-   */
-  @Deprecated(since = "2.5.0")
-  class NotCharacterPredicate extends NotCharPredicate {
-    @Deprecated(since = "2.5.0")
-    public NotCharacterPredicate(CharacterPredicate predicate) {
-      super(predicate);
-    }
-  }
 }

petitparser-core/src/main/java/org/petitparser/parser/primitive/LookupCharPredicate.java

@@ -77,16 +77,16 @@ public boolean test(int value) {
 
   @Override
   public boolean isEqualTo(CharacterPredicate other) {
-    return other instanceof LookupCharPredicate &&
-        start == ((LookupCharPredicate) other).start &&
-        stop == ((LookupCharPredicate) other).stop &&
-        Arrays.equals(bits, ((LookupCharPredicate) other).bits);
+    return other instanceof LookupCharPredicate that &&
+        start == that.start &&
+        stop == that.stop &&
+        Arrays.equals(bits, that.bits);
   }
 
   @Override
   public boolean equals(Object other) {
-    return other instanceof CharacterPredicate &&
-        isEqualTo((CharacterPredicate) other);
+    return other instanceof CharacterPredicate that &&
+        isEqualTo(that);
   }
 
   @Override

petitparser-core/src/main/java/org/petitparser/parser/primitive/NotCharPredicate.java

@@ -34,14 +34,14 @@ public CharacterPredicate not() {
 
   @Override
   public boolean isEqualTo(CharacterPredicate other) {
-    return other instanceof NotCharPredicate &&
-        predicate.isEqualTo(((NotCharPredicate) other).predicate);
+    return other instanceof NotCharPredicate that &&
+        predicate.isEqualTo(that.predicate);
   }
 
   @Override
   public boolean equals(Object other) {
-    return other instanceof CharacterPredicate &&
-        isEqualTo((CharacterPredicate) other);
+    return other instanceof CharacterPredicate that &&
+        isEqualTo(that);
   }
 
   @Override

petitparser-core/src/main/java/org/petitparser/parser/primitive/RangeCharPredicate.java

@@ -51,15 +51,14 @@ public boolean test(int value) {
 
   @Override
   public boolean isEqualTo(CharacterPredicate other) {
-    return other instanceof RangeCharPredicate &&
-        start == ((RangeCharPredicate) other).start &&
-        stop == ((RangeCharPredicate) other).stop;
+    return other instanceof RangeCharPredicate that &&
+        start == that.start &&
+        stop == that.stop;
   }
 
   @Override
   public boolean equals(Object other) {
-    return other instanceof CharacterPredicate &&
-        isEqualTo((CharacterPredicate) other);
+    return other instanceof CharacterPredicate that && isEqualTo(that);
   }
 
   @Override