Issue #129 Tighten JsonPath docs and fix reverse slices

Author: simbo1905

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
                       for k in totals: totals[k]+=int(r.get(k,'0'))
                   except Exception:
                       pass
-          exp_tests=610
+          exp_tests=611
           exp_skipped=0
           if totals['tests']!=exp_tests or totals['skipped']!=exp_skipped:
               print(f"Unexpected test totals: {totals} != expected tests={exp_tests}, skipped={exp_skipped}")

json-java21-jsonpath/AGENTS.md

@@ -1,77 +1,17 @@
-# json-java21-jsonpath Module AGENTS.md
+# json-java21-jsonpath/AGENTS.md
 
-## Purpose
-This module implements a JsonPath query engine for the java.util.json Java 21 backport. It parses JsonPath expressions into an AST and evaluates them against JSON documents.
+This file is for contributor/agent operational notes. Read `json-java21-jsonpath/README.md` for purpose, supported syntax, and user-facing examples.
 
-## Specification
-Based on Stefan Goessner's JSONPath specification:
-https://goessner.net/articles/JsonPath/
+- User docs MUST recommend only `./mvnw`.
+- The `$(command -v mvnd || command -v mvn || command -v ./mvnw)` wrapper is for local developer speed only; do not put it in user-facing docs.
 
-## Module Structure
+Stable code entry points:
+- `json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPath.java`
+- `json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathParser.java`
+- `json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathAst.java`
+- `json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathParseException.java`
+- `json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathStreams.java`
 
-### Main Classes
-- `JsonPath`: Public API facade with `query()` method
-- `JsonPathAst`: Sealed interface hierarchy defining the AST
-- `JsonPathParser`: Recursive descent parser
-- `JsonPathParseException`: Parse error exception
-
-### Test Classes
-- `JsonPathLoggingConfig`: JUL test configuration base class
-- `JsonPathAstTest`: Unit tests for AST records
-- `JsonPathParserTest`: Unit tests for parser
-- `JsonPathGoessnerTest`: Integration tests based on Goessner article examples
-
-## Development Guidelines
-
-### Adding New Operators
-1. Add new record type to `JsonPathAst.Segment` sealed interface
-2. Update `JsonPathParser` to parse the new syntax
-3. Add parser tests in `JsonPathParserTest`
-4. Implement evaluation in `JsonPath.evaluateSegments()`
-5. Add integration tests in `JsonPathGoessnerTest`
-
-### Testing
-```bash
-# Run all tests
-$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Djava.util.logging.ConsoleHandler.level=INFO
-
-# Run specific test class with debug logging
-$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Dtest=JsonPathGoessnerTest -Djava.util.logging.ConsoleHandler.level=FINE
-
-# Run single test method
-$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Dtest=JsonPathGoessnerTest#testAuthorsOfAllBooks -Djava.util.logging.ConsoleHandler.level=FINEST
-```
-
-## Design Principles
-
-1. **No external dependencies**: Only java.base is allowed
-2. **Pure TDD**: Tests first, then implementation
-3. **Functional style**: Immutable records, pure evaluation functions
-4. **Java 21 features**: Records, sealed interfaces, pattern matching with switch
-5. **Defensive copies**: All collections in records are copied for immutability
-
-## Known Limitations
-
-1. **Script expressions**: Only `@.length-1` pattern is supported
-2. **No general expression evaluation**: Complex scripts are not supported
-3. **Stack-based recursion**: May overflow on very deep documents
-
-## API Usage
-
-```java
-import jdk.sandbox.java.util.json.*;
-import json.java21.jsonpath.JsonPath;
-
-JsonValue json = Json.parse(jsonString);
-
-// Preferred: parse once (cache) and reuse
-JsonPath path = JsonPath.parse("$.store.book[*].author");
-List<JsonValue> results = path.query(json);
-
-// If you want a static call site, pass the compiled JsonPath
-List<JsonValue> sameResults = JsonPath.query(path, json);
-```
-
-Notes:
-- Parsing a JsonPath expression is relatively expensive compared to evaluation; cache compiled `JsonPath` instances in hot code paths.
-- `JsonPath.query(String, JsonValue)` is intended for one-off usage only.
+When changing syntax/behavior:
+- Update `JsonPathAst` + `JsonPathParser` + `JsonPath` together.
+- Add parser + evaluation tests; new tests should extend `JsonPathLoggingConfig`.

