@@ -10,13 +10,114 @@
1010-- Types and functions for working efficiently with JSON data.
1111--
1212-- (A note on naming: in Greek mythology, Aeson was the father of Jason.)
13+
14+module Data.Aeson
15+ (
16+ -- * How to use this library
17+ -- $use
18+
19+ -- ** Basic use
20+ -- $basic
21+
22+ -- ** Decoding to a Haskell value
23+ -- $haskell
24+
25+ -- ** Decoding a mixed-type object
26+ -- $mixed
27+
28+ -- ** Automatically decoding data types
29+ -- $typeable
30+
31+ -- ** Pitfalls
32+ -- $pitfalls
33+
34+ -- * Encoding and decoding
35+ decode
36+ , decode'
37+ , eitherDecode
38+ , eitherDecode'
39+ , encode
40+ -- * Core JSON types
41+ , Value(..)
42+ , Array
43+ , Object
44+ -- * Convenience types
45+ , DotNetTime(..)
46+ -- * Type conversion
47+ , FromJSON(..)
48+ , Result(..)
49+ , fromJSON
50+ , ToJSON(..)
51+ -- * Inspecting @'Value's@
52+ , withObject
53+ , withText
54+ , withArray
55+ , withNumber
56+ , withBool
57+ -- * Constructors and accessors
58+ , (.=)
59+ , (.:)
60+ , (.:?)
61+ , (.!=)
62+ , object
63+ -- * Parsing
64+ , json
65+ , json'
66+ ) where
67+
68+import Data.Aeson.Encode (encode)
69+import Data.Aeson.Parser.Internal (decodeWith, eitherDecodeWith, json, json')
70+import Data.Aeson.Types
71+import qualified Data.ByteString.Lazy as L
72+
73+-- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
74+-- If this fails due to incomplete or invalid input, 'Nothing' is
75+-- returned.
76+--
77+-- This function parses immediately, but defers conversion. See
78+-- 'json' for details.
79+decode :: (FromJSON a) => L.ByteString -> Maybe a
80+decode = decodeWith json fromJSON
81+{-# INLINE decode #-}
82+
83+-- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
84+-- If this fails due to incomplete or invalid input, 'Nothing' is
85+-- returned.
86+--
87+-- This function parses and performs conversion immediately. See
88+-- 'json'' for details.
89+decode' :: (FromJSON a) => L.ByteString -> Maybe a
90+decode' = decodeWith json' fromJSON
91+{-# INLINE decode' #-}
92+
93+-- | Like 'decode' but returns an error message when decoding fails.
94+eitherDecode :: (FromJSON a) => L.ByteString -> Either String a
95+eitherDecode = eitherDecodeWith json fromJSON
96+{-# INLINE eitherDecode #-}
97+
98+-- | Like 'decode'' but returns an error message when decoding fails.
99+eitherDecode' :: (FromJSON a) => L.ByteString -> Either String a
100+eitherDecode' = eitherDecodeWith json' fromJSON
101+{-# INLINE eitherDecode' #-}
102+
103+-- $use
13104--
14−-- /DECODING TO AN ADT ('VALUE')/
105+-- This section contains basic information on the different ways to
106+-- decode data using this library. These range from simple but
107+-- inflexible, to complex but flexible.
108+--
109+-- While the notes below focus on decoding, you can apply almost the
110+-- same techniques to /encoding/ data. (The main difference is that
111+-- encoding always succeeds, but decoding has to handle the
112+-- possibility of failure, where an input doesn't match our
113+-- expectations.)
114+
115+-- $basic
15116--
16117-- To parse JSON into something useful, everything goes through the
17118-- 'decode' function, which is polymorphic on the 'FromJSON'
18−-- class. For representing arbitrary JSON AST there is a 'Value' type,
19−-- which is an instance of 'FromJSON'. For example:
119+-- class. For representing arbitrary JSON values, there is a 'Value'
120+-- type, which is an instance of 'FromJSON'. For example:
20121--
21122-- > λ> decode "{\"foo\":123}" :: Maybe Value
22123-- > Just (Object (fromList [("foo",Number 123)]))
@@ -26,14 +127,15 @@
26127-- To run these examples, you need to enable @OverloadedStrings@ (in
27128-- GHCi you can write @:set -XOverloadedStrings@) so that you can use
28129-- string literals for non-'String' types. We're using (the lazy
29−-- version of) 'Data.ByteString.Lazy.ByteString', which requires at
130+-- version of) 'Data.ByteString.Lazy.ByteString'. (This requires at
30131-- least version 0.9.0.4 of the bytestring package to provide the
31−-- 'Data.String.IsString' instance. You probably have something newer
32−-- than this installed.
33−--
34−-- /DECODING TO HASKELL TYPES/
132+-- 'Data.String.IsString' instance. You almost certainly have a
133+-- suitably recent version of the library installed.)
134+
135+-- $haskell
35136--
36−-- Any instance of 'FromJSON' can be specified (but see the PITFALLS section):
137+-- Any instance of 'FromJSON' can be specified (but see the
138+-- \"Pitfalls\" section here—"Data.Aeson#pitfalls"):
37139--
38140-- > λ> decode "[1,2,3]" :: Maybe [Int]
39141-- > Just [1,2,3]
@@ -45,19 +147,19 @@
45147-- > λ> :m + Data.Map
46148-- > λ> decode "{\"foo\":1,\"bar\":2}" :: Maybe (Map String Int)
47149-- > Just (fromList [("bar",2),("foo",1)])
150+
151+-- $mixed
48152--
49−-- /DECODING A HETEROGENOUS OBJECT/
50−--
51−-- The above approach with maps of course will not work for
52−-- heterogenous objects, so there are a couple of approaches available
53−-- to you.
153+-- The above approach with maps of course will not work for mixed-type
154+-- objects that don't follow a strict schema, but there are a couple
155+-- of approaches available for these.
54156--
55157-- The 'Object' type contains JSON objects:
56158--
57159-- > λ> decode "{\"name\":\"Dave\",\"age\":2}" :: Maybe Object
58160-- > Just (fromList) [("name",String "Dave"),("age",Number 2)]
59161--
60−-- And you extract values from it with a parser using 'parse',
162+-- You can extract values from it with a parser using 'parse',
61163-- 'parseEither' or, in this example, 'parseMaybe':
62164--
63165-- > λ> do result <- decode "{\"name\":\"Dave\",\"age\":2}"
@@ -73,13 +175,13 @@
73175-- documentation in 'FromJSON' for how to implement this class for
74176-- your own data types.
75177--
76−-- The downside is that you have to write the parser yourself, the
178+-- The downside is that you have to write the parser yourself; the
77179-- upside is that you have complete control over the way the JSON is
78180-- parsed.
181+
182+-- $typeable
79183--
80−-- /DECODING CUSTOM DATA TYPES GENERICALLY WITH TYPEABLE/
81−--
82−-- If you don't want such control and would prefer the JSON be parsed
184+-- If you don't want fine control and would prefer the JSON be parsed
83185-- to your own data types automatically according to some reasonably
84186-- sensible isomorphic implementation, you can use the generic parser
85187-- based on 'Data.Typeable.Typeable' and 'Data.Data.Data'. Switch to
@@ -97,33 +199,38 @@
97199-- > personName = "Chris", personAge = 123
98200-- > })
99201--
100−-- Be aware that the encoding might not be what you expect:
202+-- Be aware that the encoding may not always be what you'd naively
203+-- expect:
101204--
102205-- > λ> data Foo = Foo Int Int deriving (Data,Typeable,Show)
103206-- > λ> encode (Foo 1 2)
104207-- > "[1,2]"
105208--
106−-- So it's better to treat the 'Data.Aeson.Generic.decode' and
107−-- 'Data.Aeson.Generic.encode' functions as an isomorphism, but do not
108−-- rely or care about the actual intermediate representation.
109−--
110−-- /PITFALLS/
209+-- With this approach, it's best to treat the
210+-- 'Data.Aeson.Generic.decode' and 'Data.Aeson.Generic.encode'
211+-- functions as an isomorphism, and not to rely upon (or care about)
212+-- the specific intermediate representation.
213+
214+-- $pitfalls
215+-- #pitfalls#
111216--
112−-- Note that the JSON standard only allows arrays or objects of things
113−-- at the top-level, so calling decode on a simple type will not work:
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:
114220--
115221-- > λ> decode "1" :: Maybe Int
116222-- > Nothing
117223-- > λ> decode "1" :: Maybe String
118224-- > Nothing
119225--
120−-- So stick to objects (e.g. maps in Haskell) or arrays (lists in Haskell):
226+-- So stick to objects (e.g. maps in Haskell) or arrays (lists or
227+-- vectors in Haskell):
121228--
122229-- > λ> decode "[1,2,3]" :: Maybe [Int]
123230-- > Just [1,2,3]
124231--
125232-- Likewise, for encoding to JSON you can encode anything that's an
126−-- instance of 'ToJSON', which does include simple types. So beware
233+-- instance of 'ToJSON', and this may include simple types. So beware
127234-- that this aspect of the API is not isomorphic:
128235--
129236-- > λ> encode [1,2,3]
@@ -135,76 +242,5 @@
135242-- > λ> decode (encode (1 :: Int)) :: Maybe Int
136243-- > Nothing
137244--
138−-- Alternatively see 'Data.Aeson.Parser.value' to parse non-toplevel
139−-- JSON values.
140−
141−module Data.Aeson
142− (
143− -- * Encoding and decoding
144− decode
145− , decode'
146− , eitherDecode
147− , eitherDecode'
148− , encode
149− -- * Core JSON types
150− , Value(..)
151− , Array
152− , Object
153− -- * Convenience types
154− , DotNetTime(..)
155− -- * Type conversion
156− , FromJSON(..)
157− , Result(..)
158− , fromJSON
159− , ToJSON(..)
160− -- * Inspecting @'Value's@
161− , withObject
162− , withText
163− , withArray
164− , withNumber
165− , withBool
166− -- * Constructors and accessors
167− , (.=)
168− , (.:)
169− , (.:?)
170− , (.!=)
171− , object
172− -- * Parsing
173− , json
174− , json'
175− ) where
176−
177−import Data.Aeson.Encode (encode)
178−import Data.Aeson.Parser.Internal (decodeWith, eitherDecodeWith, json, json')
179−import Data.Aeson.Types
180−import qualified Data.ByteString.Lazy as L
181−
182−-- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
183−-- If this fails due to incomplete or invalid input, 'Nothing' is
184−-- returned.
185−--
186−-- This function parses immediately, but defers conversion. See
187−-- 'json' for details.
188−decode :: (FromJSON a) => L.ByteString -> Maybe a
189−decode = decodeWith json fromJSON
190−{-# INLINE decode #-}
191−
192−-- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
193−-- If this fails due to incomplete or invalid input, 'Nothing' is
194−-- returned.
195−--
196−-- This function parses and performs conversion immediately. See
197−-- 'json'' for details.
198−decode' :: (FromJSON a) => L.ByteString -> Maybe a
199−decode' = decodeWith json' fromJSON
200−{-# INLINE decode' #-}
201−
202−-- | Like 'decode' but returns an error message when decoding fails.
203−eitherDecode :: (FromJSON a) => L.ByteString -> Either String a
204−eitherDecode = eitherDecodeWith json fromJSON
205−{-# INLINE eitherDecode #-}
206−
207−-- | Like 'decode'' but returns an error message when decoding fails.
208−eitherDecode' :: (FromJSON a) => L.ByteString -> Either String a
209−eitherDecode' = eitherDecodeWith json' fromJSON
210−{-# INLINE eitherDecode' #-}
245+-- Alternatively, see 'Data.Aeson.Parser.value' for functions to parse
246+-- non-top-level JSON values.