-
Notifications
You must be signed in to change notification settings - Fork 0
/
Data-Aeson.html
265 lines (246 loc) · 76.2 KB
/
Data-Aeson.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Data.Aeson</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Data-Aeson.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Data-Aeson.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">aeson-0.10.0.0: Fast JSON parsing and encoding</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Copyright</th><td>(c) 2011-2015 Bryan O'Sullivan
(c) 2011 MailRank, Inc.</td></tr><tr><th>License</th><td>Apache</td></tr><tr><th>Maintainer</th><td>Bryan O'Sullivan <[email protected]></td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Portability</th><td>portable</td></tr><tr><th>Safe Haskell</th><td>None</td></tr><tr><th>Language</th><td>Haskell98</td></tr></table><p class="caption">Data.Aeson</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">How to use this library</a><ul><li><a href="#g:2">Writing instances by hand</a></li><li><a href="#g:3">Working with the AST</a></li><li><a href="#g:4">Decoding to a Haskell value</a></li><li><a href="#g:5">Decoding a mixed-type object</a></li></ul></li><li><a href="#g:6">Encoding and decoding</a><ul><li><a href="#g:7">Direct encoding</a></li><li><a href="#g:8">Variants for strict bytestrings</a></li></ul></li><li><a href="#g:9">Core JSON types</a></li><li><a href="#g:10">Convenience types</a></li><li><a href="#g:11">Type conversion</a><ul><li><a href="#g:12">Generic JSON classes and options</a></li></ul></li><li><a href="#g:13">Inspecting <code><code>Value</code>s</code></a></li><li><a href="#g:14">Constructors and accessors</a></li><li><a href="#g:15">Parsing</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Types and functions for working efficiently with JSON data.</p><p>(A note on naming: in Greek mythology, Aeson was the father of Jason.)</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:decode">decode</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a</li><li class="src short"><a href="#v:decode-39-">decode'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a</li><li class="src short"><a href="#v:eitherDecode">eitherDecode</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a</li><li class="src short"><a href="#v:eitherDecode-39-">eitherDecode'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a</li><li class="src short"><a href="#v:encode">encode</a> :: <a href="Data-Aeson.html#t:ToJSON">ToJSON</a> a => a -> <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:decodeStrict">decodeStrict</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a</li><li class="src short"><a href="#v:decodeStrict-39-">decodeStrict'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a</li><li class="src short"><a href="#v:eitherDecodeStrict">eitherDecodeStrict</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a</li><li class="src short"><a href="#v:eitherDecodeStrict-39-">eitherDecodeStrict'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a</li><li class="src short"><span class="keyword">data</span> <a href="#t:Value">Value</a><ul class="subs"><li>= <a href="#v:Object">Object</a> !<a href="Data-Aeson.html#t:Object">Object</a></li><li>| <a href="#v:Array">Array</a> !<a href="Data-Aeson.html#t:Array">Array</a></li><li>| <a href="#v:String">String</a> !<a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a></li><li>| <a href="#v:Number">Number</a> !<a href="../scientific-0.3.4.2/Data-Scientific.html#t:Scientific">Scientific</a></li><li>| <a href="#v:Bool">Bool</a> !<a href="../base-4.8.1.0/Data-Bool.html#t:Bool">Bool</a></li><li>| <a href="#v:Null">Null</a></li></ul></li><li class="src short"><span class="keyword">data</span> <a href="#t:Encoding">Encoding</a></li><li class="src short"><a href="#v:fromEncoding">fromEncoding</a> :: <a href="Data-Aeson.html#t:Encoding">Encoding</a> -> <a href="../bytestring-0.10.6.0/Data-ByteString-Builder.html#t:Builder">Builder</a></li><li class="src short"><span class="keyword">type</span> <a href="#t:Array">Array</a> = <a href="../vector-0.11.0.0/Data-Vector.html#t:Vector">Vector</a> <a href="Data-Aeson.html#t:Value">Value</a></li><li class="src short"><span class="keyword">type</span> <a href="#t:Object">Object</a> = <a href="../unordered-containers-0.2.5.1/Data-HashMap-Strict.html#t:HashMap">HashMap</a> <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> <a href="Data-Aeson.html#t:Value">Value</a></li><li class="src short"><span class="keyword">newtype</span> <a href="#t:DotNetTime">DotNetTime</a> = <a href="#v:DotNetTime">DotNetTime</a> {<ul class="subs"><li><a href="#v:fromDotNetTime">fromDotNetTime</a> :: <a href="../time-1.5.0.1/Data-Time-Clock.html#t:UTCTime">UTCTime</a></li></ul>}</li><li class="src short"><span class="keyword">class</span> <a href="#t:FromJSON">FromJSON</a> a <span class="keyword">where</span><ul class="subs"><li><a href="#v:parseJSON">parseJSON</a> :: <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li></ul></li><li class="src short"><span class="keyword">data</span> <a href="#t:Result">Result</a> a<ul class="subs"><li>= <a href="#v:Error">Error</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a></li><li>| <a href="#v:Success">Success</a> a</li></ul></li><li class="src short"><a href="#v:fromJSON">fromJSON</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson.html#t:Result">Result</a> a</li><li class="src short"><span class="keyword">class</span> <a href="#t:ToJSON">ToJSON</a> a <span class="keyword">where</span><ul class="subs"><li><a href="#v:toJSON">toJSON</a> :: a -> <a href="Data-Aeson.html#t:Value">Value</a></li><li><a href="#v:toEncoding">toEncoding</a> :: a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a></li></ul></li><li class="src short"><span class="keyword">class</span> <a href="#t:KeyValue">KeyValue</a> kv <span class="keyword">where</span><ul class="subs"><li><a href="#v:.-61-">(.=)</a> :: <a href="Data-Aeson.html#t:ToJSON">ToJSON</a> v => <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> v -> kv</li></ul></li><li class="src short"><span class="keyword">class</span> <a href="#t:GFromJSON">GFromJSON</a> f <span class="keyword">where</span><ul class="subs"><li><a href="#v:gParseJSON">gParseJSON</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a> -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> (f a)</li></ul></li><li class="src short"><span class="keyword">class</span> <a href="#t:GToJSON">GToJSON</a> f <span class="keyword">where</span><ul class="subs"><li><a href="#v:gToJSON">gToJSON</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a> -> f a -> <a href="Data-Aeson.html#t:Value">Value</a></li><li><a href="#v:gToEncoding">gToEncoding</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a> -> f a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a></li></ul></li><li class="src short"><a href="#v:genericToJSON">genericToJSON</a> :: (<a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a> a, <a href="Data-Aeson.html#t:GToJSON">GToJSON</a> (<a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a> a)) => <a href="Data-Aeson-Types.html#t:Options">Options</a> -> a -> <a href="Data-Aeson.html#t:Value">Value</a></li><li class="src short"><a href="#v:genericToEncoding">genericToEncoding</a> :: (<a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a> a, <a href="Data-Aeson.html#t:GToJSON">GToJSON</a> (<a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a> a)) => <a href="Data-Aeson-Types.html#t:Options">Options</a> -> a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a></li><li class="src short"><a href="#v:genericParseJSON">genericParseJSON</a> :: (<a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a> a, <a href="Data-Aeson.html#t:GFromJSON">GFromJSON</a> (<a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a> a)) => <a href="Data-Aeson-Types.html#t:Options">Options</a> -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:defaultOptions">defaultOptions</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a></li><li class="src short"><a href="#v:withObject">withObject</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="Data-Aeson.html#t:Object">Object</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:withText">withText</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:withArray">withArray</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="Data-Aeson.html#t:Array">Array</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:withNumber">withNumber</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../attoparsec-0.13.0.1/Data-Attoparsec-Number.html#t:Number">Number</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:withScientific">withScientific</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../scientific-0.3.4.2/Data-Scientific.html#t:Scientific">Scientific</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:withBool">withBool</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../base-4.8.1.0/Data-Bool.html#t:Bool">Bool</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><span class="keyword">data</span> <a href="#t:Series">Series</a></li><li class="src short"><a href="#v:pairs">pairs</a> :: <a href="Data-Aeson.html#t:Series">Series</a> -> <a href="Data-Aeson.html#t:Encoding">Encoding</a></li><li class="src short"><a href="#v:foldable">foldable</a> :: (<a href="../base-4.8.1.0/Data-Foldable.html#t:Foldable">Foldable</a> t, <a href="Data-Aeson.html#t:ToJSON">ToJSON</a> a) => t a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a></li><li class="src short"><a href="#v:.:">(.:)</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="Data-Aeson.html#t:Object">Object</a> -> <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:.:-63-">(.:?)</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="Data-Aeson.html#t:Object">Object</a> -> <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> (<a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a)</li><li class="src short"><a href="#v:.-33--61-">(.!=)</a> :: <a href="Data-Aeson-Types.html#t:Parser">Parser</a> (<a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a) -> a -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a</li><li class="src short"><a href="#v:object">object</a> :: [<a href="Data-Aeson-Types.html#t:Pair">Pair</a>] -> <a href="Data-Aeson.html#t:Value">Value</a></li><li class="src short"><a href="#v:json">json</a> :: <a href="../attoparsec-0.13.0.1/Data-Attoparsec-ByteString.html#t:Parser">Parser</a> <a href="Data-Aeson.html#t:Value">Value</a></li><li class="src short"><a href="#v:json-39-">json'</a> :: <a href="../attoparsec-0.13.0.1/Data-Attoparsec-ByteString.html#t:Parser">Parser</a> <a href="Data-Aeson.html#t:Value">Value</a></li></ul></div><div id="interface"><h1 id="g:1">How to use this library</h1><div class="doc"><p>This section contains basic information on the different ways to
work with data using this library. These range from simple but
inflexible, to complex but flexible.</p><p>The most common way to use the library is to define a data type,
corresponding to some JSON data you want to work with, and then
write either a <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> instance, a to <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> instance, or both
for that type.</p><p>For example, given this JSON data:</p><pre>{ "name": "Joe", "age": 12 }</pre><p>we create a matching data type:</p><pre>{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
data Person = Person {
name :: Text
, age :: Int
} deriving (Generic, Show)</pre><p>The <code>LANGUAGE</code> pragma and <code>Generic</code> instance let us write empty
<code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> and <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> instances for which the compiler will
generate sensible default implementations.</p><pre>instance <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> Person where
-- No need to provide a <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code> implementation.
-- For efficiency, we write a simple <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> implementation, as
-- the default version uses <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>.
<code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> = <code><a href="Data-Aeson.html#v:genericToEncoding">genericToEncoding</a></code> <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>
instance <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> Person
-- No need to provide a <code><a href="Data-Aeson.html#v:parseJSON">parseJSON</a></code> implementation.
</pre><p>We can now encode a value like so:</p><pre>>>> encode (Person {name = "Joe", age = 12})
"{\"name\":\"Joe\",\"age\":12}"</pre></div><h2 id="g:2">Writing instances by hand</h2><div class="doc"><p>When necessary, we can write <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> and <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> instances by
hand. This is valuable when the JSON-on-the-wire and Haskell data
are different or otherwise need some more carefully managed
translation. Let's revisit our JSON data:</p><pre>{ "name": "Joe", "age": 12 }</pre><p>We once again create a matching data type, without bothering to add
a <code>Generic</code> instance this time:</p><pre>data Person = Person {
name :: Text
, age :: Int
} deriving Show</pre><p>To decode data, we need to define a <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> instance:</p><pre>{-# LANGUAGE OverloadedStrings #-}
instance FromJSON Person where
parseJSON (Object v) = Person <$>
v .: "name" <*>
v .: "age"
-- A non-Object value is of the wrong type, so fail.
parseJSON _ = empty</pre><p>We can now parse the JSON data like so:</p><pre>>>> decode "{\"name\":\"Joe\",\"age\":12}" :: Maybe Person
Just (Person {name = "Joe", age = 12})</pre><p>To encode data, we need to define a <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> instance. Let's begin
with an instance written entirely by hand.</p><pre>instance ToJSON Person where
-- this generates a <code><a href="Data-Aeson.html#t:Value">Value</a></code>
<code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code> (Person name age) =
<code><a href="Data-Aeson.html#v:object">object</a></code> ["name" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> name, "age" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> age]
-- this encodes directly to a bytestring Builder
<code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> (Person name age) =
<code><a href="Data-Aeson.html#v:pairs">pairs</a></code> ("name" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> <code>name</code> <code><></code> "age" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> age)
</pre><p>We can now encode a value like so:</p><pre>>>> encode (Person {name = "Joe", age = 12})
"{\"name\":\"Joe\",\"age\":12}"</pre><p>There are predefined <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> and <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> instances for many
types. Here's an example using lists and <code><a href="../base-4.8.1.0/Data-Int.html#t:Int">Int</a></code>s:</p><pre>>>> decode "[1,2,3]" :: Maybe [Int]
Just [1,2,3]</pre><p>And here's an example using the <code><a href="../containers-0.5.6.2/Data-Map.html#v:Map">Map</a></code> type to get a map of
<code><a href="../base-4.8.1.0/Data-Int.html#t:Int">Int</a></code>s.</p><pre>>>> decode "{\"foo\":1,\"bar\":2}" :: Maybe (Map String Int)
Just (fromList [("bar",2),("foo",1)])</pre></div><h2 id="g:3">Working with the AST</h2><div class="doc"><p>Sometimes you want to work with JSON data directly, without first
converting it to a custom data type. This can be useful if you want
to e.g. convert JSON data to YAML data, without knowing what the
contents of the original JSON data was. The <code><a href="Data-Aeson.html#t:Value">Value</a></code> type, which is
an instance of <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code>, is used to represent an arbitrary JSON
AST (abstract syntax tree). Example usage:</p><pre>>>> decode "{\"foo\": 123}" :: Maybe Value
Just (Object (fromList [("foo",Number 123)]))</pre><pre>>>> decode "{\"foo\": [\"abc\",\"def\"]}" :: Maybe Value
Just (Object (fromList [("foo",Array (fromList [String "abc",String "def"]))]))</pre><p>Once you have a <code><a href="Data-Aeson.html#t:Value">Value</a></code> you can write functions to traverse it and
make arbitrary transformations.</p></div><h2 id="g:4">Decoding to a Haskell value</h2><div class="doc"><p>We can decode to any instance of <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code>:</p><pre>λ> decode "[1,2,3]" :: Maybe [Int]
Just [1,2,3]</pre><p>Alternatively, there are instances for standard data types, so you
can use them directly. For example, use the <code><a href="../containers-0.5.6.2/Data-Map.html#v:Map">Map</a></code> type to
get a map of <code><a href="../base-4.8.1.0/Data-Int.html#t:Int">Int</a></code>s.</p><pre>λ> import Data.Map
λ> decode "{\"foo\":1,\"bar\":2}" :: Maybe (Map String Int)
Just (fromList [("bar",2),("foo",1)])</pre></div><h2 id="g:5">Decoding a mixed-type object</h2><div class="doc"><p>The above approach with maps of course will not work for mixed-type
objects that don't follow a strict schema, but there are a couple
of approaches available for these.</p><p>The <code><a href="Data-Aeson.html#t:Object">Object</a></code> type contains JSON objects:</p><pre>λ> decode "{\"name\":\"Dave\",\"age\":2}" :: Maybe Object
Just (fromList) [("name",String "Dave"),("age",Number 2)]</pre><p>You can extract values from it with a parser using <code><a href="Data-Aeson-Types.html#v:parse">parse</a></code>,
<code><a href="Data-Aeson-Types.html#v:parseEither">parseEither</a></code> or, in this example, <code><a href="Data-Aeson-Types.html#v:parseMaybe">parseMaybe</a></code>:</p><pre>λ> do result <- decode "{\"name\":\"Dave\",\"age\":2}"
flip parseMaybe result $ \obj -> do
age <- obj .: "age"
name <- obj .: "name"
return (name ++ ": " ++ show (age*2))
Just "Dave: 4"</pre><p>Considering that any type that implements <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> can be used
here, this is quite a powerful way to parse JSON. See the
documentation in <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> for how to implement this class for
your own data types.</p><p>The downside is that you have to write the parser yourself; the
upside is that you have complete control over the way the JSON is
parsed.</p></div><h1 id="g:6">Encoding and decoding</h1><div class="doc"><p>Decoding is a two-step process.</p><ul><li>When decoding a value, the process is reversed: the bytes are
converted to a <code><a href="Data-Aeson.html#t:Value">Value</a></code>, then the <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> class is used to
convert to the desired type.</li></ul><p>There are two ways to encode a value.</p><ul><li>Convert to a <code><a href="Data-Aeson.html#t:Value">Value</a></code> using <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>, then possibly further
encode. This was the only method available in aeson 0.9 and
earlier.</li><li>Directly encode (to what will become a <code><a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></code>) using
<code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code>. This is much more efficient (about 3x faster, and
less memory intensive besides), but is only available in aeson
0.10 and newer.</li></ul><p>For convenience, the <code><a href="Data-Aeson.html#v:encode">encode</a></code> and <code><a href="Data-Aeson.html#v:decode">decode</a></code> functions combine both
steps.</p></div><h2 id="g:7">Direct encoding</h2><div class="doc"><p>In older versions of this library, encoding a Haskell value
involved converting to an intermediate <code><a href="Data-Aeson.html#t:Value">Value</a></code>, then encoding that.</p><p>A "direct" encoder converts straight from a source Haskell value
to a <code><a href="BL.html#v:ByteString">ByteString</a></code> without constructing an intermediate <code><a href="Data-Aeson.html#t:Value">Value</a></code>.
This approach is faster than <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>, and allocates less memory.
The <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> method makes it possible to implement direct
encoding with low memory overhead.</p><p>To complicate matters, the default implementation of <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code>
uses <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>. Why? The <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> method was added to this
library much more recently than <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>. Using <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code> ensures
that packages written against older versions of this library will
compile and produce correct output, but they will not see any
speedup from direct encoding.</p><p>To write a minimal implementation of direct encoding, your type
must implement GHC's <code>Generic</code> class, and your code should look
like this:</p><pre> <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> = <code><a href="Data-Aeson.html#v:genericToEncoding">genericToEncoding</a></code> <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>
</pre><p>What if you have more elaborate encoding needs? For example,
perhaps you need to change the names of object keys, omit parts of
a value.</p><p>To encode to a JSON "object", use the <code><a href="Data-Aeson.html#v:pairs">pairs</a></code> function.</p><pre> <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> (Person name age) =
<code><a href="Data-Aeson.html#v:pairs">pairs</a></code> ("name" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> <code>name</code> <code><></code> "age" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> age)
</pre><p>Any container type that implements <code><a href="../base-4.8.1.0/Data-Foldable.html#t:Foldable">Foldable</a></code> can be encoded to a
JSON "array" using <code><a href="Data-Aeson.html#v:foldable">foldable</a></code>.</p><pre>> import Data.Sequence as Seq
> encode (Seq.fromList [1,2,3])
"[1,2,3]"</pre></div><div class="top"><p class="src"><a name="v:decode" class="def">decode</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a <a href="src/Data-Aeson.html#decode" class="link">Source</a></p><div class="doc"><p>Efficiently deserialize a JSON value from a lazy <code><a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></code>.
If this fails due to incomplete or invalid input, <code><a href="../base-4.8.1.0/Data-Maybe.html#v:Nothing">Nothing</a></code> is
returned.</p><p>The input must consist solely of a JSON document, with no trailing
data except for whitespace.</p><p>This function parses immediately, but defers conversion. See
<code><a href="Data-Aeson.html#v:json">json</a></code> for details.</p></div></div><div class="top"><p class="src"><a name="v:decode-39-" class="def">decode'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a <a href="src/Data-Aeson.html#decode%27" class="link">Source</a></p><div class="doc"><p>Efficiently deserialize a JSON value from a lazy <code><a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></code>.
If this fails due to incomplete or invalid input, <code><a href="../base-4.8.1.0/Data-Maybe.html#v:Nothing">Nothing</a></code> is
returned.</p><p>The input must consist solely of a JSON document, with no trailing
data except for whitespace.</p><p>This function parses and performs conversion immediately. See
<code><a href="Data-Aeson.html#v:json-39-">json'</a></code> for details.</p></div></div><div class="top"><p class="src"><a name="v:eitherDecode" class="def">eitherDecode</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a <a href="src/Data-Aeson.html#eitherDecode" class="link">Source</a></p><div class="doc"><p>Like <code><a href="Data-Aeson.html#v:decode">decode</a></code> but returns an error message when decoding fails.</p></div></div><div class="top"><p class="src"><a name="v:eitherDecode-39-" class="def">eitherDecode'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a <a href="src/Data-Aeson.html#eitherDecode%27" class="link">Source</a></p><div class="doc"><p>Like <code><a href="Data-Aeson.html#v:decode-39-">decode'</a></code> but returns an error message when decoding fails.</p></div></div><div class="top"><p class="src"><a name="v:encode" class="def">encode</a> :: <a href="Data-Aeson.html#t:ToJSON">ToJSON</a> a => a -> <a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a> <a href="src/Data-Aeson-Encode-Functions.html#encode" class="link">Source</a></p><div class="doc"><p>Efficiently serialize a JSON value as a lazy <code><a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></code>.</p><p>This is implemented in terms of the <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> class's <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> method.</p></div></div><h2 id="g:8">Variants for strict bytestrings</h2><div class="top"><p class="src"><a name="v:decodeStrict" class="def">decodeStrict</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a <a href="src/Data-Aeson.html#decodeStrict" class="link">Source</a></p><div class="doc"><p>Efficiently deserialize a JSON value from a strict <code><a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a></code>.
If this fails due to incomplete or invalid input, <code><a href="../base-4.8.1.0/Data-Maybe.html#v:Nothing">Nothing</a></code> is
returned.</p><p>The input must consist solely of a JSON document, with no trailing
data except for whitespace.</p><p>This function parses immediately, but defers conversion. See
<code><a href="Data-Aeson.html#v:json">json</a></code> for details.</p></div></div><div class="top"><p class="src"><a name="v:decodeStrict-39-" class="def">decodeStrict'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a <a href="src/Data-Aeson.html#decodeStrict%27" class="link">Source</a></p><div class="doc"><p>Efficiently deserialize a JSON value from a lazy <code><a href="../bytestring-0.10.6.0/Data-ByteString-Lazy.html#t:ByteString">ByteString</a></code>.
If this fails due to incomplete or invalid input, <code><a href="../base-4.8.1.0/Data-Maybe.html#v:Nothing">Nothing</a></code> is
returned.</p><p>The input must consist solely of a JSON document, with no trailing
data except for whitespace.</p><p>This function parses and performs conversion immediately. See
<code><a href="Data-Aeson.html#v:json-39-">json'</a></code> for details.</p></div></div><div class="top"><p class="src"><a name="v:eitherDecodeStrict" class="def">eitherDecodeStrict</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a <a href="src/Data-Aeson.html#eitherDecodeStrict" class="link">Source</a></p><div class="doc"><p>Like <code><a href="Data-Aeson.html#v:decodeStrict">decodeStrict</a></code> but returns an error message when decoding fails.</p></div></div><div class="top"><p class="src"><a name="v:eitherDecodeStrict-39-" class="def">eitherDecodeStrict'</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="../bytestring-0.10.6.0/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.8.1.0/Data-Either.html#t:Either">Either</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> a <a href="src/Data-Aeson.html#eitherDecodeStrict%27" class="link">Source</a></p><div class="doc"><p>Like <code><a href="Data-Aeson.html#v:decodeStrict-39-">decodeStrict'</a></code> but returns an error message when decoding fails.</p></div></div><h1 id="g:9">Core JSON types</h1><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:Value" class="def">Value</a> <a href="src/Data-Aeson-Types-Internal.html#Value" class="link">Source</a></p><div class="doc"><p>A JSON value represented as a Haskell value.</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:Object" class="def">Object</a> !<a href="Data-Aeson.html#t:Object">Object</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:Array" class="def">Array</a> !<a href="Data-Aeson.html#t:Array">Array</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:String" class="def">String</a> !<a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:Number" class="def">Number</a> !<a href="../scientific-0.3.4.2/Data-Scientific.html#t:Scientific">Scientific</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:Bool" class="def">Bool</a> !<a href="../base-4.8.1.0/Data-Bool.html#t:Bool">Bool</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:Null" class="def">Null</a></td><td class="doc empty"> </td></tr></table></div><div class="subs instances"><p id="control.i:Value" class="caption collapser" onclick="toggleSection('i:Value')">Instances</p><div id="section.i:Value" class="show"><table><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Eq.html#t:Eq">Eq</a> <a href="Data-Aeson.html#t:Value">Value</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-297" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Data.html#t:Data">Data</a> <a href="Data-Aeson.html#t:Value">Value</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-297" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Text-Read.html#t:Read">Read</a> <a href="Data-Aeson.html#t:Value">Value</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-297" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Text-Show.html#t:Show">Show</a> <a href="Data-Aeson.html#t:Value">Value</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-297" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-String.html#t:IsString">IsString</a> <a href="Data-Aeson.html#t:Value">Value</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-351" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../deepseq-1.4.1.1/Control-DeepSeq.html#t:NFData">NFData</a> <a href="Data-Aeson.html#t:Value">Value</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-343" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../hashable-1.2.3.3/Data-Hashable.html#t:Hashable">Hashable</a> <a href="Data-Aeson.html#t:Value">Value</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-365" class="link">Source</a></td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:Encoding" class="def">Encoding</a> <a href="src/Data-Aeson-Types-Internal.html#Encoding" class="link">Source</a></p><div class="doc"><p>An encoding of a JSON value.</p></div><div class="subs instances"><p id="control.i:Encoding" class="caption collapser" onclick="toggleSection('i:Encoding')">Instances</p><div id="section.i:Encoding" class="show"><table><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Eq.html#t:Eq">Eq</a> <a href="Data-Aeson.html#t:Encoding">Encoding</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-308" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Ord.html#t:Ord">Ord</a> <a href="Data-Aeson.html#t:Encoding">Encoding</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-311" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Text-Show.html#t:Show">Show</a> <a href="Data-Aeson.html#t:Encoding">Encoding</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-305" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Monoid.html#t:Monoid">Monoid</a> <a href="Data-Aeson.html#t:Encoding">Encoding</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-303" class="link">Source</a></td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><a name="v:fromEncoding" class="def">fromEncoding</a> :: <a href="Data-Aeson.html#t:Encoding">Encoding</a> -> <a href="../bytestring-0.10.6.0/Data-ByteString-Builder.html#t:Builder">Builder</a> <a href="src/Data-Aeson-Types-Internal.html#fromEncoding" class="link">Source</a></p><div class="doc"><p>Acquire the underlying bytestring builder.</p></div></div><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:Array" class="def">Array</a> = <a href="../vector-0.11.0.0/Data-Vector.html#t:Vector">Vector</a> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Types-Internal.html#Array" class="link">Source</a></p><div class="doc"><p>A JSON "array" (sequence).</p></div></div><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:Object" class="def">Object</a> = <a href="../unordered-containers-0.2.5.1/Data-HashMap-Strict.html#t:HashMap">HashMap</a> <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Types-Internal.html#Object" class="link">Source</a></p><div class="doc"><p>A JSON "object" (key/value map).</p></div></div><h1 id="g:10">Convenience types</h1><div class="top"><p class="src"><span class="keyword">newtype</span> <a name="t:DotNetTime" class="def">DotNetTime</a> <a href="src/Data-Aeson-Types-Internal.html#DotNetTime" class="link">Source</a></p><div class="doc"><p>A newtype wrapper for <code><a href="../time-1.5.0.1/Data-Time-Clock.html#t:UTCTime">UTCTime</a></code> that uses the same non-standard
serialization format as Microsoft .NET, whose
<a href="https://msdn.microsoft.com/en-us/library/system.datetime(v=vs.110).aspx">System.DateTime</a>
type is by default serialized to JSON as in the following example:</p><pre>/Date(1302547608878)/</pre><p>The number represents milliseconds since the Unix epoch.</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:DotNetTime" class="def">DotNetTime</a></td><td class="doc empty"> </td></tr><tr><td colspan="2"><div class="subs fields"><p class="caption">Fields</p><dl><dt class="src"><a name="v:fromDotNetTime" class="def">fromDotNetTime</a> :: <a href="../time-1.5.0.1/Data-Time-Clock.html#t:UTCTime">UTCTime</a></dt><dd class="doc"><p>Acquire the underlying value.</p></dd></dl><div class="clear"></div></div></td></tr></table></div><div class="subs instances"><p id="control.i:DotNetTime" class="caption collapser" onclick="toggleSection('i:DotNetTime')">Instances</p><div id="section.i:DotNetTime" class="show"><table><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Eq.html#t:Eq">Eq</a> <a href="Data-Aeson.html#t:DotNetTime">DotNetTime</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-341" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Ord.html#t:Ord">Ord</a> <a href="Data-Aeson.html#t:DotNetTime">DotNetTime</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-341" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Text-Read.html#t:Read">Read</a> <a href="Data-Aeson.html#t:DotNetTime">DotNetTime</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-341" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Text-Show.html#t:Show">Show</a> <a href="Data-Aeson.html#t:DotNetTime">DotNetTime</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-341" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../time-1.5.0.1/Data-Time-Format.html#t:FormatTime">FormatTime</a> <a href="Data-Aeson.html#t:DotNetTime">DotNetTime</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-341" class="link">Source</a></td><td class="doc empty"> </td></tr></table></div></div></div><h1 id="g:11">Type conversion</h1><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:FromJSON" class="def">FromJSON</a> a <span class="keyword">where</span> <a href="src/Data-Aeson-Types-Class.html#FromJSON" class="link">Source</a></p><div class="doc"><p>A type that can be converted from JSON, with the possibility of
failure.</p><p>In many cases, you can get the compiler to generate parsing code
for you (see below). To begin, let's cover writing an instance by
hand.</p><p>There are various reasons a conversion could fail. For example, an
<code><a href="Data-Aeson.html#t:Object">Object</a></code> could be missing a required key, an <code><a href="Data-Aeson.html#t:Array">Array</a></code> could be of
the wrong size, or a value could be of an incompatible type.</p><p>The basic ways to signal a failed conversion are as follows:</p><ul><li><code>empty</code> and <code>mzero</code> work, but are terse and uninformative</li><li><code><a href="../base-4.8.1.0/Control-Monad.html#v:fail">fail</a></code> yields a custom error message</li><li><code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> produces an informative message for cases when the
value encountered is not of the expected type</li></ul><p>An example type and instance:</p><pre>-- Allow ourselves to write <code><a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a></code> literals.
{-# LANGUAGE OverloadedStrings #-}
data Coord = Coord { x :: Double, y :: Double }
instance FromJSON Coord where
parseJSON (<code><a href="Data-Aeson.html#t:Object">Object</a></code> v) = Coord <code><a href="../base-4.8.1.0/Data-Functor.html#v:-60--36--62-"><$></a></code>
v <code>.:</code> "x" <code><a href="../base-4.8.1.0/Control-Applicative.html#v:-60--42--62-"><*></a></code>
v <code>.:</code> "y"
-- We do not expect a non-<code><a href="Data-Aeson.html#t:Object">Object</a></code> value here.
-- We could use <code>mzero</code> to fail, but <code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code>
-- gives a much more informative error message.
parseJSON invalid = <code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> "Coord" invalid
</pre><p>Instead of manually writing your <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> instance, there are two options
to do it automatically:</p><ul><li><a href="Data-Aeson-TH.html">Data.Aeson.TH</a> provides Template Haskell functions which will derive an
instance at compile time. The generated instance is optimized for your type
so will probably be more efficient than the following two options:</li><li>The compiler can provide a default generic implementation for
<code><a href="Data-Aeson.html#v:parseJSON">parseJSON</a></code>.</li></ul><p>To use the second, simply add a <code>deriving <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code></code> clause to your
datatype and declare a <code><a href="Data-Aeson.html#t:FromJSON">FromJSON</a></code> instance for your datatype without giving
a definition for <code><a href="Data-Aeson.html#v:parseJSON">parseJSON</a></code>.</p><p>For example, the previous example can be simplified to just:</p><pre>{-# LANGUAGE DeriveGeneric #-}
import <a href="../base-4.8.1.0/GHC-Generics.html">GHC.Generics</a>
data Coord = Coord { x :: Double, y :: Double } deriving <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code>
instance FromJSON Coord
</pre><p>If <code>DefaultSignatures</code> doesn't give exactly the results you want,
you can customize the generic decoding with only a tiny amount of
effort, using <code><a href="Data-Aeson.html#v:genericParseJSON">genericParseJSON</a></code> with your preferred <code><a href="Data-Aeson-Types.html#t:Options">Options</a></code>:</p><pre>instance FromJSON Coord where
parseJSON = <code><a href="Data-Aeson.html#v:genericParseJSON">genericParseJSON</a></code> <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>
</pre></div><div class="subs minimal"><p class="caption">Minimal complete definition</p><p class="src">Nothing</p></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:parseJSON" class="def">parseJSON</a> :: <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Class.html#parseJSON" class="link">Source</a></p></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:Result" class="def">Result</a> a <a href="src/Data-Aeson-Types-Internal.html#Result" class="link">Source</a></p><div class="doc"><p>The result of running a <code><a href="Data-Aeson-Types.html#t:Parser">Parser</a></code>.</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:Error" class="def">Error</a> <a href="../base-4.8.1.0/Data-String.html#t:String">String</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a name="v:Success" class="def">Success</a> a</td><td class="doc empty"> </td></tr></table></div><div class="subs instances"><p id="control.i:Result" class="caption collapser" onclick="toggleSection('i:Result')">Instances</p><div id="section.i:Result" class="show"><table><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Control-Monad.html#t:Monad">Monad</a> <a href="Data-Aeson.html#t:Result">Result</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-135" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Functor.html#t:Functor">Functor</a> <a href="Data-Aeson.html#t:Result">Result</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-119" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Control-Applicative.html#t:Applicative">Applicative</a> <a href="Data-Aeson.html#t:Result">Result</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-152" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Foldable.html#t:Foldable">Foldable</a> <a href="Data-Aeson.html#t:Result">Result</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-205" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Traversable.html#t:Traversable">Traversable</a> <a href="Data-Aeson.html#t:Result">Result</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-219" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Control-Applicative.html#t:Alternative">Alternative</a> <a href="Data-Aeson.html#t:Result">Result</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-178" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Control-Monad.html#t:MonadPlus">MonadPlus</a> <a href="Data-Aeson.html#t:Result">Result</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-165" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Eq.html#t:Eq">Eq</a> a => <a href="../base-4.8.1.0/Data-Eq.html#t:Eq">Eq</a> (<a href="Data-Aeson.html#t:Result">Result</a> a)</span> <a href="src/Data-Aeson-Types-Internal.html#line-100" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Text-Show.html#t:Show">Show</a> a => <a href="../base-4.8.1.0/Text-Show.html#t:Show">Show</a> (<a href="Data-Aeson.html#t:Result">Result</a> a)</span> <a href="src/Data-Aeson-Types-Internal.html#line-100" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Monoid.html#t:Monoid">Monoid</a> (<a href="Data-Aeson.html#t:Result">Result</a> a)</span> <a href="src/Data-Aeson-Types-Internal.html#line-190" class="link">Source</a></td><td class="doc empty"> </td></tr><tr><td class="src clearfix"><span class="inst-left"><a href="../deepseq-1.4.1.1/Control-DeepSeq.html#t:NFData">NFData</a> a => <a href="../deepseq-1.4.1.1/Control-DeepSeq.html#t:NFData">NFData</a> (<a href="Data-Aeson.html#t:Result">Result</a> a)</span> <a href="src/Data-Aeson-Types-Internal.html#line-110" class="link">Source</a></td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><a name="v:fromJSON" class="def">fromJSON</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson.html#t:Result">Result</a> a <a href="src/Data-Aeson-Types-Instances.html#fromJSON" class="link">Source</a></p><div class="doc"><p>Convert a value from JSON, failing if the types do not match.</p></div></div><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:ToJSON" class="def">ToJSON</a> a <span class="keyword">where</span> <a href="src/Data-Aeson-Types-Class.html#ToJSON" class="link">Source</a></p><div class="doc"><p>A type that can be converted to JSON.</p><p>An example type and instance:</p><pre>-- Allow ourselves to write <code><a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a></code> literals.
{-# LANGUAGE OverloadedStrings #-}
data Coord = Coord { x :: Double, y :: Double }
instance ToJSON Coord where
toJSON (Coord x y) = <code><a href="Data-Aeson.html#v:object">object</a></code> ["x" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> x, "y" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> y]
toEncoding (Coord x y) = <code>pairs</code> ("x" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> x <code><></code> "y" <code><a href="Data-Aeson.html#v:.-61-">.=</a></code> y)
</pre><p>Instead of manually writing your <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> instance, there are two options
to do it automatically:</p><ul><li><a href="Data-Aeson-TH.html">Data.Aeson.TH</a> provides Template Haskell functions which will derive an
instance at compile time. The generated instance is optimized for your type
so will probably be more efficient than the following two options:</li><li>The compiler can provide a default generic implementation for
<code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>.</li></ul><p>To use the second, simply add a <code>deriving <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code></code> clause to your
datatype and declare a <code><a href="Data-Aeson.html#t:ToJSON">ToJSON</a></code> instance for your datatype without giving
definitions for <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code> or <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code>.</p><p>For example, the previous example can be simplified to a more
minimal instance:</p><pre>{-# LANGUAGE DeriveGeneric #-}
import <a href="../base-4.8.1.0/GHC-Generics.html">GHC.Generics</a>
data Coord = Coord { x :: Double, y :: Double } deriving <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code>
instance ToJSON Coord where
toEncoding = <code><a href="Data-Aeson.html#v:genericToEncoding">genericToEncoding</a></code> <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>
</pre><p>Why do we provide an implementation for <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> here? The
<code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> function is a relatively new addition to this class.
To allow users of older versions of this library to upgrade without
having to edit all of their instances or encounter surprising
incompatibilities, the default implementation of <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> uses
<code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>. This produces correct results, but since it performs an
intermediate conversion to a <code><a href="Data-Aeson.html#t:Value">Value</a></code>, it will be less efficient
than directly emitting an <code><a href="Data-Aeson.html#t:Encoding">Encoding</a></code>. Our one-liner definition of
<code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> above bypasses the intermediate <code><a href="Data-Aeson.html#t:Value">Value</a></code>.</p><p>If <code>DefaultSignatures</code> doesn't give exactly the results you want,
you can customize the generic encoding with only a tiny amount of
effort, using <code><a href="Data-Aeson.html#v:genericToJSON">genericToJSON</a></code> and <code><a href="Data-Aeson.html#v:genericToEncoding">genericToEncoding</a></code> with your
preferred <code><a href="Data-Aeson-Types.html#t:Options">Options</a></code>:</p><pre>instance ToJSON Coord where
toJSON = <code><a href="Data-Aeson.html#v:genericToJSON">genericToJSON</a></code> <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>
toEncoding = <code><a href="Data-Aeson.html#v:genericToEncoding">genericToEncoding</a></code> <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>
</pre></div><div class="subs minimal"><p class="caption">Minimal complete definition</p><p class="src">Nothing</p></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:toJSON" class="def">toJSON</a> :: a -> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Types-Class.html#toJSON" class="link">Source</a></p><div class="doc"><p>Convert a Haskell value to a JSON-friendly intermediate type.</p></div><p class="src"><a name="v:toEncoding" class="def">toEncoding</a> :: a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a> <a href="src/Data-Aeson-Types-Class.html#toEncoding" class="link">Source</a></p><div class="doc"><p>Encode a Haskell value as JSON.</p><p>The default implementation of this method creates an
intermediate <code><a href="Data-Aeson.html#t:Value">Value</a></code> using <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>. This provides
source-level compatibility for people upgrading from older
versions of this library, but obviously offers no performance
advantage.</p><p>To benefit from direct encoding, you <em>must</em> provide an
implementation for this method. The easiest way to do so is by
having your types implement <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code> using the <code>DeriveGeneric</code>
extension, and then have GHC generate a method body as follows.</p><pre>instance ToJSON Coord where
toEncoding = <code><a href="Data-Aeson.html#v:genericToEncoding">genericToEncoding</a></code> <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>
</pre></div></div></div><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:KeyValue" class="def">KeyValue</a> kv <span class="keyword">where</span> <a href="src/Data-Aeson-Types-Class.html#KeyValue" class="link">Source</a></p><div class="doc"><p>A key-value pair for encoding a JSON object.</p></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:.-61-" class="def">(.=)</a> :: <a href="Data-Aeson.html#t:ToJSON">ToJSON</a> v => <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> v -> kv <span class="fixity">infixr 8</span><span class="rightedge"></span> <a href="src/Data-Aeson-Types-Class.html#.%3D" class="link">Source</a></p></div></div><h2 id="g:12">Generic JSON classes and options</h2><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:GFromJSON" class="def">GFromJSON</a> f <span class="keyword">where</span> <a href="src/Data-Aeson-Types-Class.html#GFromJSON" class="link">Source</a></p><div class="doc"><p>Class of generic representation types (<code><a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a></code>) that can be converted from JSON.</p></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:gParseJSON" class="def">gParseJSON</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a> -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> (f a) <a href="src/Data-Aeson-Types-Class.html#gParseJSON" class="link">Source</a></p><div class="doc"><p>This method (applied to <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>) is used as the
default generic implementation of <code><a href="Data-Aeson.html#v:parseJSON">parseJSON</a></code>.</p></div></div></div><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:GToJSON" class="def">GToJSON</a> f <span class="keyword">where</span> <a href="src/Data-Aeson-Types-Class.html#GToJSON" class="link">Source</a></p><div class="doc"><p>Class of generic representation types (<code><a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a></code>) that can be converted to
JSON.</p></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:gToJSON" class="def">gToJSON</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a> -> f a -> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Types-Class.html#gToJSON" class="link">Source</a></p><div class="doc"><p>This method (applied to <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>) is used as the
default generic implementation of <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code>.</p></div><p class="src"><a name="v:gToEncoding" class="def">gToEncoding</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a> -> f a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a> <a href="src/Data-Aeson-Types-Class.html#gToEncoding" class="link">Source</a></p><div class="doc"><p>This method (applied to <code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code>) can be used as the
default generic implementation of <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code>.</p></div></div></div><div class="top"><p class="src"><a name="v:genericToJSON" class="def">genericToJSON</a> :: (<a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a> a, <a href="Data-Aeson.html#t:GToJSON">GToJSON</a> (<a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a> a)) => <a href="Data-Aeson-Types.html#t:Options">Options</a> -> a -> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Types-Class.html#genericToJSON" class="link">Source</a></p><div class="doc"><p>A configurable generic JSON creator. This function applied to
<code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code> is used as the default for <code><a href="Data-Aeson.html#v:toJSON">toJSON</a></code> when the type
is an instance of <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code>.</p></div></div><div class="top"><p class="src"><a name="v:genericToEncoding" class="def">genericToEncoding</a> :: (<a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a> a, <a href="Data-Aeson.html#t:GToJSON">GToJSON</a> (<a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a> a)) => <a href="Data-Aeson-Types.html#t:Options">Options</a> -> a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a> <a href="src/Data-Aeson-Types-Class.html#genericToEncoding" class="link">Source</a></p><div class="doc"><p>A configurable generic JSON encoder. This function applied to
<code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code> is used as the default for <code><a href="Data-Aeson.html#v:toEncoding">toEncoding</a></code> when the type
is an instance of <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code>.</p></div></div><div class="top"><p class="src"><a name="v:genericParseJSON" class="def">genericParseJSON</a> :: (<a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a> a, <a href="Data-Aeson.html#t:GFromJSON">GFromJSON</a> (<a href="../base-4.8.1.0/GHC-Generics.html#t:Rep">Rep</a> a)) => <a href="Data-Aeson-Types.html#t:Options">Options</a> -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Class.html#genericParseJSON" class="link">Source</a></p><div class="doc"><p>A configurable generic JSON decoder. This function applied to
<code><a href="Data-Aeson.html#v:defaultOptions">defaultOptions</a></code> is used as the default for <code><a href="Data-Aeson.html#v:parseJSON">parseJSON</a></code> when the
type is an instance of <code><a href="../base-4.8.1.0/GHC-Generics.html#t:Generic">Generic</a></code>.</p></div></div><div class="top"><p class="src"><a name="v:defaultOptions" class="def">defaultOptions</a> :: <a href="Data-Aeson-Types.html#t:Options">Options</a> <a href="src/Data-Aeson-Types-Internal.html#defaultOptions" class="link">Source</a></p><div class="doc"><p>Default encoding <code><a href="Data-Aeson-Types.html#t:Options">Options</a></code>:</p><pre><code><a href="Data-Aeson-Types.html#t:Options">Options</a></code>
{ <code><a href="Data-Aeson-Types.html#v:fieldLabelModifier">fieldLabelModifier</a></code> = id
, <code><a href="Data-Aeson-Types.html#v:constructorTagModifier">constructorTagModifier</a></code> = id
, <code><a href="Data-Aeson-Types.html#v:allNullaryToStringTag">allNullaryToStringTag</a></code> = True
, <code><a href="Data-Aeson-Types.html#v:omitNothingFields">omitNothingFields</a></code> = False
, <code><a href="Data-Aeson-Types.html#v:sumEncoding">sumEncoding</a></code> = <code><a href="Data-Aeson-Types.html#v:defaultTaggedObject">defaultTaggedObject</a></code>
}
</pre></div></div><h1 id="g:13">Inspecting <code><code><a href="Data-Aeson.html#t:Value">Value</a></code>s</code></h1><div class="top"><p class="src"><a name="v:withObject" class="def">withObject</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="Data-Aeson.html#t:Object">Object</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#withObject" class="link">Source</a></p><div class="doc"><p><code>withObject expected f value</code> applies <code>f</code> to the <code><a href="Data-Aeson.html#t:Object">Object</a></code> when <code>value</code> is an <code>Object</code>
and fails using <code><code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> expected</code> otherwise.</p></div></div><div class="top"><p class="src"><a name="v:withText" class="def">withText</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#withText" class="link">Source</a></p><div class="doc"><p><code>withText expected f value</code> applies <code>f</code> to the <code><a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a></code> when <code>value</code> is a <code>String</code>
and fails using <code><code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> expected</code> otherwise.</p></div></div><div class="top"><p class="src"><a name="v:withArray" class="def">withArray</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="Data-Aeson.html#t:Array">Array</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#withArray" class="link">Source</a></p><div class="doc"><p><code>withArray expected f value</code> applies <code>f</code> to the <code><a href="Data-Aeson.html#t:Array">Array</a></code> when <code>value</code> is an <code>Array</code>
and fails using <code><code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> expected</code> otherwise.</p></div></div><div class="top"><p class="src"><a name="v:withNumber" class="def">withNumber</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../attoparsec-0.13.0.1/Data-Attoparsec-Number.html#t:Number">Number</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#withNumber" class="link">Source</a></p><div class="doc"><div class="warning"><p>Deprecated: Use withScientific instead</p></div><p><code>withNumber expected f value</code> applies <code>f</code> to the <code><a href="../attoparsec-0.13.0.1/Data-Attoparsec-Number.html#t:Number">Number</a></code> when <code>value</code> is a <code><a href="../attoparsec-0.13.0.1/Data-Attoparsec-Number.html#t:Number">Number</a></code>.
and fails using <code><code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> expected</code> otherwise.</p></div></div><div class="top"><p class="src"><a name="v:withScientific" class="def">withScientific</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../scientific-0.3.4.2/Data-Scientific.html#t:Scientific">Scientific</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#withScientific" class="link">Source</a></p><div class="doc"><p><code>withScientific expected f value</code> applies <code>f</code> to the <code><a href="../scientific-0.3.4.2/Data-Scientific.html#t:Scientific">Scientific</a></code> number when <code>value</code> is a <code><a href="../attoparsec-0.13.0.1/Data-Attoparsec-Number.html#t:Number">Number</a></code>.
and fails using <code><code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> expected</code> otherwise.</p></div></div><div class="top"><p class="src"><a name="v:withBool" class="def">withBool</a> :: <a href="../base-4.8.1.0/Data-String.html#t:String">String</a> -> (<a href="../base-4.8.1.0/Data-Bool.html#t:Bool">Bool</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a) -> <a href="Data-Aeson.html#t:Value">Value</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#withBool" class="link">Source</a></p><div class="doc"><p><code>withBool expected f value</code> applies <code>f</code> to the <code><a href="../base-4.8.1.0/Data-Bool.html#t:Bool">Bool</a></code> when <code>value</code> is a <code>Bool</code>
and fails using <code><code><a href="Data-Aeson-Types.html#v:typeMismatch">typeMismatch</a></code> expected</code> otherwise.</p></div></div><h1 id="g:14">Constructors and accessors</h1><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:Series" class="def">Series</a> <a href="src/Data-Aeson-Types-Internal.html#Series" class="link">Source</a></p><div class="doc"><p>A series of values that, when encoded, should be separated by commas.</p></div><div class="subs instances"><p id="control.i:Series" class="caption collapser" onclick="toggleSection('i:Series')">Instances</p><div id="section.i:Series" class="show"><table><tr><td class="src clearfix"><span class="inst-left"><a href="../base-4.8.1.0/Data-Monoid.html#t:Monoid">Monoid</a> <a href="Data-Aeson.html#t:Series">Series</a></span> <a href="src/Data-Aeson-Types-Internal.html#line-320" class="link">Source</a></td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><a name="v:pairs" class="def">pairs</a> :: <a href="Data-Aeson.html#t:Series">Series</a> -> <a href="Data-Aeson.html#t:Encoding">Encoding</a> <a href="src/Data-Aeson-Encode-Functions.html#pairs" class="link">Source</a></p><div class="doc"><p>Encode a series of key/value pairs, separated by commas.</p></div></div><div class="top"><p class="src"><a name="v:foldable" class="def">foldable</a> :: (<a href="../base-4.8.1.0/Data-Foldable.html#t:Foldable">Foldable</a> t, <a href="Data-Aeson.html#t:ToJSON">ToJSON</a> a) => t a -> <a href="Data-Aeson.html#t:Encoding">Encoding</a> <a href="src/Data-Aeson-Encode-Functions.html#foldable" class="link">Source</a></p><div class="doc"><p>Encode a <code><a href="../base-4.8.1.0/Data-Foldable.html#t:Foldable">Foldable</a></code> as a JSON array.</p></div></div><div class="top"><p class="src"><a name="v:.:" class="def">(.:)</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="Data-Aeson.html#t:Object">Object</a> -> <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#.%3A" class="link">Source</a></p><div class="doc"><p>Retrieve the value associated with the given key of an <code><a href="Data-Aeson.html#t:Object">Object</a></code>.
The result is <code>empty</code> if the key is not present or the value cannot
be converted to the desired type.</p><p>This accessor is appropriate if the key and value <em>must</em> be present
in an object for it to be valid. If the key and value are
optional, use '(.:?)' instead.</p></div></div><div class="top"><p class="src"><a name="v:.:-63-" class="def">(.:?)</a> :: <a href="Data-Aeson.html#t:FromJSON">FromJSON</a> a => <a href="Data-Aeson.html#t:Object">Object</a> -> <a href="../text-1.2.1.3/Data-Text.html#t:Text">Text</a> -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> (<a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a) <a href="src/Data-Aeson-Types-Instances.html#.%3A%3F" class="link">Source</a></p><div class="doc"><p>Retrieve the value associated with the given key of an <code><a href="Data-Aeson.html#t:Object">Object</a></code>.
The result is <code><a href="../base-4.8.1.0/Data-Maybe.html#v:Nothing">Nothing</a></code> if the key is not present, or <code>empty</code> if
the value cannot be converted to the desired type.</p><p>This accessor is most useful if the key and value can be absent
from an object without affecting its validity. If the key and
value are mandatory, use '(.:)' instead.</p></div></div><div class="top"><p class="src"><a name="v:.-33--61-" class="def">(.!=)</a> :: <a href="Data-Aeson-Types.html#t:Parser">Parser</a> (<a href="../base-4.8.1.0/Data-Maybe.html#t:Maybe">Maybe</a> a) -> a -> <a href="Data-Aeson-Types.html#t:Parser">Parser</a> a <a href="src/Data-Aeson-Types-Instances.html#.%21%3D" class="link">Source</a></p><div class="doc"><p>Helper for use in combination with <code><a href="Data-Aeson.html#v:.:-63-">.:?</a></code> to provide default
values for optional JSON object fields.</p><p>This combinator is most useful if the key and value can be absent
from an object without affecting its validity and we know a default
value to assign in that case. If the key and value are mandatory,
use '(.:)' instead.</p><p>Example usage:</p><pre> v1 <- o <code><a href="Data-Aeson.html#v:.:-63-">.:?</a></code> "opt_field_with_dfl" .!= "default_val"
v2 <- o <code><a href="Data-Aeson.html#v:.:">.:</a></code> "mandatory_field"
v3 <- o <code><a href="Data-Aeson.html#v:.:-63-">.:?</a></code> "opt_field2"
</pre></div></div><div class="top"><p class="src"><a name="v:object" class="def">object</a> :: [<a href="Data-Aeson-Types.html#t:Pair">Pair</a>] -> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Types-Internal.html#object" class="link">Source</a></p><div class="doc"><p>Create a <code><a href="Data-Aeson.html#t:Value">Value</a></code> from a list of name/value <code><a href="Data-Aeson-Types.html#t:Pair">Pair</a></code>s. If duplicate
keys arise, earlier keys and their associated values win.</p></div></div><h1 id="g:15">Parsing</h1><div class="top"><p class="src"><a name="v:json" class="def">json</a> :: <a href="../attoparsec-0.13.0.1/Data-Attoparsec-ByteString.html#t:Parser">Parser</a> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Parser-Internal.html#json" class="link">Source</a></p><div class="doc"><p>Parse a top-level JSON value.</p><p>The conversion of a parsed value to a Haskell value is deferred
until the Haskell value is needed. This may improve performance if
only a subset of the results of conversions are needed, but at a
cost in thunk allocation.</p><p>This function is an alias for <code><a href="Data-Aeson-Parser.html#v:value">value</a></code>. In aeson 0.8 and earlier, it
parsed only object or array types, in conformance with the
now-obsolete RFC 4627.</p></div></div><div class="top"><p class="src"><a name="v:json-39-" class="def">json'</a> :: <a href="../attoparsec-0.13.0.1/Data-Attoparsec-ByteString.html#t:Parser">Parser</a> <a href="Data-Aeson.html#t:Value">Value</a> <a href="src/Data-Aeson-Parser-Internal.html#json%27" class="link">Source</a></p><div class="doc"><p>Parse a top-level JSON value.</p><p>This is a strict version of <code><a href="Data-Aeson.html#v:json">json</a></code> which avoids building up thunks
during parsing; it performs all conversions immediately. Prefer
this version if most of the JSON data needs to be accessed.</p><p>This function is an alias for <code><a href="Data-Aeson-Parser.html#v:value-39-">value'</a></code>. In aeson 0.8 and earlier, it
parsed only object or array types, in conformance with the
now-obsolete RFC 4627.</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.16.1</p></div></body></html>