git.iko.soy/typeable/aeson
on 0.6.1.0 help sign in
typeable/aeson/release-notes.markdown
113 lines 3.9 kB history raw
1# 0.6 series
3Much improved documentation.
5Angle brackets are now escaped in JSON strings, to help avoid XSS
6attacks.
8Fixed up handling of nullary constructors when using generic encoding.
10Added ToJSON/FromJSON instances for:
12* The `Fixed` class
14* ISO-8601 dates: `UTCTime`, `ZonedTime`, and `TimeZone`
16Added accessor functions for inspecting `Value`s.
18Added `eitherDecode` function that returns an error message if
19decoding fails.
21# 0.5 to 0.6
23This release introduces a slightly obscure, but
24backwards-incompatible, change.
26In the generic APIs of versions 0.4 and 0.5, fields whose names began
27with a "`_`" character would have this character removed. This no
28longer occurs, as [it was both buggy and
29surprising](https://github.com/bos/aeson/issues/53).
31Also:
33* Fixed [a bug in generic decoding of nullary constructors](https://github.com/bos/aeson/issues/62)
35# 0.4 to 0.5
37When used with the UTF-8 encoding performance improvements introduced
38in version 0.11.1.12 of the text package, this release improves
39aeson's JSON encoding performance by 33% relative to aeson 0.4.
41As part of achieving this improvement, an API change was necessary.
42The `fromValue` function in the `Data.Aeson.Encode` module now uses
43the text package's `Builder` type instead of the blaze-builder
44package's `Builder` type.
46# 0.3 to 0.4
48## Ease of use
50The new [`decode`
51function](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson.html#v:decode)
52complements the longstanding `encode` function, and makes the API
53simpler.
55[New examples](https://github.com/bos/aeson/tree/master/examples) make
56it easier to learn to use the package.
59## Generics support
61aeson's support for data-type generic programming makes it possible to
62use JSON encodings of most data types without writing any boilerplate
63instances.
65Thanks to Bas Van Dijk, aeson now supports the two major schemes for
66doing datatype-generic programming:
68* the modern mechanism, [built into GHC
69 itself](http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
71* the older mechanism, based on SYB (aka "scrap your boilerplate")
73The modern GHC-based generic mechanism is fast and terse: in fact, its
74performance is generally comparable in performance to hand-written and
75TH-derived `ToJSON` and `FromJSON` instances. To see how to use GHC
76generics, refer to
77[`examples/Generic.hs`](https://github.com/bos/aeson/blob/master/examples/Generic.hs).
79The SYB-based generics support lives in
80[Data.Aeson.Generic](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson-Generic.html),
81and is provided mainly for users of GHC older than 7.2. SYB is far
82slower (by about 10x) than the more modern generic mechanism. To see
83how to use SYB generics, refer to
84[`examples/GenericSYB.hs`](https://github.com/bos/aeson/blob/master/examples/GenericSYB.hs).
87## Improved performance
89* We switched the intermediate representation of JSON objects from
90 `Data.Map` to
91 [`Data.HashMap`](http://hackage.haskell.org/package/unordered-containers),
92 which has improved type conversion performance.
94* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and
95 70% faster than in 0.3.
98## Evaluation control
100This version of aeson makes explicit the decoupling between
101*identifying* an element of a JSON document and *converting* it to
102Haskell. See the
103[`Data.Aeson.Parser`](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson-Parser.html)
104documentation for details.
106The normal aeson `decode` function performs identification strictly,
107but defers conversion until needed. This can result in improved
108performance (e.g. if the results of some conversions are never
109needed), but at a cost in increased memory consumption.
111The new `decode'` function performs identification and conversion
112immediately. This incurs an up-front cost in CPU cycles, but reduces
113reduce memory consumption.