json-java21-jsonpath/README.md

@@ -5,28 +5,47 @@ This module provides a JSONPath-style query engine for JSON documents parsed wit
 It is based on the original Stefan Goessner JSONPath article:
 https://goessner.net/articles/JsonPath/
 
-## Usage
-
-Parse JSON once with `Json.parse(...)`, compile the JsonPath once with `JsonPath.parse(...)`, then query multiple documents:
+## Quick Start
 
 ```java
 import jdk.sandbox.java.util.json.*;
 import json.java21.jsonpath.JsonPath;
 
 JsonValue doc = Json.parse("""
-  {"store": {"book": [{"author": "A"}, {"author": "B"}]}}
+  {"store": {"book": [{"title": "A", "price": 8.95}, {"title": "B", "price": 12.99}]}}
   """);
 
-JsonPath path = JsonPath.parse("$.store.book[*].author");
-var authors = path.query(doc);
-
-// If you want a static call site:
-var sameAuthors = JsonPath.query(path, doc);
+var titles = JsonPath.parse("$.store.book[*].title").query(doc);
+var cheap = JsonPath.parse("$.store.book[?(@.price < 10)].title").query(doc);
 ```
 
-Notes:
-- Prefer `JsonPath.parse(String)` + `query(JsonValue)` to avoid repeatedly parsing the same path.
-- `JsonPath.query(String, JsonValue)` is intended for one-off usage.
+## Syntax At A Glance
+
+Operator | Example | What it selects
+---|---|---
+root | `$` | the whole document
+property | `$.store.book` | a nested object property
+bracket property | `$['store']['book']` | same as dot notation, but allows escaping
+wildcard | `$.store.*` | all direct children
+recursive descent | `$..price` | any matching member anywhere under the document
+array index | `$.store.book[0]` / `[-1]` | element by index (negative from end)
+slice | `$.store.book[:2]` / `[0:4:2]` / `[::-1]` | slice by start:end:step
+union | `$.store['book','bicycle']` / `[0,1]` | select multiple names/indices
+filter exists | `$.store.book[?(@.isbn)]` | elements where a member exists
+filter compare | `$.store.book[?(@.price < 10)]` | elements matching a comparison
+filter logic | `$.store.book[?(@.isbn && (@.price < 10 || @.price > 20))]` | compound boolean logic
+script (limited) | `$.store.book[(@.length-1)]` | last element via `length-1`
+
+## Examples
+
+Expression | What it selects
+---|---
+`$.store.book[*].title` | all book titles
+`$.store.book[?(@.price < 10)].title` | titles of books cheaper than 10
+`$.store.book[?(@.isbn && (@.price < 10 || @.price > 20))].title` | books with an ISBN and price outside the mid-range
+`$..price` | every `price` anywhere under the document
+`$.store.book[-1]` | the last book
+`$.store.book[0:4:2]` | every other book from the first four
 
 ## Supported Syntax
 
@@ -43,7 +62,7 @@ This implementation follows Goessner-style JSONPath operators, including:
 
 ## Stream-Based Functions (Aggregations)
 
-Some JsonPath implementations for older versions of Java provided aggregation functions such as `$.numbers.avg()`.
+Some JsonPath implementations include aggregation functions such as `$.numbers.avg()`.
 In this implementation we provide first class stream support so you can use standard JDK aggregation functions on `JsonPath.query(...)` results.
 
 The `query()` method returns a standard `List<JsonValue>`. You can stream, filter, map, and reduce these results using standard Java APIs. To make this easier, we provide the `JsonPathStreams` utility class with predicate and conversion methods.

json-java21-jsonpath/pom.xml

@@ -64,7 +64,6 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.11.0</version>
                 <configuration>
                     <release>21</release>
                     <compilerArgs>

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPath.java

