A Revised Haskell 2010 Language Report

The Haskell 2010 language report was released nearly 16 years ago, and despite numerous attempts, no updated report has been published. This lack of an updated report doesn't mean the language hasn't evolved; rather, Haskell has become more elegant, consistent, and user-friendly over time. However, the original report hasn't kept pace with these changes.

Many community members express concern about the prospects of a new report, but they believe it's either too challenging or not worthwhile. I believe this perspective is misguided. Maintaining an up-to-date report is crucial for the Haskell community's well-being, and it's actually feasible to achieve this goal in a reasonable timeframe with the right effort. Here's my plan for accomplishing this, with the aim of finalizing the process before the new year.

The Haskell Language Report is a vital component of Haskell's documentation. While it's not the first resource beginners should refer to when learning Haskell, it's an invaluable tool for those seeking to advance to intermediate or expert levels. If you're looking to understand the precise syntax of floating-point literals, the rules for do-notation, or the meaning of default declarations, the report is your definitive source.

Regrettably, outdated information in the report can lead to confusion and incompatibility with modern compilers. For instance, proposals such as Functor-Applicative-Monad, MonadFail, Foldable-Traversable, and Monad-of-no-return have significantly improved the language, but they've also made the report a historical reference rather than a practical guide.

If the report were the sole resource available to you, any non-trivial Haskell 2010 program you write might not work with current compilers like GHC or MicroHS. Therefore, it's essential to have a revised report that aligns with modern compiler expectations. Creating a new report is a significant undertaking, and we want to avoid the pitfalls that prevented previous attempts.

Setting a realistic goal is therefore crucial. The most attainable target is to create a Revised Haskell 2010 Language Report. This goal ensures that any program valid according to this report will be compatible with both MicroHS and GHC using the Haskell 2010 language edition. Now, let's delve into the technical aspects of developing this report.

The original report was produced using a mix of command-line tools, a custom .verb file format, pdflatex for PDF generation, and tex4ht for HTML creation. However, with advancements in technology since 2010, we can streamline this process. The Typst typesetting system stands out as the most suitable option. While we need to convert the report from the .verb format to .typ files, this has already been accomplished.

Compiling the report using a simple "typst compile" command is now possible, with the added benefit of hyperlinked BNF grammars, making navigation intuitive. The existing report consists of two main sections: the syntax and semantics of the language and the standard libraries. Documenting the standard libraries is critical, as many language features rely on functions, types, and type classes from these libraries.

For example, numeric literals are defined in terms of the numeric hierarchy, do-notation is tied to Monad and MonadFail, and the foreign function interface extensively uses functions from the Foreign.* namespace. To ensure accuracy and consistency, documenting the standard libraries using Haddock—an API documentation tool—is the best approach.

The repository for the revised report includes a cabal package that precisely defines the API as specified in the Haskell 2010 language report. While this package doesn't provide implementations, it serves as a comprehensive reference. A potential future enhancement could involve integrating tools like api-diff to further refine the documentation.