Introduction

Happy is a parser generator system for Haskell, similar to the tool yacc for C. Like yacc, it takes a file containing an annotated BNF specification of a grammar and produces a Haskell module containing a parser for the grammar.

Happy is flexible: you can have several Happy parsers in the same program, and each parser may have multiple entry points. Happy can work in conjunction with a lexical analyser supplied by the user (either hand-written or generated by another program), or it can parse a stream of characters directly (but this isn’t practical in most cases). In a future version we hope to include a lexical analyser generator with Happy as a single package.

Parsers generated by Happy are fast; generally faster than an equivalent parser written using parsing combinators or similar tools. Furthermore, any future improvements made to Happy will benefit an existing grammar, without need for a rewrite.

Happy is sufficiently powerful to parse full Haskell — GHC itself uses a Happy parser.

Happy can currently generate four types of parser from a given grammar, the intention being that we can experiment with different kinds of functional code to see which is the best, and compiler writers can use the different types of parser to tune their compilers. The types of parser supported are:

  1. “standard” Haskell 98 (should work with any compiler that compiles Haskell 98).

  2. standard Haskell using arrays

    (this is not the default because we have found this generates slower parsers than the standard backend).

  3. Haskell with GHC (Glasgow Haskell) extensions.

    This is a slightly faster option than the standard backend for Glasgow Haskell users.

  4. GHC Haskell with string-encoded arrays. This is the fastest/smallest option for GHC users. If you’re using GHC, the optimum flag settings are -agc (see Invoking).

Happy can also generate parsers which will dump debugging information at run time, showing state transitions and the input tokens to the parser.

Compatibility

Happy is written in Glasgow Haskell. This means that (for the time being), you need GHC to compile it. Any version of GHC >= 7.0 should work.

Remember: parsers produced using Happy should compile without difficulty under any Haskell 98 compiler or interpreter. [1]

Reporting Bugs

Any bugs found in Happy should be reported in the Happy issue tracker. Please include all the relevant information: the compiler used to compile Happy, the command-line options used, your grammar file or preferably a cut-down example showing the problem, and a description of what goes wrong. A patch to fix the problem would also be greatly appreciated.

Requests for new features should also be sent to the above address, especially if accompanied by patches :-).

License

Previous versions of Happy were covered by the GNU general public license. We’re now distributing Happy with a less restrictive BSD-style license. If this license doesn’t work for you, please get in touch.

Copyright 2009, Simon Marlow and Andy Gill. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Acknowledgements

Original authors

Happy versions up to 0.9 were written by Andy Gill and Simon Marlow.

Improvements since 0.9 are by Simon Marlow (and various other contributors).

Generalized LR Backend

  • Ben Medlock

  • Paul Callaghan

Current Maintainers

  • Andreas Abel (@andreasabel)

  • Vladislav Zavialov (@int-index)

  • John Ericson (@Ericson2314)

  • Simon Marlow (@simonmar)

Other contributors

The data is in the Git history. GitHub can render that in various ways.

Extra

A big thanks to Ben Jones for loaning out his copy of the Roger Hargreaves Mr Happy book.