Merge pull request rarestype#124 from rarestype/jq

[minor]: jq style decoding-free query language

Author: tayloraswift

Package.swift

@@ -6,13 +6,17 @@ let package: Package = .init(
     name: "swift-json",
     platforms: [.macOS(.v15), .iOS(.v18), .tvOS(.v18), .watchOS(.v11), .visionOS(.v2)],
     products: [
+        .library(name: "JavaScriptPersistence", targets: ["JavaScriptPersistence"]),
+        .library(name: "JQ", targets: ["JQ"]),
         .library(name: "JSON", targets: ["JSON"]),
         .library(name: "JSONAST", targets: ["JSONAST"]),
         .library(name: "JSONLegacy", targets: ["JSONLegacy"]),
-        .library(name: "JavaScriptPersistence", targets: ["JavaScriptPersistence"]),
 
         .library(name: "_JSON_SnippetsAnchor", targets: ["_JSON_SnippetsAnchor"]),
     ],
+    traits: [
+        .trait(name: "_ExperimentalJQ"),
+    ],
     dependencies: [
         .package(url: "https://github.com/ordo-one/dollup", from: "1.0.1"),
         .package(url: "https://github.com/rarestype/gram", from: "2.0.0"),
@@ -59,6 +63,13 @@ let package: Package = .init(
             ]
         ),
 
+        .target(
+            name: "JQ",
+            dependencies: [
+                .target(name: "JSONAST"),
+            ]
+        ),
+
         .target(
             name: "JavaScriptPersistence",
             dependencies: [
@@ -72,6 +83,13 @@ let package: Package = .init(
                 .target(name: "JSON"),
             ]
         ),
+        .testTarget(
+            name: "JQTests",
+            dependencies: [
+                .target(name: "JSON"),
+                .target(name: "JQ"),
+            ]
+        ),
 
 
         .target(

Sources/JQ/JSON.Array (ext).swift

@@ -0,0 +1,16 @@
+public import JSONAST
+
+extension JSON.Array {
+    @inlinable init(value: JSON.Node, at index: Int) {
+        var values: [JSON.Node]
+        if  index > 0 {
+            values = []
+            values.reserveCapacity(1 + index)
+            values += repeatElement(.null, count: index)
+            values.append(value)
+        } else {
+            values = [value]
+        }
+        self.init(values)
+    }
+}

Sources/JQ/JSON.ArrayAccessor.swift

@@ -0,0 +1,116 @@
+public import JSONAST
+
+extension JSON {
+    @frozen public struct ArrayAccessor: ~Copyable {
+        @usableFromInline let crumb: PathComponent?
+        @usableFromInline var state: NodeAccess<Array>
+
+        @inlinable init(crumb: PathComponent?, state: NodeAccess<Array>) {
+            self.crumb = crumb
+            self.state = state
+        }
+    }
+}
+extension JSON.ArrayAccessor {
+    @inlinable static func protected(_ crumb: JSON.PathComponent?) -> Self {
+        .init(crumb: crumb, state: .protected)
+    }
+
+    @inlinable static func reserved(_ crumb: JSON.PathComponent?, _ index: Int) -> Self {
+        .init(crumb: crumb, state: .reserved(index))
+    }
+
+    @inlinable static var writable: Self {
+        .init(crumb: nil, state: .writable)
+    }
+
+    @inlinable static func occupied(_ value: consuming JSON.Array) -> Self {
+        .init(crumb: nil, state: .occupied(value))
+    }
+}
+extension JSON.ArrayAccessor {
+    @discardableResult
+    @inlinable public static func &? <E, T>(
+        self: inout Self,
+        yield: (inout JSON.Array) throws(E) -> T
+    ) throws(E) -> T? {
+        switch self.state {
+        case .protected:
+            return nil
+        case .reserved:
+            return nil
+        case .writable:
+            return nil
+        case .occupied(var array):
+            self.state = .writable
+            defer {
+                self.state = .occupied(array)
+            }
+            return try yield(&array)
+        }
+    }
+
+    @inlinable public static func & (
+        self: inout Self,
+        yield: (inout JSON.Array?) throws -> ()
+    ) throws {
+        switch self.state {
+        case .protected:
+            var array: JSON.Array? = nil
+            try yield(&array)
+            if  array != nil {
+                throw JSON.NodeAccessError.protected(self.crumb)
+            }
+
+        case .reserved(let offender):
+            var array: JSON.Array? = nil
+            try yield(&array)
+            if  array != nil {
+                throw JSON.NodeAccessError.reserved(self.crumb, offender)
+            }
+
+        case .writable:
+            var array: JSON.Array? = []
+            try yield(&array)
+            if  let array: JSON.Array {
+                self.state = .occupied(array)
+            }
+
+        case .occupied(let value):
+            var array: JSON.Array? = consume value
+
+            self.state = .writable
+            defer {
+                self.state = array.map { .occupied($0) } ?? .writable
+            }
+            try yield(&array)
+        }
+    }
+
+    @inlinable public static func |? <E, T>(
+        self: borrowing Self,
+        yield: (JSON.Node) throws(E) -> T
+    ) throws(E) -> [T]? {
+        if  case .occupied(let array) = self.state {
+            return try array.elements.map(yield)
+        } else {
+            return nil
+        }
+    }
+
+    @inlinable public static func | <T>(
+        self: borrowing Self,
+        yield: (JSON.Node) throws -> T
+    ) throws -> [T] {
+        switch self.state {
+        case .protected:
+            throw JSON.NodeAccessError.protected(self.crumb)
+        case .reserved(let offender):
+            throw JSON.NodeAccessError.reserved(self.crumb, offender)
+        case .writable:
+            return []
+        case .occupied(let array):
+            return try array.elements.map(yield)
+        }
+    }
+}