[java] Fix for #4583: update readme's. (#4588)

* Fix for #4583.

Addresses other documentation issues for the Java grammars, e.g., metntioned in #4530.

* Update readme.md

* Update java/java/README.md.

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update readme.md

* Update README.md

* Update readme, update Trash toolkit to 0.23.26.

The readme now references trunfoldlit, consequently we should just update to the latest toolkit.

* Update README.md

Author: kaby76

.config/dotnet-tools.json

@@ -3,186 +3,193 @@
   "isRoot": true,
   "tools": {
     "trcaret": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trcaret"
       ],
       "rollForward": false
     },
     "trcover": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trcover"
       ],
       "rollForward": false
     },
     "trgen": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trgen"
       ],
       "rollForward": false
     },
     "trglob": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trglob"
       ],
       "rollForward": false
     },
     "triconv": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "triconv"
       ],
       "rollForward": false
     },
     "trparse": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trparse"
       ],
       "rollForward": false
     },
     "trquery": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trquery"
       ],
       "rollForward": false
     },
     "trtext": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trtext"
       ],
       "rollForward": false
     },
     "trwdog": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trwdog"
       ],
       "rollForward": false
     },
     "trxgrep": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trxgrep"
       ],
       "rollForward": false
     },
     "trxml": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trxml"
       ],
       "rollForward": false
     },
     "trxml2": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trxml2"
       ],
       "rollForward": false
     },
     "trclonereplace": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trclonereplace"
       ],
       "rollForward": false
     },
     "trcombine": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trcombine"
       ],
       "rollForward": false
     },
     "trconvert": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trconvert"
       ],
       "rollForward": false
     },
     "trfoldlit": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trfoldlit"
       ],
       "rollForward": false
     },
     "tritext": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "tritext"
       ],
       "rollForward": false
     },
     "trjson": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trjson"
       ],
       "rollForward": false
     },
     "trperf": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trperf"
       ],
       "rollForward": false
     },
     "trrename": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trrename"
       ],
       "rollForward": false
     },
     "trsort": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trsort"
       ],
       "rollForward": false
     },
     "trsplit": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trsplit"
       ],
       "rollForward": false
     },
     "trsponge": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trsponge"
       ],
       "rollForward": false
     },
     "trtokens": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trtokens"
       ],
       "rollForward": false
     },
     "trtree": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trtree"
       ],
       "rollForward": false
     },
     "trunfold": {
-      "version": "0.23.24",
+      "version": "0.23.26",
       "commands": [
         "trunfold"
       ],
       "rollForward": false
+    },
+    "trunfoldlit": {
+      "version": "0.23.26",
+      "commands": [
+        "trunfoldlit"
+      ],
+      "rollForward": false
     }
   }
 }

java/java/README.md

@@ -1,96 +1,68 @@
-# Java Antlr Grammar
+# The optimized Java grammar
 
