Add `parseEntireOrNull()` function

[aSemy]

I'd like to be able to parse and receive null if the parsing fails.

• This would be useful because I could parse a statement and, if it fails, then throw a more specific exception. Example:

  val statement = "a & (b1 -> c1) | a1 & !b | !(a1 -> a2) -> a"
  val ast = booleanGrammar.parseEntireOrNull(statement)
    ?: error("failed to parse boolean statement '$statement'")

• Add an *OrNull() variant matches the Kotlin standard library functions patterns, which use *OrNull() for parsing numbers, or getting elements from lists, and more.

Remove parseEntireOrThrow()?

I'd even go further and completely remove the parseEntireOrThrow() function.

• I think it would be more idiomatic to give the option to users to throw using an elvis operator, because it would encourage more detailed error messages.

• Introducing try/catches into code that relies on coroutines can be risky, because there's a chance users will catch a general Exception, which can disrupt Coroutines cancellation if implemented improperly. (Because coroutines are cancelled via a CancellationException, if an Exception is swallowed then a cancellation won't propagate).

  Returning null would also allow for handling error scenarios without needing to worry about try/catches:

  val statement = "help"
  val ast = booleanGrammar.parseEntireOrNull(statement)
  if (ast == null) {
    val cmd = commandGrammar.parseEntireOrNull(statement)
    handleUnexpectedCommand(cmd)
    return
  }

Document parseEntireOrThrow() with @Throws

Because I'm proposing removing parseEntireOrThrow() I thought I'd put this issue here rather than make a new issue.

I'm using Parsus in a .kts script, and unfortunately IntelliJ doesn't handle dependencies very well, so I can't see the source code documentation that says what exception parseEntireOrThrow() could throw.

Adding @Throws would help with JVM consumers.

[alllex]

I think that's a good suggestion. This could work for cases where it's fine to tell the end-user that the complete input is not valid.

Overall, however, it's also important to provide some means of localized error reporting. If parsing fails, it may be better to say that in the particular place (position in the input) something else was expected. This information gets lost, if we just do parseEntireOrNull.

[aSemy]

Thanks for looking into it @alllex.

I've had a bit more of a play around and I agree, having the failure reasons would be important.

I can see that this functionality already exists:

SemVerParser.parseEntire(input).getOrElse { return null }

But because it requires chaining a couple of methods it's a little harder to find.

To make this more similar to the Kotlin stdlib (e.g. getOrElse(), I propose introducing a parseOrElse() {} function.

SemVerParser.parseOrElse(input) { err -> 
  error("could not parse $input, because $err")
}

// or return another value
val DEFAULT = SemVer("0.0.0-SNAPSHOT")
SemVerParser.parseOrElse(input) { DEFAULT }

And then parseOrNull() would be a shortcut for

SemVerParser.parseOrElse(input) { null }

which might be useful in some situations.

I also suggest removing Entire from the function names. There's no 'partial' parsing, all parse* functions parse the entire input, so I think the 'Entire' keyword is a little confusing and redundant. If partial parsing was introduced, then it should be done with an overload with a range.

[alllex]

I agree that OrElse and OrNull shorthands are idiomatic in Kotlin. I'll add them soon.

As for the Entire, I would keep it for now to keep the intent clear as it is done with Regex APIs in Kotlin.

[alllex]

After more consideration, I actually agree with you that Entire seems like an overkill. I will introduce functions without it in the name, and deprecate the ones that have it.

[alllex]

All functions you described are on main now and will be included in the next release

[aSemy]

Thanks for the updates @alllex!