Working with slightly more "structured" input data

[lukeredpath]

A lot of the examples for this library are focussed on parsing strings as input data into more structured output. However, as demonstrated by the URLRouting library's URLRequestData you can also parse slightly more "structured" inputs into better structured outputs. I was wondering if there might be a use case for some kind of general "key path" parser for parsing off properties of a struct. This is effectively what URLRouting does but in its case, it ships with a bunch of domain-specific parsers that work with specific properties of URLRequestData.

One use case might be dealing with JSON APIs that return objects in a way that makes sense for constructing JSON schemas but doesn't translate nicely into a well designed and strongly typed domain within your code (which might involve enums and generics etc that don't map nicely to the JSON structure). If you've ever tried to do any kind of advanced JSON decoding in Swift you'll find you hit the limitations of Codable very quickly and end up with a spaghetti of pseudo-parsing code within your custom codable implementations.

An alternative approach would be a two-step process where you parse the JSON into less structured types that reflect the JSON schema itself and then use those types as input into a parser that transforms it into your more structured domain. The nice thing about this is converting your domain types back into JSON would simply be a case of using your parser to print back into the unstructured types and then encoding the unstructured types back into JSON.

Example

Let's say we have this JSON schema returned from our API:

{
  type: "string" // other types like "int", "date" etc. are supported
  value: "value" // this is _always_ a string and needs to be parsed into a native type based on the "type" value.
}

There's a few ways we could model this in Swift - a generic Value<T> although that might be a bit too flexible. If there are limited number of types supported, we might choose to model this as an enum instead:

enum SomeValue {
  case string(String)
  case int(Int)
  // etc.
}

Now, instead of trying to write some kind of messy custom Codable implementation, we're going to first parse the JSON into a less structured value that more accurately represents the JSON schema, which can be done with minimal boilerplate and gives us something we can use as input:

struct JsonType: Codable {
  var type: Substring?
  var value: Substring?
}

KeyPath parsing

Now all we need to do is write a parser of (JsonType) -> SomeValue. Without having to write completely custom parsers to deal with this, it would be nice if we could generalise this approach by parsing off a mutable property of a struct by referencing its key path. I've managed to come up with something like this so far (it needs more work I think):

enum Parsers {
    struct KeyPath<Root, Value, ValueParser: ParserPrinter>: ParserPrinter
    where ValueParser.Input == Value
    {
        private let keyPath: WritableKeyPath<Root, Value?>
        private let valueParser: ValueParser

        init(
            _ keyPath: WritableKeyPath<Root, Value?>,
            @ParserBuilder _ valueParser: () -> ValueParser
        ) {
            self.keyPath = keyPath
            self.valueParser = valueParser()
        }

        func parse(_ input: inout Root) throws -> ValueParser.Output {
            guard var value = input[keyPath: keyPath] else { throw ParsingError() }
            let output = try valueParser.parse(&value)
            input[keyPath: keyPath] = value
            return output
        }

        func print(_ output: ValueParser.Output, into input: inout Root) throws {
            guard var value = input[keyPath: keyPath] else { throw ParsingError() }
            try valueParser.print(output, into: &value)
            input[keyPath: keyPath] = value
        }
    }
}

We can now write our parser:

let parser = OneOf {
    Parse(.case(SomeValue.string)) {
        Parsers.KeyPath(\JsonType.type) {
            "string"
        }
        Parsers.KeyPath(\JsonType.value) {
            Parse(.string) { Rest() }
        }
    }
    Parse(.case(SomeValue.int)) {
        Parsers.KeyPath(\JsonType.type) {
            "int"
        }
        Parsers.KeyPath(\JsonType.value) {
            Int.parser()
        }
    }
}

Alternatives

Would some version of this key path parser be useful in the library, or would we be better off writing a completely custom domain-specific parser instead? Writing a custom parser feels like it would be a bit more work although arguably the final result could end up looking a bit clearer:

struct JsonTypeParser<ValueParser: ParserPrinter>: ParserPrinter where ValueParser.Input == Substring {
    let type: Substring
    let valueParser: ValueParser

    init(
        _ type: Substring,
        @ParserBuilder _ valueParser: () -> ValueParser
    ) {
        self.type = type
        self.valueParser = valueParser()
    }

    func parse(_ input: inout JsonType) throws -> ValueParser.Output {
        guard input.type == type else { throw ParsingError() }
        guard var value = input.value else { throw ParsingError() }
        input.type = nil
        let output = try valueParser.parse(&value)
        input.value = value
        return output
    }

    func print(_ output: ValueParser.Output, into input: inout JsonType) throws {
        guard var value = input.value else { throw ParsingError() }
        try valueParser.print(output, into: &value)
        input.type = type
        input.value = value
    }
}

So now the parser becomes:

let parser = OneOf {
    Parse(.case(ParsedValue.string)) {
        JsonTypeParser("string") {
            Parse(.string) { Rest() }
        }
    }
    Parse(.case(ParsedValue.int)) {
        JsonTypeParser("int") {
            Int.parser()
        }
    }
}