Enhance Fail parser with a custom error message (#244)

It's useful to have a way how to specify a custom error message for the
`Fail` parser; the current workaround is to throw an exception instead
of using the `Fail` parser.

The implementation is backwards-compatible, the original `Fail`
signature doesn't change and it works the same way as before.

**Issue**: closes #243

---------

Co-authored-by: Li Haoyi <haoyi.sg@gmail.com>

.gitignore

@@ -3,8 +3,10 @@ target/
 out/
 .DS_STORE
 *.iml
-.idea/
+.idea
+.coursier
 .bloop/
 .metals/
+project/metals.sbt
 .vscode/
 .bsp/

README.md

@@ -46,7 +46,7 @@ compiled to Scala.js. These all live in `demo/`.
 Common Commands
 ---------------
 
-- `mill -w fastparse.jvm[2.12.7].test` runs the main testsuite. If you're
+- `mill -w fastparse.jvm[2.12.10].test` runs the main testsuite. If you're
   hacking on FastParse, this is often where you want to go
 
 - You can run the other suites via `fastparse.js`, `scalaparse.jvm`, etc. if you
@@ -57,7 +57,7 @@ Common Commands
   versions, but again I usually don't bother
 
 - `mill __.test.test` is the aggregate test-all command, but is pretty slow. You
-  can use `mill __.jvm[2.12.7].test` to run all tests only under JVM/Scala-2.12,
+  can use `mill __.jvm[2.12.10].test` to run all tests only under JVM/Scala-2.12,
   which is much faster and catches most issues
 
 - `mill demo.fullOpt && sbt readme/run` builds the documentation site, which can

fastparse/src/fastparse/SharedPackageDefs.scala

@@ -154,12 +154,16 @@ trait SharedPackageDefs {
   /**
     * No-op parser that always fails, consuming zero characters
     */
-  def Fail(implicit ctx: P[_]): P[Nothing] = {
+  def Fail(implicit ctx: P[_]): P[Nothing] = Fail("fail")
+
+  /**
+   * No-op parser with a custom error message that always fails, consuming zero characters
+   */
+  def Fail(msg: String)(implicit ctx: P[_]): P[Nothing] = {
     val res = ctx.freshFailure()
     if (ctx.verboseFailures) ctx.reportTerminalMsg(ctx.index, () => "fail")
     res
   }
-
   /**
     * Parser that always succeeds and returns the current index into the parsed
     * input. Useful for e.g. capturing source locations so when downstream
@@ -292,4 +296,4 @@ object SharedPackageDefs{
     val res = parse0()
     res
   }
-}
+}

fastparse/test/src/fastparse/ExampleTests.scala

@@ -129,6 +129,10 @@ object ExampleTests extends TestSuite{
       test("passfail"){
         val Parsed.Success((), 0) = parse("asdad", Pass(_))
         val Parsed.Failure(_, 0, _) = parse("asdad", Fail(_))
+
+        def failWithLabel[$: P] = P( Fail("custom fail msg") )
+        val Parsed.Failure(_, 0, extra) = parse("asdad", failWithLabel(_))
+        assert(extra.trace().longMsg == """Expected failWithLabel:1:1 / fail:1:1, found "asdad"""")
       }
 
       test("index"){