@@ -16,8 +16,8 @@ module Data.Aeson
1616 -- * How to use this library
1717 -- $use
1818
19− -- ** Basic use
20− -- $basic
19+ -- ** Working with the AST
20+ -- $ast
2121
2222 -- ** Decoding to a Haskell value
2323 -- $haskell
@@ -32,6 +32,7 @@ module Data.Aeson
3232 -- $pitfalls
3333
3434 -- * Encoding and decoding
35+ -- $encoding_and_decoding
3536 decode
3637 , decode'
3738 , eitherDecode
@@ -106,31 +107,85 @@ eitherDecode' = eitherDecodeWith json' fromJSON
106107-- decode data using this library. These range from simple but
107108-- inflexible, to complex but flexible.
108109--
110+-- The most common way to use the library is to define a data type,
111+-- corresponding to some JSON data you want to work with, and then
112+-- write either a 'FromJSON' instance, a to 'ToJSON' instance, or both
113+-- for that type. For example, given this JSON data:
114+--
115+-- > { "name": "Joe", "age": 12 }
116+--
117+-- we create a matching data type:
118+--
119+-- > data Person = Person
120+-- > { name :: Text
121+-- > , age :: Int
122+-- > } deriving Show-
123+--
124+-- To decode data, we need to define a 'FromJSON' instance:
125+--
126+-- > {-# LANGUAGE OverloadedStrings #-}
127+-- >
128+-- > instance FromJSON Coord where
129+-- > parseJSON (Object v) = Person <$>
130+-- > v .: "name" <*>
131+-- > v .: "age"
132+-- > -- A non-Object value is of the wrong type, so fail.
133+-- > parseJSON _ = mzero
134+--
135+-- We can now parse the JSON data like so:
136+--
137+-- > >>> decode "{\"name\":\"Joe\",\"age\":12}" :: Maybe Person
138+-- > Just (Person {name = "Joe", age = 12})
139+--
140+-- To encode data, we need to define a 'ToJSON' instance:
141+--
142+-- > instance ToJSON Person where
143+-- > toJSON (Person name age) = object ["name" .= name, "age" .= age]
144+--
145+-- We can now encode a value like so:
146+--
147+-- > >>> encode (Person {name = "Joe", age = 12})
148+-- > "{\"name\":\"Joe\",\"age\":12}"
149+--
150+-- There are predefined 'FromJSON' and 'ToJSON' instances for many
151+-- types. Here's an example using lists and 'Int's:
152+--
153+-- > >>> decode "[1,2,3]" :: Maybe [Int]
154+-- > Just [1,2,3]
155+--
156+-- And here's an example using the 'Data.Map.Map' type to get a map of
157+-- 'Int's.
158+--
159+-- > >>> decode "{\"foo\":1,\"bar\":2}" :: Maybe (Map String Int)
160+-- > Just (fromList [("bar",2),("foo",1)])
161+
109162-- While the notes below focus on decoding, you can apply almost the
110163-- same techniques to /encoding/ data. (The main difference is that
111164-- encoding always succeeds, but decoding has to handle the
112165-- possibility of failure, where an input doesn't match our
113166-- expectations.)
167+--
168+-- See the documentation of 'FromJSON' and 'ToJSON' for some examples
169+-- of how you can automatically derive instances in some
170+-- circumstances.
114171
115−-- $basic
172+-- $ast
116173--
117−-- To parse JSON into something useful, everything goes through the
118−-- 'decode' function, which is polymorphic on the 'FromJSON'
119−-- class. For representing arbitrary JSON values, there is a 'Value'
120−-- type, which is an instance of 'FromJSON'. For example:
174+-- Sometimes you want to work with JSON data directly, without first
175+-- converting it to a custom data type. This can be useful if you want
176+-- to e.g. convert JSON data to YAML data, without knowing what the
177+-- contents of the original JSON data was. The 'Value' type, which is
178+-- an instance of 'FromJSON', is used to represent an arbitrary JSON
179+-- AST (abstract syntax tree). Example usage:
121180--
122−-- > λ> decode "{\"foo\":123}" :: Maybe Value
181+-- > >>> decode "{\"foo\": 123}" :: Maybe Value
123182-- > Just (Object (fromList [("foo",Number 123)]))
124−-- > λ> decode "{\"foo\":[\"abc\",\"def\"]}" :: Maybe Value
183+--
184+-- > >>> decode "{\"foo\": [\"abc\",\"def\"]}" :: Maybe Value
125185-- > Just (Object (fromList [("foo",Array (fromList [String "abc",String "def"]))]))
126186--
127−-- To run these examples, you need to enable @OverloadedStrings@ (in
128−-- GHCi you can write @:set -XOverloadedStrings@) so that you can use
129−-- string literals for non-'String' types. We're using (the lazy
130−-- version of) 'Data.ByteString.Lazy.ByteString'. (This requires at
131−-- least version 0.9.0.4 of the bytestring package to provide the
132−-- 'Data.String.IsString' instance. You almost certainly have a
133−-- suitably recent version of the library installed.)
187+-- Once you have a 'Value' you can write functions to traverse it and
188+-- make arbitrary transformations.
134189
135190-- $haskell
136191--
@@ -214,33 +269,50 @@ eitherDecode' = eitherDecodeWith json' fromJSON
214269-- $pitfalls
215270-- #pitfalls#
216271--
217−-- For historical reasons, the JSON standard requires the outermost
218−-- (topmost) value in a structure to be an array or object. Calling
219−-- 'decode' on a simple type will typecheck, but will never succeed:
272+-- Note that the JSON standard only allows arrays or objects of things
273+-- at the top-level. Since this library follows the standard, calling
274+-- 'decode' on an unsupported result type will typecheck, but will
275+-- always \"fail\":
220276--
221−-- > λ> decode "1" :: Maybe Int
277+-- > >>> decode "1" :: Maybe Int
222278-- > Nothing
223−-- > λ> decode "1" :: Maybe String
279+-- > >>> decode "1" :: Maybe String
224280-- > Nothing
225281--
226282-- So stick to objects (e.g. maps in Haskell) or arrays (lists or
227283-- vectors in Haskell):
228284--
229−-- > λ> decode "[1,2,3]" :: Maybe [Int]
285+-- > >>> decode "[1,2,3]" :: Maybe [Int]
230286-- > Just [1,2,3]
231287--
232−-- Likewise, for encoding to JSON you can encode anything that's an
233−-- instance of 'ToJSON', and this may include simple types. So beware
234−-- that this aspect of the API is not isomorphic:
288+-- When encoding to JSON you can encode anything that's an instance of
289+-- 'ToJSON', and this may include simple types. So beware that this
290+-- aspect of the API is not isomorphic. You can round-trip arrays and
291+-- maps, but not simple values:
235292--
236−-- > λ> encode [1,2,3]
293+-- > >>> encode [1,2,3]
237294-- > "[1,2,3]"
238−-- > λ> decode (encode [1]) :: Maybe [Int]
295+-- > >>> decode (encode [1]) :: Maybe [Int]
239296-- > Just [1]
240−-- > λ> encode 1
297+-- > >>> encode 1
241298-- > "1"
242−-- > λ> decode (encode (1 :: Int)) :: Maybe Int
299+-- > >>> decode (encode (1 :: Int)) :: Maybe Int
243300-- > Nothing
244301--
245−-- Alternatively, see 'Data.Aeson.Parser.value' for functions to parse
246−-- non-top-level JSON values.
302+-- Alternatively, see 'Data.Aeson.Parser.value' to parse non-top-level
303+-- JSON values.
304+
305+-- $encoding_and_decoding
306+--
307+-- Encoding and decoding are each two-step processes.
308+--
309+-- * To encode a value, it is first converted to an abstract syntax
310+-- tree (AST), using 'ToJSON'. This generic representation is then
311+-- encoded as bytes.
312+--
313+-- * When decoding a value, the process is reversed: the bytes are
314+-- converted to an AST, then the 'FromJSON' class is used to convert
315+-- to the desired type.
316+--
317+-- For convenience, the 'encode' and
318+-- 'decode' functions combine both steps for convenience.