The only changes are added instances.
This release should be close to backwards compatible with aeson 0.9.
If you are upgrading from aeson 0.10 it might be easier to go back in
history to the point you were still using 0.9.
-
The ToJSON class has a new method, toEncoding, that allows
direct encoding from a Haskell value to a lazy bytestring without
construction of an intermediate Value.
The performance benefits of direct encoding are significant: more
than 2x faster than before, with less than 1/3 the memory usage.
To preserve API compatibility across upgrades from older versions of
this library, the default implementation of toEncoding uses
toJSON. You will not see any performance improvement unless you
write an implementation of toEncoding, which can be very simple:
instance ToJSON Coord where
toEncoding = genericToEncoding defaultOptions
(Behind the scenes, the encode function uses toEncoding now, so
if you implement toEncoding for your types, you should see a
speedup immediately.)
If you use Template Haskell or GHC Generics to auto-generate your
ToJSON instances, you’ll benefit from fast toEncoding
implementations for free!
-
When converting from a Value to a target Haskell type, FromJSON
instances now provide much better error messages, including a
complete JSON path from the root of the object to the offending
element. This greatly eases debugging.
-
It is now possible to use Template Haskell to generate FromJSON
and ToJSON instances for types in data families.
-
If you use Template Haskell or generics, and used to use the
camelTo function to rename fields, the new camelTo2 function is
smarter. For example, camelTo will rename CamelAPICase to
camelapi_case (ugh!), while camelTo2 will map it to
camel_api_case (yay!).
-
New ToJSON and FromJSON instances for the following time-related
types: Day, LocalTime.
-
FromJSON UTCTime parser accepts the same values as for ZonedTime,
but converts any time zone offset into a UTC time.
-
The Result type is now an instance of Foldable and Traversable.
-
The Data.Aeson.Generic module has been removed. It was deprecated in
late 2013.
-
GHC 7.2 and older are no longer supported.
-
The instance of Monad for the Result type lacked an implementation
of fail (oops). This has been corrected.
-
Semantics of (.:?) operator are changed. It’s doesn’t anymore accept
present Null value.
-
Added (Foldable t, ToJSON a) => ToJSON (t a) overlappable instance.
You might see No instance for (Foldable YourPolymorphicType) arising from a use of ‘.=’ -errors due this change.
-
Encoding a Scientific value with a huge exponent is now handled
efficiently. (This would previously allocate a huge
arbitrary-precision integer, potentially leading to a denial of
service.)
-
Handling of strings that contain backslash escape sequences is
greatly improved. For a pathological string containing almost a
megabyte of consecutive backslashes, the new implementation is 27x
faster and uses 42x less memory.
-
The ToJSON instance for UTCTime is rendered with higher
(picosecond) resolution.
-
The value parser now correctly handles leading whitespace.
-
New instances of ToJSON and FromJSON for Data.Sequence and
Data.Functor.Identity. The Value type now has a Read instance.
-
ZonedTime parser ordering now favours the standard JSON format,
increasing efficiency in the common case.
-
Encoding to a Text.Builder now escapes '<' and '>' characters,
to reduce XSS risk.
-
The new decode function complements the longstanding encode
function, and makes the API simpler.
-
New examples make it easier to learn to use the package
(https://github.com/bos/aeson/tree/master/examples).
-
Generics support
aeson’s support for data-type generic programming makes it
possible to use JSON encodings of most data types without writing
any boilerplate instances.
Thanks to Bas Van Dijk, aeson now supports the two major schemes
for doing datatype-generic programming:
The modern GHC-based generic mechanism is fast and terse: in fact,
its performance is generally comparable in performance to
hand-written and TH-derived ToJSON and FromJSON instances. To
see how to use GHC generics, refer to examples/Generic.hs.
The SYB-based generics support lives in Data.Aeson.Generic and is
provided mainly for users of GHC older than 7.2. SYB is far slower
(by about 10x) than the more modern generic mechanism. To see how
to use SYB generics, refer to examples/GenericSYB.hs.
-
We switched the intermediate representation of JSON objects from
Data.Map to Data.HashMap which has improved type conversion
performance.
-
Instances of ToJSON and FromJSON for tuples are between 45% and 70%
faster than in 0.3.
-
Evaluation control
This version of aeson makes explicit the decoupling between
identifying an element of a JSON document and converting it to
Haskell. See the Data.Aeson.Parser documentation for details.
The normal aeson decode function performs identification
strictly, but defers conversion until needed. This can result in
improved performance (e.g. if the results of some conversions are
never needed), but at a cost in increased memory consumption.
The new decode' function performs identification and conversion
immediately. This incurs an up-front cost in CPU cycles, but
reduces reduce memory consumption.
