Singular query selector stub [skip ci]

Author: jg-rp

docs/singular_query_selector.md

@@ -0,0 +1,43 @@
+# Singular Query Selector
+
+The singular query selector consist of an embedded absolute singular query, the result of which is used as an object member name or array element index.
+
+If the embedded query resolves to a string or int value, at most one object member value or array element value is selected. Otherwise the singular query selector selects nothing.
+
+## Syntax
+
+```
+selector                = name-selector /
+                          wildcard-selector /
+                          slice-selector /
+                          index-selector /
+                          filter-selector /
+                          singular-query-selector
+
+singular-query-selector = abs-singular-query
+```
+
+## Examples
+
+```json
+{
+  "a": {
+    "j": [1, 2, 3],
+    "p": {
+      "q": [4, 5, 6]
+    }
+  },
+  "b": ["j", "p", "q"],
+  "c d": {
+    "x": {
+      "y": 1
+    }
+  }
+}
+```
+
+| Query                 | Result             | Result Path      | Comment                                                           |
+| --------------------- | ------------------ | ---------------- | ----------------------------------------------------------------- |
+| `$.a[$.b[1]]`         | `{"q": [4, 5, 6]}` | `$['a']['p']`    | Object name from embedded singular query                          |
+| `$.a.j[$['c d'].x.y]` | `2`                | `$['a']['j'][1]` | Array index from embedded singular query                          |
+| `$.a[$.b]`            |                    |                  | Embedded singular query does not resolve to a string or int value |

jsonpath/parse.py

@@ -50,6 +50,7 @@
 from .selectors import KeysFilter
 from .selectors import KeysSelector
 from .selectors import PropertySelector
+from .selectors import SingularQuerySelector
 from .selectors import SliceSelector
 from .selectors import WildSelector
 from .token import TOKEN_AND
@@ -239,7 +240,7 @@ def __init__(self, *, env: JSONPathEnvironment) -> None:
 
         self.token_map: Dict[str, Callable[[TokenStream], FilterExpression]] = {
             TOKEN_DOUBLE_QUOTE_STRING: self.parse_string_literal,
-            TOKEN_PSEUDO_ROOT: self.parse_root_path,
+            TOKEN_PSEUDO_ROOT: self.parse_absolute_query,
             TOKEN_FALSE: self.parse_boolean,
             TOKEN_FILTER_CONTEXT: self.parse_filter_context_path,
             TOKEN_FLOAT: self.parse_float_literal,
@@ -254,8 +255,8 @@ def __init__(self, *, env: JSONPathEnvironment) -> None:
             TOKEN_NOT: self.parse_prefix_expression,
             TOKEN_NULL: self.parse_nil,
             TOKEN_RE_PATTERN: self.parse_regex,
-            TOKEN_ROOT: self.parse_root_path,
-            TOKEN_SELF: self.parse_self_path,
+            TOKEN_ROOT: self.parse_absolute_query,
+            TOKEN_SELF: self.parse_relative_query,
             TOKEN_SINGLE_QUOTE_STRING: self.parse_string_literal,
             TOKEN_TRUE: self.parse_boolean,
             TOKEN_UNDEFINED: self.parse_undefined,
@@ -277,7 +278,7 @@ def __init__(self, *, env: JSONPathEnvironment) -> None:
             str, Callable[[TokenStream], FilterExpression]
         ] = {
             TOKEN_DOUBLE_QUOTE_STRING: self.parse_string_literal,
-            TOKEN_PSEUDO_ROOT: self.parse_root_path,
+            TOKEN_PSEUDO_ROOT: self.parse_absolute_query,
             TOKEN_FALSE: self.parse_boolean,
             TOKEN_FILTER_CONTEXT: self.parse_filter_context_path,
             TOKEN_FLOAT: self.parse_float_literal,
@@ -287,8 +288,8 @@ def __init__(self, *, env: JSONPathEnvironment) -> None:
             TOKEN_NIL: self.parse_nil,
             TOKEN_NONE: self.parse_nil,
             TOKEN_NULL: self.parse_nil,
-            TOKEN_ROOT: self.parse_root_path,
-            TOKEN_SELF: self.parse_self_path,
+            TOKEN_ROOT: self.parse_absolute_query,
+            TOKEN_SELF: self.parse_relative_query,
             TOKEN_SINGLE_QUOTE_STRING: self.parse_string_literal,
             TOKEN_TRUE: self.parse_boolean,
         }
@@ -299,15 +300,15 @@ def parse(self, stream: TokenStream) -> Iterator[JSONPathSegment]:
         if stream.current().kind in {TOKEN_ROOT, TOKEN_PSEUDO_ROOT}:
             stream.next()
 
-        yield from self.parse_path(stream)
+        yield from self.parse_query(stream)
 
         if stream.current().kind not in (TOKEN_EOF, TOKEN_INTERSECTION, TOKEN_UNION):
             raise JSONPathSyntaxError(
                 f"unexpected token {stream.current().value!r}",
                 token=stream.current(),
             )
 