-Based on the previous optimized [Java7](../java) grammar by Terence Parr and Sam Harwell
-with the same BSD license. This grammar does not exactly corresponds to the formal
-Java specification unlike usual [Java8](../java8) grammar, but passes tests such as
-[AllInOne7.Java](examples/AllInOne7.java) and [AllInOne8.java](examples/AllInOne8.java).
-Performance, practical usage and clarity in priority.
+This grammar, based on the optimized Java7 grammar by Terence Parr and Sam Harwell,
+is meant to parse the latest for the Java language, and is optimized for
+performance, practical usage, and clarity.
+
+It does not correspond
+exactly to the [Java Language Specification](https://docs.oracle.com/javase/specs/).
+The [java8](../java8), [java9](../java9), and [java20](../java20) grammars
+follow the JLS, but are slower that this grammar due to ambiguity and max-k problems
+in the published JLS EBNF.
 
 This grammar parses the file [ManyStringsConcat.java](examples/ManyStringsConcat.java)
-much more faster than original grammar without left recursion expressions.
+faster than the unoptimized java grammars. It implements operator precedence
+using Antlr4-style alt ordering instead of operator-precedence rules. Thus, it avoids
+creating parse trees with long, single-child chains for each string literal constant in
+[ManyStringsConcat.java](examples/ManyStringsConcat.java). In addition, it is faster
+because it avoids the large ATN-config set construction in the
+`AdaptivePredict()` parsing engine.
 
-## Supported Java versions
+[Java Enhancement Proposals (JEP)](https://openjdk.org/jeps/0)
+are not implemented in this grammar.
 
-* Java 7
-* Java 8
-* Java 11
-* Java 17
+## Currently supported Java version
+* Java 24 (latest)
 
 ## Main contributors
-
 * Terence Parr, 2013
 * Sam Harwell, 2013
 * Ivan Kochurkin ([Positive Technologies](https://github.com/PositiveTechnologies)), 2017
 * Michał Lorek, 2021
 
 ## Tests
-
-The grammar contains [AllInOne7.java](examples/AllInOne7.java) and
-[AllInOne8.java](examples/AllInOne8.java) files that almost fully covered Java syntax.
+* See examples/
+* OpenJDK 24, `src/**/*.java` (using [Trash trgen to create app](https://github.com/kaby76/Trash/tree/main/src/trgen), then `find ~/jdk-jdk-23-ga/src/ -name '*.java' | cygpath -w -f - | ./Test -x`)
 
 ## Benchmarks
-
-Grammar performance has been tested on the following projects:
-
-* jdk8
+Grammar performance has been tested on the following Java projects:
+* [OpenJDK 24](https://github.com/openjdk/jdk/archive/refs/tags/jdk-24-ga.zip)
 * Spring Framework
 * Elasticsearch
 * RxJava
 * JUnit4
 * Guava
 * Log4j
 
-See [Benchmarks](Benchmarks.md) page for details.
+See the [benchmarks](Benchmarks.md) page for details.
 
 ## Grammar style
-
-### Parse rules
-
-```ANTLR
-parserRule
-    : token1 (token2* OPERATOR token3?)
-    ;
-```
-
-### Tokens
-
-```ANTLR
-INT:                'int';
-INTERFACE:          'interface';
-```
-
-### Fragments
-
-```ANTLR
-fragment
-HexDigit
-    : [0-9a-fA-F]
-    ;
-```
-
-### Tokens using
-
-Please use token names instead of literal names if possible and justified.
-It's more convenient during parse tree bypass.
-
-```ANTLR
-modifier
-    : classOrInterfaceModifier
-    | NATIVE
-    | SYNCHRONIZED
-    | TRANSIENT
-    | VOLATILE
-    ;
-```
-
-instead of
-
-```ANTLR
-modifier
-    : classOrInterfaceModifier
-    | 'native'
-    | 'synchronized'
-    | 'transient'
-    | 'volatile'
-    ;
-```
+Please use [antlr-format](https://github.com/antlr-ng/antlr-format) and
+[formatting style config](https://github.com/antlr/grammars-v4/blob/master/_scripts/repo_coding_style.json)
+to reformat in the [coding standard format for the repo](https://github.com/antlr/grammars-v4/wiki#is-there-a-coding-standard-for-antlr4-grammars).
+
+### String literals
+Generally, you can use either a string literal or the corresponding lexer rule name
+(`TOKEN_REF`) directly in a parser rule for a token. It makes no difference because the
+[java/java/ grammar](https://github.com/antlr/grammars-v4/tree/master/java/java)
+is a split Antlr4 grammar, and the Antlr Tool prevents you from defining a token using
+a string literal in a parser rule (it outputs
+`cannot create implicit token for string literal in non-combined grammar` if you try).
+When writing an Antlr listener or visitor, use the corresponding lexer rule name for the
+string literal used in the parser rule.
+
+Currently, the grammar contains a mixture of string literals
+and lexer rule names in parser rules. If you want a parser grammar that removes all string literals
+from parser rules, use [Trash trfoldlit](https://github.com/kaby76/Trash/tree/main/src/trfoldlit).
+If you want a parser grammar that uses string literals where a lexer rule exists for the string
+literal, use [Trash trunfoldlit](https://github.com/kaby76/Trash/tree/main/src/trunfoldlit).