Improve parser errors

[mdiep]

When parsing fails, the errors are pretty rough.

Take this example:

Error while parsing response from server: NIOIMAPCore.ParserError(hint: "none of the options match", file: "NIOIMAPCore/Parser/Grammar/GrammarParser.swift", line: 147)

In this case, I think the actual error is that base64-decoding fails. But oneOf throws away useful error information:

    static func oneOf<T>(_ subParsers: [SubParser<T>], buffer: inout ByteBuffer, tracker: StackTracker, file: String = (#file), line: Int = #line) throws -> T {
        for parser in subParsers {
            do {
                return try composite(buffer: &buffer, tracker: tracker, parser)
            } catch is ParserError {
                continue
            }
        }
        throw ParserError(hint: "none of the options match", file: file, line: line)
    }

[Davidde94]

@mdiep the problem here is that n parsers will have failed before we actually throw the final ParserError. What behaviour would you find useful?

[mdiep]

IME the solution is:

1. Don't backtrack if a subparser consumed any input. This ensures that the most relevant error is returned.
2. Provide a default error to oneOf that's used if no subparsers consumed any input or use the error from the last subparser. (If you do the latter, you can use an always-failing subparser to provide a better error at your discretion.)

elm/parser does (1) but returns a list of errors instead of (2). Haskell's parsec library also works this way.

This approach is also faster since it avoids needless backtracking. But it may require some adjustments to the parser.