RFC: Allow throwing custom errors within grammar files

[Kroc]

Add a special term that, if matched, immediately throws an error with custom error message appended.

bin_or_type     = @{
    "%" ~ (
        bin_num     // ... 0s or 1s
    |   type_name   // ... an ID
    |   err! -> "Not recognised as a binary number ('%10101010') or a custom type name ('%vector')"
    )
}

The purpose would be to:

1. allow fast-failing by minimizing the amount of backtracking where the author knows there are no alternates
2. Allow the author to implement friendlier error messages without having to write custom-parsing Rust code

[dragostis]

I'll close this in favor of #333 and add a chapter about it there once I get to do a revision based on the feedback left!

[CAD97]

Just a few thoughts on the actual implementation (I love this idea for giving more control over errors!):

As a generalization, add a very limited form of "actions", which are written as action!(parameters) (thus looking like a Rust macro invocation). For the time being, these will only allowed to be defined by pest itself for error recovery control (and probably should remain "strippable", being able to get the same tokenization result without them), but maybe this could somehow be relaxed in the future?

As some examples of possible actions pest could add (and in a pseudo-#333 syntax),

id =
 @{ pest::defer_err!("_" - pest::unicode[XID_Continue]* => "Identifiers aren't allowed to start with `_`")
  | pest::unicode[XID_Start] - pest::unicode[XID_Continue]*
  }

This would emit an error pointing to the id if it started with an underscore, which isn't a valid identifier under profile-less UAX-31, but still match it as one, allowing parsing to continue (and emit a later error as well, if found.)

bin_or_ty = @{ "%" - (bin | ty | err!((!trivia - pest::any)* => "Not recognized as a binary number (`%10101010`) or type name (`%vector`)")

This could both allow customizing the error message emitted by pest as well as in this case, defining a span which to grab and point at in the constructed error.

This is a super rough proposal generalization of this, but these usages I've demonstrated here seem like they could be very useful.