# Welcome to blaze-textual

blaze-textual is a fast Haskell library for rendering common Haskell
datatypes in text form using the
[blaze-builder](http://hackage.haskell.org/package/blaze-builder)
library.

# Important note for users of GHCi and Template Haskell

To achieve excellent performance for rendering floating point numbers,
this package uses the
[double-conversion](http://hackage.haskell.org/package/double-conversion)
package.

Unfortunately, due to bugs in GHC, some uses of GHCi and Template
Haskell can crash if this package is loaded.

* [5289: Can't use ghci with a library linked against
  libstdc++](http://hackage.haskell.org/trac/ghc/ticket/5289) (fixed
  in GHC 7.2.1).

* [5386: GHCi crashes with SIGFPE when using double-conversion
  package](http://hackage.haskell.org/trac/ghc/ticket/5386) (not yet
  fixed at the time of writing)

If you are affected by these problems, you should expect the 5289
crash to look like this:

    Loading package double-conversion-0.2.0.0 ... can't load .so/.DLL for: stdc++

The 5386 crash causes GHCi to die with a floating point exception
(SIGFPE).

To work around these bugs, this package includes an alternative,
slower, floating point conversion that is written in pure Haskell.
Because it is 10 times slower than the double-conversion package, it
is not the default.

To use it, reinstall this package by passing the `native` flag to
`cabal`:

    cabal install -fnative

Afterwards, you will also need to reinstall any downstream packages
that depend on this one, e.g. the [aeson JSON
library](http://hackage.haskell.org/package/aeson):

    cabal install aeson --reinstall

# Join in!

We are happy to receive bug reports, fixes, documentation
enhancements, and other improvements.

Please report bugs via the
[github issue tracker](http://github.com/mailrank/blaze-textual/issues).

Master [git repository](http://github.com/mailrank/blaze-textual):

* `git clone git://github.com/mailrank/blaze-textual.git`

There's also a [Mercurial mirror](http://bitbucket.org/bos/blaze-textual):

* `hg clone http://bitbucket.org/bos/blaze-textual`

(You can create and contribute changes using either git or Mercurial.)

Authors
-------

This library is written and maintained by Bryan O'Sullivan,
<bos@mailrank.com>.