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