[Haskell-cafe] ANNOUNCE: waargonaut- (better mousetrap)

Sean Chalmers sean.chalmers at data61.csiro.au
Fri Feb 22 04:59:51 UTC 2019

## Waargonaut

This release of Waargonaut sees several issues fixed and a generous 
helping of
cleanups and refactoring. This is a breaking change as the API has been
drastically altered for some parts. Other changes include more granular 
and generalisation.

### Bug fixes

- Unicode was not being handled correctly, sometimes. The 
encoding/decoding to a
   `Text` or `String` value wasn't correct due to my own lack of 
- Upper-case hexadecimal input was being silently zeroed out during some
   conversion steps.

Those issues should all be resolved now. In the process of fixing those 
it tugged on a couple of threads for things I've been wanting to do. So 
I did
them, see below:

### Changes:

#### Decoding!

Using `parseWith` and the requirement to DIY almost an entire parsing 
is a thing of the past. Replaced with the following structure:

- `decodeWith`
- `decodeFromText`
- `decodeFromString`
- `decodeFromByteString`
- `decodeWithInput`
- as well as their pure variants

These functions only require you provide a function from the respective 
type and has an implementation of the `CharParsing` interface. The greatly
simplifies the process of providing your own parsing function.

#### Default Parsing Functions!

Waargonaut now provides some default parsing functions using the 
package. These are in the `Waargonaut.Attoparsec` module and should make it
easier for people to be up and running with the package when 
requirements of a
custom parser aren't important.

#### New Optics!

The `Waargonaut.Lens` module provides some Prisms for use with the 
`Json` type.
Working in a similar way to the `lens-aeson` package.

These optics are law abiding and they have tests to prove it.

#### Better Builder

To complement the more streamlined parsing functions, the encoder has 
had its
builder internals reworked to support either `Text` or `ByteString`. In the
style of "scrap your typeclasses" to keep things simple.

Added tests to check their output matches.

#### More modules!

- Factored out components into more focused submodules:
   - UnescapedJChar
   - EscapedJChar
   - HexDigit4
   - Elem
   - Elems
   - JAssoc
   - Decode.Runners
   - Builders for all `Json` types now live under 

#### Deprecate Traversal decoder

The decoder in `Waargonaut.Decode.Traversal` has been marked as 
deprecated and
will be removed in a future release. It is bit rotting somewhat compared 
to the
succinct powered decoder and doesn't operate at anywhere near the same 
level of
speed or memory efficiency. If people care they can open an issue to let me

#### Test re-structure

Tests have been reordered into more granular modules. Some tests have been
removed or reworked to be more accurate. More tests have been added to 
try to
protect from regressions. More tests have been added to confirm that various
instances or functions are law abiding. As a consequence there have been 
a few
instances and functions that have been removed.

More information about the Haskell-Cafe mailing list