SpecialisedGen

This method can be overridden to control how wide an error is based on the value and width that produces it.

The width provides to this error generator likely comes directly from the span of the parser used to produce the required result. However, this may not be entirely accurate for how the user might want the error to be sized (perhaps there was whitespace, or the parser consumed more input than was necessary to pin-point the problem). In these cases, this method allows for custom logic to derive the actual width of the error message. By default, just returns the given width.

This combinator takes a given parser and raises an error based on its returned results.

The given parser produces a value and a width, which are used to synthesise and raise an error message derived from the value with the given width. This is a safe way of using parser, since it ensures that the result of the given parser p is not optimised out. errGen(p) is similar to withWidth(p).flatMap { case (x, w) => failCombinator(...) }, in that it generates errors in a context-sensitive way. However, this is much more efficient than using the expensive flatMap, so it is provided as a primitive operation.

This parser can be applied (postfix) to a parser returning a value and a width to generate an error message tailored to them.

This is not a generally safe operation to be performing, and should only be used within a combinator that is guaranteed to use its results. The optimiser is not aware that the results of the parser this will be applied to will actually be needed, and so may optimise them out. Using this parser inside an arm of select or branch, say, would be safe, because these combinators force the result of their condition to be generated, but p <**> this.parser is not generally safe without a use of impure to guard it. This is what apply accomplishes more safely.