@@ -16,6 +16,9 @@ module Data.Aeson
1616 -- * How to use this library
1717 -- $use
1818
19+ -- ** Writing instances by hand
20+ -- $manual
21+
1922 -- ** Working with the AST
2023 -- $ast
2124
@@ -25,9 +28,6 @@ module Data.Aeson
2528 -- ** Decoding a mixed-type object
2629 -- $mixed
2730
28− -- ** Pitfalls
29− -- $pitfalls
30−
3131 -- * Encoding and decoding
3232 -- $encoding_and_decoding
3333 decode
@@ -169,20 +169,55 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
169169-- $use
170170--
171171-- This section contains basic information on the different ways to
172−-- decode data using this library. These range from simple but
172+-- work with data using this library. These range from simple but
173173-- inflexible, to complex but flexible.
174174--
175175-- The most common way to use the library is to define a data type,
176176-- corresponding to some JSON data you want to work with, and then
177177-- write either a 'FromJSON' instance, a to 'ToJSON' instance, or both
178−-- for that type. For example, given this JSON data:
178+-- for that type.
179+--
180+-- For example, given this JSON data:
179181--
180182-- > { "name": "Joe", "age": 12 }
181183--
182184-- we create a matching data type:
183185--
184−-- > data Person = Person
185−-- > { name :: Text
186+-- > {-# LANGUAGE DeriveGeneric #-}
187+-- >
188+-- > import GHC.Generics
189+-- >
190+-- > data Person = Person {
191+-- > name :: Text
192+-- > , age :: Int
193+-- > } deriving (Generic, Show)
194+--
195+-- The @LANGUAGE@ pragma and 'Generic' instance let us write empty
196+-- 'FromJSON' and 'ToJSON' instances for which the compiler will
197+-- generate sensible default implementations.
198+--
199+-- > instance ToJSON Person
200+-- > instance FromJSON Person
201+--
202+-- We can now encode a value like so:
203+--
204+-- > >>> encode (Person {name = "Joe", age = 12})
205+-- > "{\"name\":\"Joe\",\"age\":12}"
206+
207+-- $manual
208+--
209+-- When necessary, we can write 'ToJSON' and 'FromJSON' instances by
210+-- hand. This is valuable when the JSON-on-the-wire and Haskell data
211+-- are different or otherwise need some more carefully managed
212+-- translation. Let's revisit our JSON data:
213+--
214+-- > { "name": "Joe", "age": 12 }
215+--
216+-- We once again create a matching data type, without bothering to add
217+-- a 'Generic' instance this time:
218+--
219+-- > data Person = Person {
220+-- > name :: Text
186221-- > , age :: Int
187222-- > } deriving Show
188223--
@@ -195,7 +230,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
195230-- > v .: "name" <*>
196231-- > v .: "age"
197232-- > -- A non-Object value is of the wrong type, so fail.
198−-- > parseJSON _ = mzero
233+-- > parseJSON _ = empty
199234--
200235-- We can now parse the JSON data like so:
201236--
@@ -205,7 +240,13 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
205240-- To encode data, we need to define a 'ToJSON' instance:
206241--
207242-- > instance ToJSON Person where
208−-- > toJSON (Person name age) = object ["name" .= name, "age" .= age]
243+-- > -- this generates a Value
244+-- > toJSON (Person name age) =
245+-- > object ["name" .= name, "age" .= age]
246+-- >
247+-- > -- this encodes directly to a ByteString Builder
248+-- > toEncoding (Person name age) =
249+-- > series $ "name" .= name <> "age" .= age
209250--
210251-- We can now encode a value like so:
211252--
@@ -231,7 +272,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
231272-- expectations.)
232273--
233274-- See the documentation of 'FromJSON' and 'ToJSON' for some examples
234−-- of how you can automatically derive instances in some
275+-- of how you can automatically derive instances in many common
235276-- circumstances.
236277
237278-- $ast
@@ -254,8 +295,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
254295
255296-- $haskell
256297--
257−-- Any instance of 'FromJSON' can be specified (but see the
258−-- \"Pitfalls\" section here—"Data.Aeson#pitfalls"):
298+-- We can decode to any instance of 'FromJSON':
259299--
260300-- > λ> decode "[1,2,3]" :: Maybe [Int]
261301-- > Just [1,2,3]
@@ -264,7 +304,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
264304-- can use them directly. For example, use the 'Data.Map.Map' type to
265305-- get a map of 'Int's.
266306--
267−-- > λ> :m + Data.Map
307+-- > λ> import Data.Map
268308-- > λ> decode "{\"foo\":1,\"bar\":2}" :: Maybe (Map String Int)
269309-- > Just (fromList [("bar",2),("foo",1)])
270310
@@ -299,54 +339,24 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
299339-- upside is that you have complete control over the way the JSON is
300340-- parsed.
301341
302−-- $pitfalls
303−-- #pitfalls#
304−--
305−-- Note that the JSON standard requires that the top-level value be
306−-- either an array or an object. If you try to use 'decode' with a
307−-- result type that is /not/ represented in JSON as an array or
308−-- object, your code will typecheck, but it will always \"fail\" at
309−-- runtime:
310−--
311−-- > >>> decode "1" :: Maybe Int
312−-- > Nothing
313−-- > >>> decode "1" :: Maybe String
314−-- > Nothing
315−--
316−-- So stick to objects (e.g. maps in Haskell) or arrays (lists or
317−-- vectors in Haskell):
342+-- $encoding_and_decoding
318343--
319−-- > >>> decode "[1,2,3]" :: Maybe [Int]
320−-- > Just [1,2,3]
344+-- Decoding is a two-step process.
321345--
322−-- When encoding to JSON you can encode anything that's an instance of
323−-- 'ToJSON', and this may include simple types. So beware that this
324−-- aspect of the API is not isomorphic. You can round-trip arrays and
325−-- maps, but not simple values:
326−--
327−-- > >>> encode [1,2,3]
328−-- > "[1,2,3]"
329−-- > >>> decode (encode [1]) :: Maybe [Int]
330−-- > Just [1]
331−-- > >>> encode 1
332−-- > "1"
333−-- > >>> decode (encode (1 :: Int)) :: Maybe Int
334−-- > Nothing
335−--
336−-- Alternatively, see 'Data.Aeson.Parser.value' to parse non-top-level
337−-- JSON values.
338−
339−-- $encoding_and_decoding
346+-- * When decoding a value, the process is reversed: the bytes are
347+-- converted to a 'Value', then the 'FromJSON' class is used to
348+-- convert to the desired type.
340349--
341−-- Encoding and decoding are each two-step processes.
350+-- There are two ways to encode a value.
342351--
343−-- * To encode a value, it is first converted to an abstract syntax
344−-- tree (AST), using 'ToJSON'. This generic representation is then
345−-- encoded as bytes.
352+-- * Convert to a 'Value' using 'toJSON', then possibly further
353+-- encode. This was the only method available in aeson 0.9 and
354+-- earlier.
346355--
347−-- * When decoding a value, the process is reversed: the bytes are
348−-- converted to an AST, then the 'FromJSON' class is used to convert
349−-- to the desired type.
356+-- * Directly encode (to what will become a 'L.ByteString') using
357+-- 'toEncoding'. This is much more efficient (about 3x faster, and
358+-- less memory intensive besides), but is only available in aeson
359+-- 0.10 and newer.
350360--
351361-- For convenience, the 'encode' and 'decode' functions combine both
352362-- steps.