@@ -16,6 +16,9 @@ module Data.Aeson
16 -- * How to use this library
16 -- * How to use this library
19+ -- ** Writing instances by hand
19 -- ** Working with the AST
22 -- ** Working with the AST
@@ -25,9 +28,6 @@ module Data.Aeson
25 -- ** Decoding a mixed-type object
28 -- ** Decoding a mixed-type object
31 -- * Encoding and decoding
31 -- * Encoding and decoding
32 -- $encoding_and_decoding
32 -- $encoding_and_decoding
@@ -169,20 +169,55 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
171-- This section contains basic information on the different ways to
171-- 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
173-- inflexible, to complex but flexible.
173-- inflexible, to complex but flexible.
175-- The most common way to use the library is to define a data type,
175-- The most common way to use the library is to define a data type,
176-- corresponding to some JSON data you want to work with, and then
176-- corresponding to some JSON data you want to work with, and then
177-- write either a 'FromJSON' instance, a to 'ToJSON' instance, or both
177-- write either a 'FromJSON' instance, a to 'ToJSON' instance, or both
178−-- for that type. For example, given this JSON data:
180+-- For example, given this JSON data:
180-- > { "name": "Joe", "age": 12 }
182-- > { "name": "Joe", "age": 12 }
182-- we create a matching data type:
184-- we create a matching data type:
186+-- > {-# LANGUAGE DeriveGeneric #-}
188+-- > import GHC.Generics
184−-- > data Person = Person
190+-- > data Person = Person {
193+-- > } deriving (Generic, Show)
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.
199+-- > instance ToJSON Person
200+-- > instance FromJSON Person
202+-- We can now encode a value like so:
204+-- > >>> encode (Person {name = "Joe", age = 12})
205+-- > "{\"name\":\"Joe\",\"age\":12}"
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:
214+-- > { "name": "Joe", "age": 12 }
216+-- We once again create a matching data type, without bothering to add
217+-- a 'Generic' instance this time:
219+-- > data Person = Person {
185−-- > { name :: Text
220+-- > name :: Text
186-- > , age :: Int
221-- > , age :: Int
187-- > } deriving Show
222-- > } deriving Show
@@ -195,7 +230,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
195-- > v .: "name" <*>
230-- > v .: "name" <*>
196-- > v .: "age"
231-- > v .: "age"
197-- > -- A non-Object value is of the wrong type, so fail.
232-- > -- A non-Object value is of the wrong type, so fail.
198−-- > parseJSON _ = mzero
233+-- > parseJSON _ = empty
200-- We can now parse the JSON data like so:
235-- We can now parse the JSON data like so:
@@ -205,7 +240,13 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
205-- To encode data, we need to define a 'ToJSON' instance:
240-- To encode data, we need to define a 'ToJSON' instance:
207-- > instance ToJSON Person where
242-- > instance ToJSON Person where
243+-- > -- this generates a Value
244+-- > toJSON (Person name age) =
208−-- > toJSON (Person name age) = object ["name" .= name, "age" .= age]
245+-- > object ["name" .= name, "age" .= age]
247+-- > -- this encodes directly to a ByteString Builder
248+-- > toEncoding (Person name age) =
249+-- > series $ "name" .= name <> "age" .= age
210-- We can now encode a value like so:
251-- We can now encode a value like so:
@@ -231,7 +272,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
231-- expectations.)
272-- expectations.)
233-- See the documentation of 'FromJSON' and 'ToJSON' for some examples
274-- 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
235-- circumstances.
276-- circumstances.
@@ -254,8 +295,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
255-- $haskell
296-- $haskell
257−-- Any instance of 'FromJSON' can be specified (but see the
298+-- We can decode to any instance of 'FromJSON':
258−-- \"Pitfalls\" section here—"Data.Aeson#pitfalls"):
260-- > λ> decode "[1,2,3]" :: Maybe [Int]
300-- > λ> decode "[1,2,3]" :: Maybe [Int]
261-- > Just [1,2,3]
301-- > Just [1,2,3]
@@ -264,7 +304,7 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
264-- can use them directly. For example, use the 'Data.Map.Map' type to
304-- can use them directly. For example, use the 'Data.Map.Map' type to
265-- get a map of 'Int's.
305-- get a map of 'Int's.
267−-- > λ> :m + Data.Map
307+-- > λ> import Data.Map
268-- > λ> decode "{\"foo\":1,\"bar\":2}" :: Maybe (Map String Int)
308-- > λ> decode "{\"foo\":1,\"bar\":2}" :: Maybe (Map String Int)
269-- > Just (fromList [("bar",2),("foo",1)])
309-- > Just (fromList [("bar",2),("foo",1)])
@@ -299,54 +339,24 @@ eitherDecodeStrict' = eitherFormatError . eitherDecodeStrictWith jsonEOF' fromJS
299-- upside is that you have complete control over the way the JSON is
339-- upside is that you have complete control over the way the JSON is
300-- parsed.
340-- parsed.
302−-- $pitfalls
342+-- $encoding_and_decoding
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
311−-- > >>> decode "1" :: Maybe Int
313−-- > >>> decode "1" :: Maybe String
316−-- So stick to objects (e.g. maps in Haskell) or arrays (lists or
317−-- vectors in Haskell):
319−-- > >>> decode "[1,2,3]" :: Maybe [Int]
344+-- Decoding is a two-step process.
322−-- When encoding to JSON you can encode anything that's an instance of
346+-- * When decoding a value, the process is reversed: the bytes are
323−-- 'ToJSON', and this may include simple types. So beware that this
347+-- converted to a 'Value', then the 'FromJSON' class is used to
324−-- aspect of the API is not isomorphic. You can round-trip arrays and
348+-- convert to the desired type.
325−-- maps, but not simple values:
327−-- > >>> encode [1,2,3]
329−-- > >>> decode (encode [1]) :: Maybe [Int]
333−-- > >>> decode (encode (1 :: Int)) :: Maybe Int
336−-- Alternatively, see 'Data.Aeson.Parser.value' to parse non-top-level
339−-- $encoding_and_decoding
341−-- Encoding and decoding are each two-step processes.
350+-- There are two ways to encode a value.
343−-- * To encode a value, it is first converted to an abstract syntax
352+-- * Convert to a 'Value' using 'toJSON', then possibly further
344−-- tree (AST), using 'ToJSON'. This generic representation is then
353+-- encode. This was the only method available in aeson 0.9 and
345−-- encoded as bytes.
354+-- earlier.
347−-- * When decoding a value, the process is reversed: the bytes are
356+-- * Directly encode (to what will become a 'L.ByteString') using
348−-- converted to an AST, then the 'FromJSON' class is used to convert
357+-- 'toEncoding'. This is much more efficient (about 3x faster, and
349−-- to the desired type.
358+-- less memory intensive besides), but is only available in aeson
351-- For convenience, the 'encode' and 'decode' functions combine both
361-- For convenience, the 'encode' and 'decode' functions combine both