Make ParsingError public?

[Jeehut]

I just started migrating over to the latest version of swift-parsing. While doing that, I had some custom parsers that I wanted to update to the new throwing style. One of my parsers has a minCharacters variable and when I can't find that chars, I'd like to throw a ParsingError. But when I do, I get an error because ParsingError seems to be internal to the library. Is there any reason we shouldn't have access to the ParsingError type for our custom parsers? While I could write my own error type, wouldn't it be more convenient if all parsers would throw the same errors?

Here's my custom parser:

/// A parser that consumes all whitespace characters from the beginning of the input. No output.
struct Whitespaces: Parser {
  let minCharacters: Int

  init(
    minCharacters: Int = 0
  ) {
    self.minCharacters = minCharacters
  }

  func parse(_ input: inout Substring) throws {
    let foundWhitespaces = input.prefix { char in
      char == " " || char == "\n" || char == "\r" || char == "\t"
    }

    guard foundWhitespaces.count >= minCharacters else {
      throw ParsingError.expectedInput("\(minCharacters) whitespaces", at: input)
      // => ERROR: Cannot find 'ParsingError' in scope
    }

    input.removeFirst(foundWhitespaces.count)
  }
}

[tgrapperon]

I agree that is cumbersome, but ParsingError is a new type that is evolving very quickly, and the authors prefer to keep it internal at least for now, until its shape and a public API settle.

[Jeehut]

I see, in that case I'll use a simple custom error type like this until the ParsingError is made public:

struct ParsingError: Error {
  let expectedInput: String
  let remainingInput: Substring

  init(expected expectedInput: String, at remainingInput: Substring) {
    self.expectedInput = expectedInput
    self.remainingInput = remainingInput
  }
}

The above custom parser example looks like this with my custom error type:

/// A parser that consumes all whitespace characters from the beginning of the input. No output.
struct Whitespaces: Parser {
  let minCharacters: Int

  init(
    minCharacters: Int = 0
  ) {
    self.minCharacters = minCharacters
  }

  func parse(_ input: inout Substring) throws {
    let foundWhitespaces = input.prefix { char in
      char == " " || char == "\n" || char == "\r" || char == "\t"
    }

    guard foundWhitespaces.count >= minCharacters else {
      throw ParsingError(expected: "\(minCharacters) whitespaces", at: input)
    }

    input.removeFirst(foundWhitespaces.count)
  }
}

[Jeehut]

Having _ParserError would actually help. I would make sure to only use as few features as possible so I don't run into large problems when you iterate over it. Thank you for the consideration.

[tgrapperon]

Prefixing with an underscore is a good solution in my opinion.
Even if it's stated in the documentation, many users will already understand implicitly the caveats of being underscored.
On the top of that, having more users handling the value with its limitations will probably provide many constructive use-cases to polish its API.

[randomeizer]

I'll add my vote for exposing it as _ParserError.

[lukeredpath]

Another +1 to making this public with the underscore and the caveat that its a fast moving API.

[stephencelis]

@lukeredpath We're down for that. Any chance you have time to PR this? If not we'll try to carve out some time next week.

[alexito4]

I think this would also be beneficial for testing, since we could write an assert that expects a specific error to be thrown.

[wilhuff]

So... ParserError hasn't materially changed since April 2022. Would you accept a PR that flipped this to public?

[randomeizer]

Also _PrinterError.

[randomeizer]

I think you could probably just create the PR and they will address it when they get time.