Introduction

# Chapter 1 Introduction

Frown is an LALR(k) parser generator for Haskell 98 written in Haskell 98.
The work on Frown started as an experiment in generating genuinely functional LR parsers. The first version was written within three days—yes, Haskell is a wonderful language for rapid prototyping. Since then Frown has gone through several cycles of reorganization and rewriting. It also grew considerably: dozens of features were added, examples were conceived and tested, and this manual was written. In the end, Frown has become a useable tool. I hope you will find it useful, too.

## 1.1 Obtaining and installing Frown

##### Obtaining Frown

The parser generator is available from

> `http://www.informatik.uni-bonn.de/~ralf/frown`.

The bundle includes the sources and the complete documentation (dvi, ps, PDF, and HTML).

##### Requirements

You should be able to build Frown with every Haskell 98-compliant compiler. You have to use a not too ancient compiler as there have been some changes to the Haskell language in Sep. 2001 (GHC 5.02 and later versions will do).
The Haskell interpreter Hugs 98 is needed for running the testsuite.
Various tools are required to generate the documentation from scratch: `lhs2TeX`, LATEX, functional , HEVEA and HACHA. Note, however, that the bundle already includes the complete documentation.

##### Installation

Unzip and untar the bundle. This creates a directory called `Frown`. Enter this directory.

`ralf> tar xzf frown.tar.gz`
`ralf> cd Frown`

The documentation resides in the directory `Manual`; example grammars can be found in `Examples` and `Manual/Examples` (the files ending in `.g` and `.lg`).
You can install Frown using either traditional makefiles or Cabal.

##### Using makefiles

Optionally, edit the `Makefile` to specify destinations for the binary and the documentation (this information is only used by `make install`). Now, you can trigger

`ralf/Frown> make`

which compiles Frown generating an executable called `frown` (to use Frown you only need this executable). Optionally, continue with

`ralf/Frown> make install`

to install the executable and the documentation.
For reference, here is a list of possible targets:

`make`
  Compiles Frown generating an executable called `frown` (to use Frown you only need this executable).
`make install`
  Compiles Frown and installs the executable and the documentation.
`make test`
  Runs the testsuite.1
`make man`
  Generates the documentation in various formats (dvi, ps, PDF, and HTML).
`make clean`
  Removes some temporary files.
`make distclean`
  Removes all files except the ones that are included in the distribution.

##### Using Cabal

Alternatively, you can build Frown using Cabal (version 1.1.3 or later), Haskell's Common Architecture for Building Applications and Libraries.
For a global install, type:

`ralf/Frown> runhaskell Setup.hs configure --ghc`
`ralf/Frown> runhaskell Setup.hs build`
`ralf/Frown> runhaskell Setup.hs install`

If you want to install Frown locally, use (you may wish to replace `$HOME` by a directory of your choice):

`ralf/Frown> runhaskell Setup.hs configure --ghc --prefix=$HOME`
`ralf/Frown> runhaskell Setup.hs build`
`ralf/Frown> runhaskell Setup.hs install --user`

##### Usage

The call

`ralf/Frown> frown -h`

displays the various options. For more information consult this manual.

## 1.2 Reporting bugs

Bug reports should be send to Ralf Hinze (`ralf@cs.uni-bonn.de`). The report should include all information necessary to reproduce the bug: the compiler used to compile Frown, the grammar source file (and possibly auxiliary Haskell source files), and the command-line invocation of Frown.
Suggestions for improvements or request for features should also be sent to the above address.

## 1.3 License

Frown is distributed under the GNU general public licence (version 2).

    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    %                                                                             %
    %   Frown --- An LALR(k) parser generator for Haskell 98                      %
    %   Copyright (C) 2001-2005 Ralf Hinze                                        %
    %                                                                             %
    %   This program is free software; you can redistribute it and/or modify      %
    %   it under the terms of the GNU General Public License (version 2) as       %
    %   published by the Free Software Foundation.                                %
    %                                                                             %
    %   This program is distributed in the hope that it will be useful,           %
    %   but WITHOUT ANY WARRANTY; without even the implied warranty of            %
    %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the             %
    %   GNU General Public License for more details.                              %
    %                                                                             %
    %   You should have received a copy of the GNU General Public License         %
    %   along with this program; see the file COPYING.  If not, write to          %
    %   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,          %
    %   Boston, MA 02111-1307, USA.                                               %
    %                                                                             %
    %   Contact information                                                       %
    %   Email:      Ralf Hinze <ralf@cs.uni-bonn.de>                              %
    %   Homepage:   http://www.informatik.uni-bonn.de/~ralf/                      %
    %   Paper mail: Dr. Ralf Hinze                                                %
    %               Institut für Informatik III                                   %
    %               Universität Bonn                                              %
    %               Römerstraße 164                                               %
    %               53117 Bonn, Germany                                           %
    %                                                                             %
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

## 1.4 Credits

Frown wouldn't have seen the light of day without the work of Ross Paterson and Doaitse Swierstra. Ross invoked my interest in LR parsing and he devised the `--code=stackless` and `--code=gvstack` output formats. Doaitse invented the `--code=standard` format, which was historically the first format Frown supported.
A big thank you goes to Andres Löh and Ross Paterson for various bug reports and suggestions for improvement.

1
  There are some known problems. The format `code=stackless` behaves differently for `Loop.g` (the generated parser is less strict than the standard one). Also, `Empty.g` does not work yet. Finally, error reports may differ for different formats and for optimized and unoptimized versions (as some parsers perform additional reductions before an error is reported).