You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As [`JsonCodec`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#t:JsonCodec)s are values, they need to be fed into the [`encode`](https://pursuit.purescript.org/packages/purescript-codec/docs/Data.Codec/#v:encode) or [`decode`](https://pursuit.purescript.org/packages/purescript-codec/docs/Data.Codec/#v:decode) function provided by [`Data.Codec`](https://pursuit.purescript.org/packages/purescript-codec/docs/Data.Codec) (and re-exported by [`Data.Codec.Argonaut`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut)):
23
23
24
-
```purescript
24
+
```purescript
25
25
import Data.Argonaut.Core as J
26
26
import Data.Codec.Argonaut as CA
27
27
import Data.Either (Either)
@@ -39,7 +39,7 @@ To parse a serialized `String` into a `J.Json` structure use the [`Parser.jsonPa
39
39
40
40
To /"stringify"/ (serialize) your `Array String` to a serialized JSON `String` we would use the [`stringify`](https://pursuit.purescript.org/packages/purescript-argonaut-core/5.1.0/docs/Data.Argonaut.Core#v:stringify) like so:
41
41
42
-
```purescript
42
+
```purescript
43
43
import Control.Category ((>>>))
44
44
45
45
serialize :: Array String -> String
@@ -60,7 +60,7 @@ So far so boring. Things only start getting interesting or useful when we can bu
60
60
61
61
The simplest compound codec provided by the library is [`CA.array`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:array), which accepts another codec, and encodes/decodes an arbitrary length array where all the items match the inner codec. For example:
62
62
63
-
```purescript
63
+
```purescript
64
64
import Data.Codec.Argonaut as CA
65
65
66
66
codec ∷ CA.JsonCodec (Array String)
@@ -71,7 +71,7 @@ codec = CA.array CA.string
71
71
72
72
Probably the most useful compound codec is for `Record`, this will generally be the building block of most codecs. There are a few different ways to define these codecs, but the most convenient is the [`record`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Record#v:record) function provided by [`Data.Codec.Argonaut.Record`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Record):
73
73
74
-
```purescript
74
+
```purescript
75
75
import Data.Codec.Argonaut as CA
76
76
import Data.Codec.Argonaut.Record as CAR
77
77
@@ -91,13 +91,13 @@ Note we also used a [`CA.object`](https://pursuit.purescript.org/packages/puresc
91
91
92
92
The codec will encode/decode JSON objects of the same shape as the defining record. For example:
93
93
94
-
```json
94
+
```json
95
95
{ "name": "Rashida", "age": 37, "active": true }
96
96
```
97
97
98
98
It's possible to encode/decode records that include properties with spaces and/or symbols in the name, or reserved names, by quoting the fields in the type and definition:
99
99
100
-
```purescript
100
+
```purescript
101
101
type Person = { "Name" ∷ String, age ∷ Int, "is active" ∷ Boolean }
102
102
103
103
codec ∷ CA.JsonCodec Person
@@ -116,7 +116,7 @@ This library comes with codec support for [`purescript-variant`](https://github.
116
116
117
117
First of all, variants. Similar to the object/record case there are a few options for defining variant codecs, but most commonly they will be defined with [`variantMatch`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Variant#v:variantMatch) provided by [`Data.Codec.Argonaut.Variant`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Variant):
118
118
119
-
```purescript
119
+
```purescript
120
120
import Prelude
121
121
122
122
import Data.Codec.Argonaut as CA
@@ -142,23 +142,23 @@ The fields in the record passed to [`CAV.variantMatch`](https://pursuit.purescri
142
142
143
143
The variant codec is a little opinionated since there's no exactly corresponding JSON structure for sums. The encoding looks something like:
144
144
145
-
```json
145
+
```json
146
146
{ "tag": <constructorName>, "value": <value> }
147
147
```
148
148
149
149
`value` will be omitted for nullary / `Left`-defined constructors. At the moment it is not possible to customise the encoding for variant types, so they may not be suitable if you are not in control of the serialization format.
150
150
151
151
Sum type encoding is usually handled by building a variant codec, and then using [`dimap`](https://pursuit.purescript.org/packages/purescript-profunctor/docs/Data.Profunctor#v:dimap) to inject into/project out of a corresponding sum type:
152
152
153
-
```purescript
153
+
```purescript
154
154
import Prelude
155
155
156
156
import Data.Codec.Argonaut as CA
157
157
import Data.Codec.Argonaut.Variant as CAV
158
158
import Data.Either (Either(..))
159
159
import Data.Profunctor (dimap)
160
-
import Data.Symbol (SProxy(..))
161
160
import Data.Variant as V
161
+
import Type.Proxy (Proxy(..))
162
162
163
163
data SomeValue2 = Str String | Int Int | Neither
164
164
@@ -171,17 +171,17 @@ codec =
171
171
}
172
172
where
173
173
toVariant = case _ of
174
-
Str s → V.inj (SProxy ∷ _ "str") s
175
-
Int i → V.inj (SProxy ∷ _ "int") i
176
-
Neither → V.inj (SProxy ∷ _ "neither") unit
174
+
Str s → V.inj (Proxy ∷ _ "str") s
175
+
Int i → V.inj (Proxy ∷ _ "int") i
176
+
Neither → V.inj (Proxy ∷ _ "neither") unit
177
177
fromVariant = V.match
178
178
{ str: Str
179
179
, int: Int
180
180
, neither: \_ → Neither
181
181
}
182
182
```
183
183
184
-
This certainly is a little boilerplate-y, but at least when defining codecs this way you do gain the benefits of having a single definition that aligns the encoding and decoding behaviour. This means, assuming there are no mixups in `toVariant`/`fromVariant`, the guaranteed roundtripping is preserved. Often it's not even possible to have mixups during `dimap`, since the sum constructor types will all differ.
184
+
This certainly is a little boilerplate-y, but at least when defining codecs this way you do gain the benefits of having a single definition that aligns the encoding and decoding behaviour. This means, assuming there are no mixups in `toVariant`/`fromVariant`, the guaranteed roundtripping is preserved. Often it's not even possible to have mixups during `dimap`, since the sum constructor types will all differ.
185
185
186
186
If you have a sum type that only consists of nullary constructors and it has a [`Generic`](https://pursuit.purescript.org/packages/purescript-generics-rep/docs/Data.Generic.Rep#t:Generic) instance defined, [`nullarySum`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Generic#v:nullarySum) provided by [`Data.Codec.Argonaut.Generic`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Generic) can generate a codec that will encode the constructors as string values matching the constructor names in the JSON.
187
187
@@ -197,7 +197,7 @@ There is also a [`Data.Codec.Argonaut.Compat`](https://pursuit.purescript.org/pa
197
197
198
198
If you have a codec for a `newtype` with a [`Newtype`](https://pursuit.purescript.org/packages/purescript-newtype/docs/Data.Newtype#t:Newtype) instance, you can use the [`wrapIso`](https://pursuit.purescript.org/packages/purescript-profunctor/docs/Data.Profunctor#v:wrapIso) function from [`purescript-profunctor`](https://github.com/purescript/purescript-profunctor) to adapt a codec to work with the `newtype`. For example:
199
199
200
-
```purescript
200
+
```purescript
201
201
import Data.Codec.Argonaut.Common as CA
202
202
import Data.Codec.Argonaut.Record as CAR
203
203
import Data.Newtype (class Newtype)
@@ -225,7 +225,7 @@ If you have a type with a pair of functions like the `preview` and `view` that m
225
225
226
226
For example, to adapt the [`CA.string`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:string) codec to only work for `NonEmptyString`s:
0 commit comments