Merge pull request #22 from garyb/more-docs

More docs

Author: garyb

README.md

@@ -5,7 +5,9 @@
 
 Bi-directional codecs for [argonaut](https://github.com/purescript-contrib/purescript-argonaut-core).
 
-This library is build on `purescript-codec` and offers a different approach to dealing with JSON encoding/decoding than `purescript-argonaut-codecs`. Instead of using type classes, codecs are constructed as values explicitly. As long as the basic codec values provided by this library are used, the codecs are guaranteed to roundtrip succesfully.
+This library is build on [`purescript-codec`](https://github.com/garyb/purescript-codec) and offers a different approach to dealing with JSON encoding/decoding than [`purescript-argonaut-codecs`](https://github.com/purescript-contrib/purescript-argonaut-codecs). Instead of using type classes, codecs are constructed as values explicitly. As long as the basic codec values provided by this library are used, the codecs are guaranteed to roundtrip successfully.
+
+The errors reported from this library are a little better than those provided by `purescript-argonaut-codecs` too - they contain the full JSON structure to the point of failure, and the error can be inspected as a value before being printed as a string.
 
 For more information on the motivation behind this library, I [wrote a bit about my problems with typeclass codecs](http://code.slipthrough.net/2018/03/13/thoughts-on-typeclass-codecs/) previously.
 
@@ -15,6 +17,186 @@ For more information on the motivation behind this library, I [wrote a bit about
 bower install purescript-codec-argonaut
 ```
 
+## Usage
+
+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)):
+
+``` purescript
+import Data.Argonaut.Core as J
+import Data.Codec.Argonaut as CA
+import Data.Either (Either)
+
+encodeString ∷ String → J.Json
+encodeString = CA.encode CA.string
+
+decodeString ∷ J.Json → Either CA.JsonDecodeError String
+decodeString = CA.decode CA.string
+```
+
+### Basic codecs
+
+A number of codecs are provided for basic types such as `Boolean`, `Number`, `Int`, `String`, `CodePoint`, `Char`, and are named as such but starting lowercase. So [`CA.boolean`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:boolean), [`CA.number`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:number), and so on.
+
+There is also a `Json` "identity" codec called [`CA.json`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:json) that just passes the value through either way. This is sometimes useful when building up a larger codec. More on that in a moment.
+
+The final two basic codecs are [`CA.null`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:null), which decodes to `Unit` in PureScript and encodes to `null` in JSON, and [`CA.void`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:void), which is an eliminator for `Void` in PureScript and will never actualy encode or decode anything since `Void` is uninhabited. This is another codec that is primarily intended for use in larger codecs.
+
+So far so boring. Things only start getting interesting or useful when we can build up larger codecs for our data model or serialization format, which is where compound codecs come in to play.
+
+### Arrays
+
+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:
+
+``` purescript
+import Data.Codec.Argonaut as CA
+
+codec ∷ CA.JsonCodec (Array String)
+codec = CA.array CA.string
+```
+
+### Objects
+
+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):
+
+``` purescript
+import Data.Codec.Argonaut as CA
+import Data.Codec.Argonaut.Record as CAR
+
+type Person = { name ∷ String, age ∷ Int, active ∷ Boolean }
+
+codec ∷ CA.JsonCodec Person
+codec =
+  CA.object "Person"
+    (CAR.record
+      { name: CA.string
+      , age: CA.int
+      , active: CA.boolean
+      })
+```
+
+Note we also used a [`CA.object`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:object) wrapping this [`CAR.record`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Record#v:record). This allows us to name the record, for help when debugging decode failures, but is also because [`CAR.record`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Record#v:record) produces a [`JPropCodec`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#t:JPropCodec) rather than a [`JsonCodec`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#t:JsonCodec) directly. There are some other options for constructing and working with [`JPropCodec`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#t:JPropCodec) values, but that's out of the scope of this README.
+
+The codec will encode/decode JSON objects of the same shape as the defining record. For example:
+
+``` json
+{ "name": "Rashida", "age": 37, "active": true }
+```
+
+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:
+
+``` purescript
+type Person = { "Name" ∷ String, age ∷ Int, "is active" ∷ Boolean }
+
+codec ∷ CA.JsonCodec Person
+codec =
+  CA.object "Person"
+    (CAR.record
+      { "Name": CA.string
+      , age: CA.int
+      , "is active": CA.boolean
+      })
+```
+
+### Sum types and variants
+
+This library comes with codec support for [`purescript-variant`](https://github.com/natefaubion/purescript-variant) out of the box and codecs for sums are often based on the variant codec.
+
+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):
+
+``` purescript
+import Prelude
+
+import Data.Codec.Argonaut as CA
+import Data.Codec.Argonaut.Variant as CAV
+import Data.Either (Either(..))
+import Data.Variant as V
+
+type SomeValue = V.Variant
+  ( str ∷ String
+  , int ∷ Int
+  , neither ∷ Unit
+  )
+
+codec ∷ CA.JsonCodec SomeValue
+codec = CAV.variantMatch
+  { str: Right CA.string
+  , int: Right CA.int
+  , neither: Left unit
+  }
+```
+
+The fields in the record passed to [`CAV.variantMatch`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Variant#v:variantMatch) correspond with the variant constructors. Each one accepts an `Either` carrying either a codec or a static value - `Right` with a codec for when there's a value that needs encoding for the constructor, `Left` with a static value for nullary constructors.
+
+The variant codec is a little opinionated since there's no exactly corresponding JSON structure for sums. The encoding looks something like:
+
+``` json
+{ "tag": <constructorName>, "value": <value> }
+```
+
+`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.
+
+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:
+
+``` purescript
+import Prelude
+
+import Data.Codec.Argonaut as CA
+import Data.Codec.Argonaut.Variant as CAV
+import Data.Either (Either(..))
+import Data.Profunctor (dimap)
+import Data.Symbol (SProxy(..))
+import Data.Variant as V
+
+data SomeValue2 = Str String | Int Int | Neither
+
+codec ∷ CA.JsonCodec SomeValue2
+codec =
+  dimap toVariant fromVariant $ CAV.variantMatch
+    { str: Right CA.string
+    , int: Right CA.int
+    , neither: Left unit
+    }
+  where
+    toVariant = case _ of
+      Str s → V.inj (SProxy ∷ _ "str") s
+      Int i → V.inj (SProxy ∷ _ "int") i
+      Neither → V.inj (SProxy ∷ _ "neither") unit
+    fromVariant = V.match
+      { str: Str
+      , int: Int
+      , neither: \_ → Neither
+      }
+```
+
+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.
+
+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.
+
+The story for sum type codecs outside of these options isn't great just now. There are some functions provided in [`Data.Codec.Argonaut.Sum`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Sum) for defining them, but these are more error prone than the variant method, and use the same encoding methods described above. Often it's just as easy to construct a codec from scratch with [`basicCodec`](https://pursuit.purescript.org/packages/purescript-codec/docs/Data.Codec#v:basicCodec) from [`Data.Codec`](https://pursuit.purescript.org/packages/purescript-codec/docs/Data.Codec), although means it's up to you to ensure the roundtrip succeeds.
+
+### Other common types
+
+The library provides a [`Data.Codec.Argonaut.Common`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Common) module with codecs for `Maybe`, `Either`, `Tuple`, and so on. These codecs are somewhat opinionated, so only suitable for cases when you are in control of the serialization format.
+
+There is also a [`Data.Codec.Argonaut.Compat`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut.Compat) module provided for codecs that need to preserve compatibility with the encoding using by [`purescript-argonaut-codecs`](https://github.com/purescript-contrib/purescript-argonaut-codecs). These codecs have some issues, like the inability to accurately encode nested `Maybe`s, so if possible, `Common` should be preferred.
+
+### "Prismatic" codecs
+
+If you have a type with a pair of functions like the `preview` and `view` that make up a prism (`preview :: a -> Maybe b`, `view :: b -> a`), you can use these to adapt an existing codec to further refine it.
+
+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:
+
+``` purescript
+import Data.Codec.Argonaut as CA
+import Data.String.NonEmpty (NonEmptyString)
+import Data.String.NonEmpty as NES
+
+codec ∷ CA.JsonCodec NonEmptyString
+codec = CA.prismaticCodec NES.fromString NES.toString CA.string
+```
+
+See the documentation for [another example](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:prismaticCodec) of how [`CA.prismaticCodec`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:prismaticCodec) might be used. The main downside to [`CA.prismaticCodec`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#v:prismaticCodec) is the error reporting for the `Nothing` case might not be good as it otherwise could be, since [`UnexpectedValue`](https://pursuit.purescript.org/packages/purescript-codec-argonaut/docs/Data.Codec.Argonaut#t:JsonDecodeError) is the only information we have at that point.
+
 ## Documentation
 
 Module documentation is [published on Pursuit](http://pursuit.purescript.org/packages/purescript-codec-argonaut).

src/Data/Codec/Argonaut.purs

@@ -8,6 +8,7 @@ module Data.Codec.Argonaut
   , number
   , int
   , string
+  , codePoint
   , char
   , jarray
   , jobject
@@ -34,7 +35,7 @@ import Data.Argonaut.Core as J
 import Data.Array as A
 import Data.Bifunctor as BF
 import Data.Codec (BasicCodec, Codec, GCodec(..), basicCodec, bihoistGCodec, decode, encode)
-import Data.Codec (decode, encode, (~), (<~<)) as Exports
+import Data.Codec (decode, encode, (~), (<~<), (>~>)) as Exports
 import Data.Either (Either(..), note)
 import Data.Generic.Rep (class Generic)
 import Data.Int as I
@@ -136,12 +137,15 @@ jarray = jsonPrimCodec "Array" J.toArray J.fromArray
 jobject ∷ JsonCodec (FO.Object J.Json)
 jobject = jsonPrimCodec "Object" J.toObject J.fromObject
 
--- | A codec for `Array` values.
--- |```purescript
--- | decodeIntArray ∷ Json → Either JsonDecodeError (Array Int)
--- | decodeIntArray = decode (array int)
--- |```
-
+-- | A codec for arbitrary length `Array`s where every item in the array
+-- | shares the same type.
+-- |
+-- | ``` purescript
+-- | import Data.Codec.Argonaut as CA
+-- |
+-- | codecIntArray ∷ CA.JsonCodec (Array Int)
+-- | codecIntArray = CA.array CA.int
+-- | ```
 array ∷ ∀ a. JsonCodec a → JsonCodec (Array a)
 array codec = GCodec dec enc
   where
@@ -161,16 +165,20 @@ type JIndexedCodec a =
 
 -- | A codec for types that are encoded as an array with a specific layout.
 -- |
--- | For example, given that we'd like to encode a Person as a 2-element array,
--- | like so `[ "Karl", 25 ]`, we could write the following codec:
+-- | For example, if we'd like to encode a `Person` as a 2-element array, like
+-- | `["Rashida", 37]`, we could write the following codec:
 -- |
 -- | ```purescript
+-- | import Data.Codec ((~))
+-- | import Data.Codec.Argonaut as CA
+-- |
 -- | type Person = { name ∷ String, age ∷ Int }
 -- |
--- | JA.indexedArray "Test Object" $
+-- | codecPerson ∷ CA.JsonCodec Person
+-- | codecPerson = CA.indexedArray "Test Object" $
 -- |   { name: _, age: _ }
--- |     <$> _.name ~ index 0 JA.string
--- |     <*> _.age ~ index 1 JA.int
+-- |     <$> _.name ~ CA.index 0 CA.string
+-- |     <*> _.age ~ CA.index 1 CA.int
 -- | ```
 indexedArray ∷ ∀ a. String → JIndexedCodec a → JsonCodec a
 indexedArray name =
@@ -197,6 +205,9 @@ type JPropCodec a =
     a a
 
 -- | A codec for objects that are encoded with specific properties.
+-- |
+-- | See also `Data.Codec.Argonaut.Record.object` for a more commonly useful
+-- | version of this function.
 object ∷ ∀ a. String → JPropCodec a → JsonCodec a
 object name =
   bihoistGCodec
@@ -219,13 +230,23 @@ prop key codec = GCodec dec enc
 -- | provides a convenient method for defining codecs for record types that
 -- | encode into JSON objects of the same shape.
 -- |
--- | For example:
+-- | For example, to encode a record as the JSON object
+-- | `{ "name": "Karl", "age": 25 }` we would define a codec like this:
 -- | ```
--- | myRecordCodec =
--- |   object "MyRecord" $ record
--- |     # recordProp (SProxy :: SProxy "tag") tagCodec
--- |     # recordProp (SProxy :: SProxy "value") valueCodec
+-- | import Data.Codec.Argonaut as CA
+-- | import Data.Symbol (SProxy(..))
+-- |
+-- | type Person = { name ∷ String, age ∷ Int }
+-- |
+-- | codecPerson ∷ CA.JsonCodec Person
+-- | codecPerson =
+-- |   CA.object "Person" $ CA.record
+-- |     # CA.recordProp (SProxy :: _ "name") CA.string
+-- |     # CA.recordProp (SProxy :: _ "age") CA.int
 -- | ```
+-- |
+-- | See also `Data.Codec.Argonaut.Record.object` for a more commonly useful
+-- | version of this function.
 record ∷ JPropCodec {}
 record = GCodec (pure {}) (Star \val → writer (Tuple val L.Nil))
 
@@ -270,7 +291,27 @@ jsonPrimCodec
 jsonPrimCodec ty f =
   basicCodec (maybe (Left (TypeMismatch ty)) pure <<< f)
 
--- | Helper function for defining recursive codecs.
+-- | Helper function for defining recursive codecs in situations where the codec
+-- | definition causes a _"The value of <codec> is undefined here"_ error.
+-- |
+-- | ```purescript
+-- | import Data.Codec.Argonaut as CA
+-- | import Data.Codec.Argonaut.Common as CAC
+-- | import Data.Codec.Argonaut.Record as CAR
+-- | import Data.Maybe (Maybe)
+-- | import Data.Newtype (class Newtype)
+-- | import Data.Profunctor (wrapIso)
+-- |
+-- | newtype IntList = IntList { cell ∷ Int, rest ∷ Maybe IntList }
+-- |
+-- | derive instance newtypeLoopyList ∷ Newtype IntList _
+-- |
+-- | codecIntList ∷ CA.JsonCodec IntList
+-- | codecIntList =
+-- |   CA.fix \codec →
+-- |     wrapIso IntList $
+-- |       CAR.object "IntList" { cell: CA.int, rest: CAC.maybe codec }
+-- | ```
 fix ∷ ∀ a. (JsonCodec a → JsonCodec a) → JsonCodec a
 fix f =
   basicCodec
@@ -284,9 +325,15 @@ fix f =
 -- | This function is named as such as the pair of functions it accepts
 -- | correspond with the `preview` and `view` functions of a `Prism`-style lens.
 -- |
--- | For example, in order to parse a mapping from an enum to strings, which
--- | doesn't match up nicely with `Data.Codec.Argonaut.Sum.enumSum` we can use
--- | prismaticCodec:
+-- | An example of this would be a codec for `Data.String.NonEmpty.NonEmptyString`:
+-- |
+-- | ```purescript
+-- | nonEmptyString ∷ CA.JsonCodec NES.NonEmptyString
+-- | nonEmptyString = CA.prismaticCodec NES.fromString NES.toString CA.string
+-- | ```
+-- |
+-- | Another example might be to handle a mapping from a small sum type to
+-- | strings:
 -- |
 -- | ```purescript
 -- | data Direction = North | South | West | East
@@ -307,6 +354,9 @@ fix f =
 -- |       West -> "W"
 -- |       East -> "E"
 -- | ```
+-- |
+-- | Although for this latter case there are some other options too, in the form
+-- | of `Data.Codec.Argonaut.Generic.nullarySum` and `Data.Codec.Argonaut.Sum.enumSum`.
 prismaticCodec ∷ ∀ a b. (a → Maybe b) → (b → a) → JsonCodec a → JsonCodec b
 prismaticCodec f g orig =
   basicCodec