Merge pull request #12 from kRITZCREEK/documentation

Documentation for prismaticCodec

Author: garyb

src/Data/Codec/Argonaut.purs

@@ -11,6 +11,7 @@ module Data.Codec.Argonaut
   , char
   , jarray
   , jobject
+  , void
   , array
   , JIndexedCodec
   , indexedArray
@@ -125,6 +126,11 @@ jobject ∷ JsonCodec J.JObject
 jobject = jsonPrimCodec "Object" J.toObject J.fromObject
 
 -- | A codec for `Array` values.
+-- |```purescript
+-- | decodeIntArray ∷ Json → Either JsonDecodeError (Array Int)
+-- | decodeIntArray = decode (array int)
+-- |```
+
 array ∷ ∀ a. JsonCodec a → JsonCodec (Array a)
 array codec = GCodec dec enc
   where
@@ -143,6 +149,18 @@ type JIndexedCodec a =
     a 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:
+-- |
+-- | ```purescript
+-- | type Person = { name ∷ String, age ∷ Int }
+-- |
+-- | JA.indexedArray "Test Object" $
+-- |   { name: _, age: _ }
+-- |     <$> _.name ~ index 0 JA.string
+-- |     <*> _.age ~ index 1 JA.int
+-- | ```
 indexedArray ∷ ∀ a. String → JIndexedCodec a → JsonCodec a
 indexedArray name =
   bihoistGCodec
@@ -254,8 +272,32 @@ 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:
+-- |
+-- | ```purescript
+-- | data Direction = North | South | West | East
+-- |
+-- | directionCodec :: JsonCodec Direction
+-- | directionCodec = prismaticCodec dec enc string
+-- |   where
+-- |     dec = case _ of
+-- |       "N" -> Just North
+-- |       "S" -> Just South
+-- |       "W" -> Just West
+-- |       "E" -> Just East
+-- |       _ -> Nothing
+-- |
+-- |     enc = case _ of
+-- |       North -> "N"
+-- |       South -> "S"
+-- |       West -> "W"
+-- |       East -> "E"
+-- | ```
 prismaticCodec ∷ ∀ a b. (a → Maybe b) → (b → a) → JsonCodec a → JsonCodec b
 prismaticCodec f g orig =
   basicCodec
-    (\json → note (UnexpectedValue json) <<< f =<< (decode orig json))
+    (\json' → note (UnexpectedValue json') <<< f =<< decode orig json')
     (encode orig <<< g)

src/Data/Codec/Argonaut/Common.purs

@@ -18,6 +18,9 @@ import Data.StrMap as SM
 import Data.Tuple (Tuple(..), fst, snd)
 
 -- | A codec for `Maybe` values.
+-- |
+-- | NOTE: This is not suitable to en/decode null values. If you need these kinds of codecs,
+-- | look into `Data.Codec.Argonaut.Compat`
 maybe ∷ ∀ a. JsonCodec a → JsonCodec (Maybe a)
 maybe codec = taggedSum "Maybe" printTag parseTag dec enc
   where

src/Data/Codec/Argonaut/Compat.purs

@@ -21,6 +21,8 @@ import Data.Tuple (Tuple(..))
 
 -- | A codec for `Maybe` values.
 -- |
+-- | Encodes and decodes `Nothing` as `null`
+-- |
 -- | Note: this codec cannot represent nested `Maybe` values in a lossless
 -- | manner.
 maybe ∷ ∀ a. JsonCodec a → JsonCodec (Maybe a)
@@ -38,6 +40,10 @@ maybe codec = basicCodec dec enc
 -- | A codec for `StrMap` values.
 -- |
 -- | Encodes as a JSON object with the keys as properties.
+-- |
+-- | ```purescript
+-- | encode (strMap int) (Data.StrMap.fromFoldable [Tuple "a" 1, Tuple "b" 2]) == "{ \"a\": 1, \"b\": 2}"
+-- | ```
 strMap ∷ ∀ a. JsonCodec a → JsonCodec (SM.StrMap a)
 strMap codec =
   mapCodec

src/Data/Codec/Argonaut/Generic.purs

@@ -10,6 +10,17 @@ import Data.Either (Either(..), note)
 import Data.Generic.Rep (class Generic, Constructor(..), NoArguments(..), Sum(..), from, to)
 import Data.Symbol (class IsSymbol, SProxy(..), reflectSymbol)
 