@@ -12,7 +12,7 @@
 ///
 /// Usage examples:
 /// ```java
-/// // Fluent API (preferred)
+/// // Fluent API
 /// JsonValue json = Json.parse(jsonString);
 /// List<JsonValue> results = JsonPath.parse("$.store.book[*].author").query(json);
 ///
@@ -46,8 +46,8 @@ public static JsonPath parse(String path) {
 
     /// Queries matching values from a JSON document.
     ///
-    /// This is the preferred instance API: compile once via `parse(String)`, then call `query(JsonValue)`
-    /// for each already-parsed JSON document.
+    /// Instance API: compile once via `parse(String)`, then call `query(JsonValue)` for each already-parsed
+    /// JSON document.
     ///
     /// @param json the JSON document to query
     /// @return a list of matching JsonValue instances (maybe empty)
@@ -74,6 +74,21 @@ public static List<JsonValue> query(JsonPath path, JsonValue json) {
         return path.query(json);
     }
 
+    /// Evaluates a JsonPath expression against a JSON document.
+    ///
+    /// Intended for one-off usage; for hot paths, prefer caching the compiled `JsonPath` via `parse(String)`.
+    ///
+    /// @param path the JsonPath expression to parse
+    /// @param json the JSON document to query
+    /// @return a list of matching JsonValue instances (maybe empty)
+    /// @throws NullPointerException if path or JSON is null
+    /// @throws JsonPathParseException if the path is invalid
+    public static List<JsonValue> query(String path, JsonValue json) {
+        Objects.requireNonNull(path, "path must not be null");
+        Objects.requireNonNull(json, "json must not be null");
+        return parse(path).query(json);
+    }
+
     /// Evaluates a pre-parsed JsonPath AST against a JSON document.
     /// @param ast the parsed JsonPath AST
     /// @param json the JSON document to query
@@ -166,24 +181,28 @@ private static void evaluateArraySlice(
             final var elements = array.elements();
             final int size = elements.size();
 
-            // Resolve start, end, step with defaults
-            int start = slice.start() != null ? normalizeIndex(slice.start(), size) : 0;
-            int end = slice.end() != null ? normalizeIndex(slice.end(), size) : size;
-            int step = slice.step() != null ? slice.step() : 1;
+            final int step = slice.step() != null ? slice.step() : 1;
 
             if (step == 0) {
                 return; // Invalid step
             }
 
-            // Clamp values
-            start = Math.max(0, Math.min(start, size));
-            end = Math.max(0, Math.min(end, size));
-
             if (step > 0) {
+                int start = slice.start() != null ? normalizeIndex(slice.start(), size) : 0;
+                int end = slice.end() != null ? normalizeIndex(slice.end(), size) : size;
+
+                start = Math.max(0, Math.min(start, size));
+                end = Math.max(0, Math.min(end, size));
+
                 for (int i = start; i < end; i += step) {
                     evaluateSegments(segments, index + 1, elements.get(i), root, results);
                 }
             } else {
+                int start = slice.start() != null ? normalizeIndex(slice.start(), size) : size - 1;
+                final int end = slice.end() != null ? normalizeIndex(slice.end(), size) : -1;
+
+                start = Math.max(0, Math.min(start, size - 1));
+
                 for (int i = start; i > end; i += step) {
                     evaluateSegments(segments, index + 1, elements.get(i), root, results);
                 }

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathParser.java

@@ -524,6 +524,8 @@ private JsonPathAst.Segment parseNumberOrSliceOrUnion() {
             // After initial ':', check if there's a number for end
             if (pos < path.length() && (Character.isDigit(path.charAt(pos)) || path.charAt(pos) == '-')) {
                 elements.add(parseInteger());
+            } else {
+                elements.add(null);
             }
         } else {
             elements.add(parseInteger());

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathStreams.java

@@ -2,54 +2,35 @@
 
 import jdk.sandbox.java.util.json.*;
 
-/// Utility class for stream-based processing of JsonPath query results.
-///
-/// This module intentionally does not embed aggregate functions (avg/sum/min/max)
-/// in JsonPath syntax; use Java Streams on `JsonPath.query(...)` results instead.
+/// Helpers for stream-based processing of `JsonPath.query(...)` results.
 public final class JsonPathStreams {
 
     private JsonPathStreams() {}
 
-    // =================================================================================
-    // Predicates
-    // =================================================================================
-
-    /// @return true if the value is a `JsonNumber`
     public static boolean isNumber(JsonValue v) {
         return v instanceof JsonNumber;
     }
 
-    /// @return true if the value is a `JsonString`
     public static boolean isString(JsonValue v) {
         return v instanceof JsonString;
     }
 
-    /// @return true if the value is a `JsonBoolean`
     public static boolean isBoolean(JsonValue v) {
         return v instanceof JsonBoolean;
     }
 
-    /// @return true if the value is a `JsonArray`
     public static boolean isArray(JsonValue v) {
         return v instanceof JsonArray;
     }
 
-    /// @return true if the value is a `JsonObject`
     public static boolean isObject(JsonValue v) {
         return v instanceof JsonObject;
     }
 
-    /// @return true if the value is a `JsonNull`
     public static boolean isNull(JsonValue v) {
         return v instanceof JsonNull;
     }
 
-    // =================================================================================
-    // Strict Converters (throw ClassCastException if type mismatch)
-    // =================================================================================
-
-    /// Converts a `JsonNumber` to a `double`.
-    ///
     /// @throws ClassCastException if the value is not a `JsonNumber`
     public static double asDouble(JsonValue v) {
         if (v instanceof JsonNumber n) {
@@ -58,8 +39,6 @@ public static double asDouble(JsonValue v) {
         throw new ClassCastException("Expected JsonNumber but got " + v.getClass().getSimpleName());
     }
 
-    /// Converts a `JsonNumber` to a `long`.
-    ///
     /// @throws ClassCastException if the value is not a `JsonNumber`
     public static long asLong(JsonValue v) {
         if (v instanceof JsonNumber n) {
@@ -68,8 +47,6 @@ public static long asLong(JsonValue v) {
         throw new ClassCastException("Expected JsonNumber but got " + v.getClass().getSimpleName());
     }
 
-    /// Converts a `JsonString` to a `String`.
-    ///
     /// @throws ClassCastException if the value is not a `JsonString`
     public static String asString(JsonValue v) {
         if (v instanceof JsonString s) {
@@ -78,8 +55,6 @@ public static String asString(JsonValue v) {
         throw new ClassCastException("Expected JsonString but got " + v.getClass().getSimpleName());
     }
 
-    /// Converts a `JsonBoolean` to a `boolean`.
-    ///
     /// @throws ClassCastException if the value is not a `JsonBoolean`
     public static boolean asBoolean(JsonValue v) {
         if (v instanceof JsonBoolean b) {
@@ -88,26 +63,18 @@ public static boolean asBoolean(JsonValue v) {
         throw new ClassCastException("Expected JsonBoolean but got " + v.getClass().getSimpleName());
     }
 
-    // =================================================================================
-    // Lax Converters (return null if type mismatch)
-    // =================================================================================
-
-    /// Converts to `Double` if the value is a `JsonNumber`, otherwise returns null.
     public static Double asDoubleOrNull(JsonValue v) {
         return (v instanceof JsonNumber n) ? n.toDouble() : null;
     }
 
-    /// Converts to `Long` if the value is a `JsonNumber`, otherwise returns null.
     public static Long asLongOrNull(JsonValue v) {
         return (v instanceof JsonNumber n) ? n.toLong() : null;
     }
 
-    /// Converts to `String` if the value is a `JsonString`, otherwise returns null.
     public static String asStringOrNull(JsonValue v) {
         return (v instanceof JsonString s) ? s.string() : null;
     }
 
-    /// Converts to `Boolean` if the value is a `JsonBoolean`, otherwise returns null.
     public static Boolean asBooleanOrNull(JsonValue v) {
         return (v instanceof JsonBoolean b) ? b.bool() : null;
     }