More polish, added doc comments to the new code

Author: czechboy0

Sources/OpenAPIRuntime/Conversion/ParameterStyles.swift

@@ -14,7 +14,7 @@
 
 /// The serialization style used by a parameter.
 ///
-/// Details: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-10
+/// Details: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#fixed-fields-10
 @_spi(Generated) public enum ParameterStyle: Sendable {
 
     /// The form style.
@@ -26,9 +26,10 @@
     ///
     /// Details: https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.2
     case simple
+
     /// The deepObject style.
     ///
-    /// Details: https://spec.openapis.org/oas/v3.1.0.html#style-values
+    /// Details: https://spec.openapis.org/oas/v3.0.4.html#style-values
     case deepObject
 }
 

Sources/OpenAPIRuntime/URICoder/Common/URICoderConfiguration.swift

@@ -17,7 +17,7 @@ import Foundation
 /// A bag of configuration values used by the URI encoder and decoder.
 struct URICoderConfiguration {
 
-    /// A variable expansion style as described by RFC 6570 and OpenAPI 3.0.3.
+    /// A variable expansion style as described by RFC 6570 and OpenAPI 3.0.4.
     enum Style {
 
         /// A style for simple string variable expansion.
@@ -50,7 +50,7 @@ struct URICoderConfiguration {
     var style: Style
 
     /// A Boolean value indicating whether the key should be repeated with
-    /// each value, as described by RFC 6570 and OpenAPI 3.0.3.
+    /// each value, as described by RFC 6570 and OpenAPI 3.0.4.
     var explode: Bool
 
     /// The character used to escape the space character.

Sources/OpenAPIRuntime/URICoder/Common/URIDecodedTypes.swift

@@ -0,0 +1,22 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2024 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// A primitive value produced by `URIValueFromNodeDecoder`.
+typealias URIDecodedPrimitive = URIParsedValue
+
+/// An array value produced by `URIValueFromNodeDecoder`.
+typealias URIDecodedArray = URIParsedValueArray
+
+/// A dictionary value produced by `URIValueFromNodeDecoder`.
+typealias URIDecodedDictionary = [Substring: URIParsedValueArray]

Sources/OpenAPIRuntime/URICoder/Common/URIEncodedNode.swift

@@ -128,7 +128,7 @@ extension URIEncodedNode {
         }
     }
 
-    /// Marks the node as an array, starting of empty.
+    /// Marks the node as an array, starting as empty.
     /// - Throws: If the node is already set to be anything else but an array.
     mutating func markAsArray() throws {
         switch self {

Sources/OpenAPIRuntime/URICoder/Common/URIParsedNode.swift

@@ -0,0 +1,91 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+
+/// A component of a `URIParsedKey`.
+typealias URIParsedKeyComponent = String.SubSequence
+
+/// A parsed key for a parsed value.
+///
+/// For example, `foo=bar` in a `form` string would parse the key as `foo` (single component).
+/// In an unexploded `form` string `root=foo,bar`, the key would be `root/foo` (two components).
+/// In a `simple` string `bar`, the key would be empty (0 components).
+struct URIParsedKey: Hashable {
+
+    /// The individual string components.
+    let components: [URIParsedKeyComponent]
+    
+    /// Creates a new parsed key.
+    /// - Parameter components: The key components.
+    init(_ components: [URIParsedKeyComponent]) { self.components = components }
+
+    /// A new empty key.
+    static var empty: Self { .init([]) }
+}
+
+/// A primitive value produced by `URIParser`.
+typealias URIParsedValue = String.SubSequence
+
+/// An array of primitive values produced by `URIParser`.
+typealias URIParsedValueArray = [URIParsedValue]
+
+/// A key-value produced by `URIParser`.
+struct URIParsedPair: Equatable {
+
+    /// The key of the pair.
+    ///
+    /// In `foo=bar`, `foo` is the key.
+    var key: URIParsedKey
+
+    /// The value of the pair.
+    ///
+    /// In `foo=bar`, `bar` is the value.
+    var value: URIParsedValue
+}
+
+/// An array of key-value pairs produced by `URIParser`.
+typealias URIParsedPairArray = [URIParsedPair]
+
+// MARK: - Extensions
+
+extension URIParsedKey: CustomStringConvertible {
+    /// A textual representation of this instance.
+    ///
+    /// Calling this property directly is discouraged. Instead, convert an
+    /// instance of any type to a string by using the `String(describing:)`
+    /// initializer. This initializer works with any type, and uses the custom
+    /// `description` property for types that conform to
+    /// `CustomStringConvertible`:
+    ///
+    ///     struct Point: CustomStringConvertible {
+    ///         let x: Int, y: Int
+    ///
+    ///         var description: String {
+    ///             return "(\(x), \(y))"
+    ///         }
+    ///     }
+    ///
+    ///     let p = Point(x: 21, y: 30)
+    ///     let s = String(describing: p)
+    ///     print(s)
+    ///     // Prints "(21, 30)"
+    ///
+    /// The conversion of `p` to a string in the assignment to `s` uses the
+    /// `Point` type's `description` property.
+    var description: String {
+        if components.isEmpty { return "<empty>" }
+        return components.joined(separator: "/")
+    }
+}

Sources/OpenAPIRuntime/URICoder/Common/URIParsedTypes.swift

@@ -15,7 +15,7 @@
 import Foundation
 
 /// A type that decodes a `Decodable` value from an URI-encoded string
-/// using the rules from RFC 6570, RFC 1866, and OpenAPI 3.0.3, depending on
+/// using the rules from RFC 6570, RFC 1866, and OpenAPI 3.0.4, depending on
 /// the configuration.
 ///
 /// [RFC 6570 - Form-style query expansion.](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.8)
@@ -45,6 +45,13 @@ import Foundation
 /// | `{list\*}`       | `red,green,blue`                  |
 /// | `{keys}`         | `semi,%3B,dot,.,comma,%2C`        |
 /// | `{keys\*}`       | `semi=%3B,dot=.,comma=%2C`        |
+///
+/// [OpenAPI 3.0.4 - Deep object expansion.](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#style-examples)
+///
+/// | Example Template |   Expansion                                               |
+/// | ---------------- | ----------------------------------------------------------|
+/// | `{?keys\*}`      | `?keys%5Bsemi%5D=%3B&keys%5Bdot%5D=.&keys%5Bcomma%5D=%2C` |
+///
 struct URIDecoder: Sendable {
 
     /// The configuration instructing the decoder how to interpret the raw
@@ -60,27 +67,24 @@ extension URIDecoder {
 
     /// Attempt to decode an object from an URI string.
     ///
-    /// Under the hood, `URIDecoder` first parses the string into a
-    /// `URIParsedNode` using `URIParser`, and then uses
-    /// `URIValueFromNodeDecoder` to decode the `Decodable` value.
-    ///
     /// - Parameters:
     ///   - type: The type to decode.
     ///   - key: The key of the decoded value. Only used with certain styles
     ///     and explode options, ignored otherwise.
     ///   - data: The URI-encoded string.
     /// - Returns: The decoded value.
     /// - Throws: An error if decoding fails, for example, due to incompatible data or key.
-    func decode<T: Decodable>(_ type: T.Type = T.self, forKey key: String = "", from data: Substring) throws -> T {
-        try withDecoder(from: data, forKey: key) { decoder in try decoder.decodeRoot(type) }
+    func decode<T: Decodable>(
+        _ type: T.Type = T.self,
+        forKey key: String = "",
+        from data: Substring
+    ) throws -> T {
+        let decoder = URIValueFromNodeDecoder(data: data, rootKey: key[...], configuration: configuration)
+        return try decoder.decodeRoot(type)
     }
 
     /// Attempt to decode an object from an URI string, if present.
     ///
-    /// Under the hood, `URIDecoder` first parses the string into a
-    /// `URIParsedNode` using `URIParser`, and then uses
-    /// `URIValueFromNodeDecoder` to decode the `Decodable` value.
-    ///
     /// - Parameters:
     ///   - type: The type to decode.
     ///   - key: The key of the decoded value. Only used with certain styles
@@ -90,22 +94,8 @@ extension URIDecoder {
     /// - Throws: An error if decoding fails, for example, due to incompatible data or key.
     func decodeIfPresent<T: Decodable>(_ type: T.Type = T.self, forKey key: String = "", from data: Substring) throws
         -> T?
-    { try withDecoder(from: data, forKey: key) { decoder in try decoder.decodeRootIfPresent(type) } }
-
-    /// Make multiple decode calls on the parsed URI.
-    ///
-    /// Use to avoid repeatedly reparsing the raw string.
-    /// - Parameters:
-    ///   - data: The URI-encoded string.
-    ///   - key: The root key to decode.
-    ///   - calls: The closure that contains 0 or more calls to
-    ///     the `decode` method on `URIDecoderImpl`.
-    /// - Returns: The result of the closure invocation.
-    /// - Throws: An error if parsing or decoding fails.
-    func withDecoder<R>(from data: Substring, forKey key: String, calls: (URIValueFromNodeDecoder) throws -> R) throws
-        -> R
     {
         let decoder = URIValueFromNodeDecoder(data: data, rootKey: key[...], configuration: configuration)
-        return try calls(decoder)
+        return try decoder.decodeRootIfPresent(type)
     }
 }