+-- | Encodes nullary sums with a Generic instance as strings that match the constructor names.
+-- |
+-- | ```purescript
+-- | import Data.Argonaut as J
+-- |
+-- | data MySum = Ctor1 | Ctor2 | MoarCtors
+-- | derive instance genericMySum ∷ Generic MySum _
+-- |
+-- | encode nullarySum Ctor1 == J.fromString "Ctor1"
+-- | decode nullarySum (J.fromString "MoarCtors") == Right MoarCtors
+-- |```
 nullarySum ∷ ∀ a r. Generic a r ⇒ NullarySumCodec r ⇒ String → CA.JsonCodec a
 nullarySum name =
   C.basicCodec

src/Data/Codec/Argonaut/Record.purs

@@ -34,6 +34,16 @@ instance rowListCodecCons ∷
     tail = rowListCodec (R.RLProxy ∷ R.RLProxy rs) ((unsafeCoerce ∷ Record ri → Record ri') codecs)
 
 -- | Constructs a record codec from a record of codecs.
+-- |
+-- | ```purescript
+-- | type Person = { name ∷ String, age ∷ Int }
+-- |
+-- | personCodec ∷ CA.JsonCodec Person
+-- | personCodec = CA.object "Person" (record { name: CA.string, age: CA.int })
+-- |
+-- | decode personCodec "{ name: \"Carl\", age:\"25\" }" == Right { name: "Carl", age: 25 }
+-- | ```
+
 record
   ∷ ∀ ri ro rl
   . R.RowToList ri rl

src/Data/Codec/Argonaut/Variant.purs

@@ -20,6 +20,28 @@ import Type.Equality as TE
 import Type.Row as R
 import Unsafe.Coerce (unsafeCoerce)
 
+-- | Allows building codecs for variants in combination with variantCase.
+-- |
+-- | Commonly used to write decoders for sum-types, by providing a mapping from
+-- | and to a Variant from that type and then using `dimap`.
+-- |
+-- |```purescript
+-- | codecMaybe ∷ ∀ a. JA.JsonCodec a → JA.JsonCodec (Maybe a)
+-- | codecMaybe codecA =
+-- |   dimap toVariant fromVariant
+-- |     (JAV.variant
+-- |       # JAV.variantCase _Just (Right codecA)
+-- |       # JAV.variantCase _Nothing (Left unit))
+-- |   where
+-- |   toVariant = case _ of
+-- |     Just a → V.inj _Just a
+-- |     Nothing → V.inj _Nothing unit
+-- |   fromVariant = V.case_
+-- |     # V.on _Just Just
+-- |     # V.on _Nothing (const Nothing)
+-- |   _Just = SProxy ∷ SProxy "just"
+-- |   _Nothing = SProxy ∷ SProxy "nothing"
+-- |```
 variant ∷ JsonCodec (Variant ())
 variant = GCodec (ReaderT (Left <<< UnexpectedValue)) (Star case_)
 

test/Test/Generic.purs

@@ -0,0 +1,28 @@
+module Test.Generic where
+
+import Prelude
+
+import Control.Monad.Eff.Console (log)
+import Data.Codec.Argonaut.Generic (nullarySum)
+import Data.Generic.Rep (class Generic)
+import Data.Generic.Rep.Show (genericShow)
+import Test.QuickCheck (QC, quickCheck)
+import Test.QuickCheck.Arbitrary (genericArbitrary)
+import Test.QuickCheck.Gen (Gen)
+import Test.Util (propCodec)
+
+data MySum = Ctor1 | Ctor2 | MoarCtors
+
+derive instance eqMySum ∷ Eq MySum
+derive instance genericMySum ∷ Generic MySum _
+
+instance showMySum ∷ Show MySum where
+  show = genericShow
+
+genMySum ∷ Gen MySum
+genMySum = genericArbitrary
+
+main ∷ QC () Unit
+main = do
+  log "Check nullarySum"
+  quickCheck (propCodec genMySum (nullarySum "MySum"))

test/Test/Main.purs

@@ -6,7 +6,8 @@ import Control.Monad.Eff.Console (log)
 import Test.Common as Common
 import Test.Compat as Compat
 import Test.Migration as Migration
-import Test.Prim as Prim
+import Test.Prim as TestPrim
+import Test.Generic as Generic
 import Test.QuickCheck (QC)
 import Test.Variant as Variant
 import Test.Record as Record
@@ -15,7 +16,7 @@ main :: QC () Unit
 main = do
   log "Checking Prim codecs"
   log "------------------------------------------------------------"
-  Prim.main
+  TestPrim.main
   log ""
   log "Checking Common codecs"
   log "------------------------------------------------------------"
@@ -36,3 +37,7 @@ main = do
   log "Checking Migration codecs"
   log "------------------------------------------------------------"
   Migration.main
+  log ""
+  log "Checking Generic codecs"
+  log "------------------------------------------------------------"
+  Generic.main