Properly announce removal of the %errorhandlertype directive (#320)

Fixes #320.

ChangeLog.md

@@ -1,10 +1,16 @@
 # Revision history for Happy
 
-## 2.1
+## 3.0
 
+This release makes one breaking change:
+
+* Remove `%errorhandlertype` directive, reimplement it as `%error.expected`,
+  documented as "Reporting expected tokens" feature
+
+Additionally, it adds the following new features:
+
+* Documented and implemented the new feature "Resumptive parsing with `catch`" (Check it out!)
 * Added `--numeric-version` CLI flag.
-* Documented and implemented the new feature "Resumptive parsing with ``catch``"
-* Documented (and reimplemented) the "Reporting expected tokens" feature
 
 ## 2.0.2
 

doc/syntax.rst

@@ -270,6 +270,8 @@ Error declaration
 
    %error { <identifier> }
 
+   %error { <identifier> } { <identifier> }
+
 .. index:: ``%error``
 
 Specifies the function to be called in the event of a parse error.
@@ -286,6 +288,68 @@ Additional error information
 
 .. index:: ``%errorhandlertype``
 
+Removed in 3.0; overhauled and superseded in favour of the simple, optional flag directive ``%error.expected``.
+See <sec-error-expected-directive>.
+
+.. _sec-error-expected-directive:
+
+Reporting expected tokens
+-------------------------
+
+.. index:: ``%error.expected``
+
+(optional)
+Often, it is useful to present users with suggestions as to which kind of tokens
+where expected at the site of a syntax error.
+To this end, when the ``%error.expected`` directive is specified, happy assumes that
+the error handling function (resp. ``report`` function when using the binary
+form of the ``%error`` directive) takes a ``[String]`` argument (the argument
+*after* the token stream, in case of a non-threaded lexer) listing all the
+stringified tokens that could be shifted at the site of the syntax error.
+The strings in this list are derived from the ``%token`` directive.
+
+Here is an example, inspired by test case ``monaderror-explist``:
+
+.. code-block:: none
+
+  %tokentype { Token }
+  %error { handleErrorExpList }
+  %error.expected
+
+  %monad { ParseM } { (>>=) } { return }
+
+  %token
+          'S'             { TokenSucc }
+          'Z'             { TokenZero }
+          'T'             { TokenTest }
+
+  %%
+
+  Exp         :       'Z'           { 0 }
+              |       'T' 'Z' Exp   { $3 + 1 }
+              |       'S' Exp       { $2 + 1 }
+
+  %%
+
+  type ParseM = ...
+
+  handleErrorExpList :: [Token] -> [String] -> ParseM a
+  handleErrorExpList ts explist = throwError $ ParseError $ explist
+
+  ...
+
+
+Additional error information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+   %error.expected
+
+.. index:: ``%error.expected``
+
+Deprecated in favour of the simple, optional flag directive ``%error.expected``.
+
 (optional)
 The expected type of the user-supplied error handling can be applied with additional information.
 By default, no information is added, for compatibility with previous versions.

doc/using.rst

@@ -1118,7 +1118,7 @@ A couple of notes:
 
   * Whether or not the ``abort`` and ``report`` functions get passed the
     list of tokens is subject to the :ref:`same decision logic as for ``parseError`` <sec-monad-summary>`.
-    When using :ref:`the ``%error.expected`` directive <sec-expected-list>`,
+    When using :ref:`the ``%error.expected`` directive <sec-error-expected-directive>`,
     the list of expected tokens is passed to ``report`` only, between ``tks``
     and ``resume``.
 
@@ -1127,52 +1127,6 @@ to the user of happy; the example above simply emitted the string ``catch``
 whenever it stands-in an for an errorneous AST node.
 A more reasonable implementation would be similar to typed holes in GHC.
 
-.. _sec-expected-list:
-
-Reporting expected tokens
--------------------------
-
-.. index:: expected tokens
-
-Often, it is useful to present users with suggestions as to which kind of tokens
-where expected at the site of a syntax error.
-To this end, when ``%error.expected`` directive is specified, happy assumes that
-the error handling function (resp. ``report`` function when using the binary
-form of the ``%error`` directive) takes a ``[String]`` argument (the argument
-*after* the token stream, in case of a non-threaded lexer) listing all the
-stringified tokens that were expected at the site of the syntax error.
-The strings in this list are derived from the ``%token`` directive.
-
-Here is an example, inspired by test case ``monaderror-explist``:
-
-.. code-block:: none
-
-  %tokentype { Token }
-  %error { handleErrorExpList }
-  %error.expected
-
-  %monad { ParseM } { (>>=) } { return }
-
-  %token
-          'S'             { TokenSucc }
-          'Z'             { TokenZero }
-          'T'             { TokenTest }
-
-  %%
-
-  Exp         :       'Z'           { 0 }
-              |       'T' 'Z' Exp   { $3 + 1 }
-              |       'S' Exp       { $2 + 1 }
-
-  %%
-
-  type ParseM = ...
-
-  handleErrorExpList :: [Token] -> [String] -> ParseM a
-  handleErrorExpList ts explist = throwError $ ParseError $ explist
-
-  ...
-
 .. _sec-multiple-parsers:
 
 Generating Multiple Parsers From a Single Grammar

lib/frontend/src/Happy/Frontend/Lexer.lhs

@@ -131,6 +131,8 @@ followed by a special identifier.
 >               cont (TokenKW TokSpecId_Expect) rest
 >       'e':'r':'r':'o':'r':'.':'e':'x':'p':'e':'c':'t':'e':'d':rest | end_of_id rest ->
 >               cont (TokenKW TokSpecId_ErrorExpected) rest
+>       'e':'r':'r':'o':'r':'h':'a':'n':'d':'l':'e':'r':'t':'y':'p':'e':rest | end_of_id rest ->
+>               lexError ("The %errorhandlertype directive has been removed in Happy 3.0. Use %error.expected instead.") s
 >       'e':'r':'r':'o':'r':rest | end_of_id rest ->
 >               cont (TokenKW TokSpecId_Error) rest
 >       'a':'t':'t':'r':'i':'b':'u':'t':'e':'t':'y':'p':'e':rest | end_of_id rest ->