-    def parse_path(self, stream: TokenStream) -> Iterable[JSONPathSegment]:
+    def parse_query(self, stream: TokenStream) -> Iterable[JSONPathSegment]:
         """Parse a JSONPath query string.
 
         This method assumes the root, current or pseudo root identifier has
@@ -405,7 +406,7 @@ def parse_selector(self, stream: TokenStream) -> tuple[JSONPathSelector, ...]:
         stream.pos -= 1
         return ()
 
-    def parse_bracketed_selection(self, stream: TokenStream) -> List[JSONPathSelector]:  # noqa: PLR0912
+    def parse_bracketed_selection(self, stream: TokenStream) -> List[JSONPathSelector]:  # noqa: PLR0912, PLR0915
         """Parse a comma separated list of JSONPath selectors."""
         segment_token = stream.eat(TOKEN_LBRACKET)
         selectors: List[JSONPathSelector] = []
@@ -470,6 +471,8 @@ def parse_bracketed_selection(self, stream: TokenStream) -> List[JSONPathSelecto
                 selectors.append(self.parse_filter_selector(stream))
             elif token.kind == TOKEN_KEYS_FILTER:
                 selectors.append(self.parse_filter_selector(stream, keys=True))
+            elif token.kind in (TOKEN_ROOT, TOKEN_NAME):
+                selectors.append(self.parse_singular_query_selector(stream))
             elif token.kind == TOKEN_EOF:
                 raise JSONPathSyntaxError("unexpected end of query", token=token)
             else:
@@ -664,20 +667,41 @@ def parse_grouped_expression(self, stream: TokenStream) -> FilterExpression:
         stream.eat(TOKEN_RPAREN)
         return expr
 
-    def parse_root_path(self, stream: TokenStream) -> FilterExpression:
+    def parse_absolute_query(self, stream: TokenStream) -> FilterExpression:
         root = stream.next()
         return RootFilterQuery(
             JSONPath(
                 env=self.env,
-                segments=self.parse_path(stream),
+                segments=self.parse_query(stream),
                 pseudo_root=root.kind == TOKEN_PSEUDO_ROOT,
             )
         )
 
-    def parse_self_path(self, stream: TokenStream) -> FilterExpression:
-        stream.next()
+    def parse_relative_query(self, stream: TokenStream) -> FilterExpression:
+        stream.eat(TOKEN_SELF)
         return RelativeFilterQuery(
-            JSONPath(env=self.env, segments=self.parse_path(stream))
+            JSONPath(env=self.env, segments=self.parse_query(stream))
+        )
+
+    def parse_singular_query_selector(
+        self, stream: TokenStream
+    ) -> SingularQuerySelector:
+        # TODO: optionally require root identifier
+        token = (
+            stream.next() if stream.current().kind == TOKEN_ROOT else stream.current()
+        )
+
+        query = JSONPath(env=self.env, segments=self.parse_query(stream))
+
+        if not query.singular_query():
+            raise JSONPathSyntaxError(
+                "embedded query selectors must be singular queries", token=token
+            )
+
+        return SingularQuerySelector(
+            env=self.env,
+            token=token,
+            query=query,
         )
 
     def parse_current_key(self, stream: TokenStream) -> FilterExpression:
@@ -687,7 +711,7 @@ def parse_current_key(self, stream: TokenStream) -> FilterExpression:
     def parse_filter_context_path(self, stream: TokenStream) -> FilterExpression:
         stream.next()
         return FilterContextPath(
-            JSONPath(env=self.env, segments=self.parse_path(stream))
+            JSONPath(env=self.env, segments=self.parse_query(stream))
         )
 
     def parse_regex(self, stream: TokenStream) -> FilterExpression:

jsonpath/selectors.py

@@ -22,6 +22,7 @@
     from .env import JSONPathEnvironment
     from .filter import BooleanExpression
     from .match import JSONPathMatch
+    from .path import JSONPath
     from .token import Token
 
 # ruff: noqa: D102
@@ -372,6 +373,45 @@ async def resolve_async(self, node: JSONPathMatch) -> AsyncIterable[JSONPathMatc
                 yield match
 
 
+class SingularQuerySelector(JSONPathSelector):
+    """An embedded absolute query.
+
+    The result of the embedded query is used as an object member name or array element
+    index.
+
+    NOTE: This is a non-standard selector.
+    """
+
+    __slots__ = ("query",)
+
+    def __init__(
+        self, *, env: JSONPathEnvironment, token: Token, query: JSONPath
+    ) -> None:
+        super().__init__(env=env, token=token)
+        self.query = query
+
+    def __str__(self) -> str:
+        return str(self.query)
+
+    def __eq__(self, __value: object) -> bool:
+        return (
+            isinstance(__value, SingularQuerySelector)
+            and self.query == __value.query
+            and self.token == __value.token
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.query, self.token))
+
+    def resolve(self, node: JSONPathMatch) -> Iterable[JSONPathMatch]:
+        # TODO:
+        raise Exception("not implemented")
+
+    async def resolve_async(self, node: JSONPathMatch) -> AsyncIterable[JSONPathMatch]:
+        # TODO:
+        raise Exception("not implemented")
+
+
 class Filter(JSONPathSelector):
     """Filter sequence/array items or mapping/object values with a filter expression."""