mirror of
https://github.com/NorfairKing/autodocodec.git
synced 2024-09-11 14:36:05 +03:00
Readme and documentation efforts
This commit is contained in:
parent
ac755572fb
commit
1f16d4ccb6
20
README.md
20
README.md
@ -2,9 +2,29 @@
|
|||||||
|
|
||||||
Autodocodec is short for "self(auto)- documenting encoder and decoder".
|
Autodocodec is short for "self(auto)- documenting encoder and decoder".
|
||||||
|
|
||||||
|
In short:
|
||||||
|
You write one (1) instance, of the 'Codec' type-class, for your type, and you get:
|
||||||
|
|
||||||
|
* [A 'ToJSON' instance from 'aeson'](https://hackage.haskell.org/package/aeson-2.0.1.0/docs/Data-Aeson-Types.html#t:ToJSON)
|
||||||
|
* [A 'FromJSON' instance from 'aeson'](https://hackage.haskell.org/package/aeson-2.0.1.0/docs/Data-Aeson-Types.html#t:FromJSON)
|
||||||
|
* [A json schema](http://json-schema.org/)
|
||||||
|
* A human-readable yaml schema
|
||||||
|
* Hopefully soon also: A swagger schema
|
||||||
|
* Hopefully soon also: An openapi schema
|
||||||
|
* Potentially also: bson instances for mongodb
|
||||||
|
|
||||||
|
## DISCLAIMER: This is a work in progress.
|
||||||
|
|
||||||
|
This is not ready for production, it is not in use in any of my own projects yet, I do not recommend using it yet.
|
||||||
|
|
||||||
|
* Documentation is not complete.
|
||||||
|
* Some pieces of the implementation
|
||||||
|
|
||||||
## Goals:
|
## Goals:
|
||||||
|
|
||||||
* Correct-by-construction encoding and decoding, without generating code.
|
* Correct-by-construction encoding and decoding, without generating code.
|
||||||
* Generate automatically-correct documentation from code.
|
* Generate automatically-correct documentation from code.
|
||||||
* Fun but not important: Be able to provide instances without depending on aeson and/or yaml.
|
* Fun but not important: Be able to provide instances without depending on aeson and/or yaml.
|
||||||
* Would be nice: support for recursive types.
|
* Would be nice: support for recursive types.
|
||||||
|
|
||||||
|
|
||||||
|
@ -42,16 +42,20 @@ data Codec input output where
|
|||||||
BoolCodec ::
|
BoolCodec ::
|
||||||
-- |
|
-- |
|
||||||
Codec Bool Bool
|
Codec Bool Bool
|
||||||
-- | A String value
|
-- | Encode 'Text' to a @string@ value, and decode a @string@ value as a 'Text'.
|
||||||
--
|
--
|
||||||
-- This is named after the primitive type "String" in json, not after the haskell type string.
|
-- This is named after the primitive type "String" in json, not after the haskell type string.
|
||||||
StringCodec ::
|
StringCodec ::
|
||||||
-- |
|
-- |
|
||||||
Codec Text Text
|
Codec Text Text
|
||||||
|
-- | Encode 'Scientific' to a @number@ value, and decode a @number@ value as a 'Scientific'.
|
||||||
|
--
|
||||||
|
-- NOTE: We use 'Scientific' here because that is what aeson uses.
|
||||||
|
-- TODO: Can we do this without 'Scientific'? It has too many footguns.
|
||||||
NumberCodec ::
|
NumberCodec ::
|
||||||
-- |
|
-- |
|
||||||
Codec Scientific Scientific -- TODO can we do this without scientific?
|
Codec Scientific Scientific
|
||||||
-- TODO use a vector here because that's what aeson uses.
|
-- TODO use a vector here because that's what aeson uses.
|
||||||
ArrayCodec ::
|
ArrayCodec ::
|
||||||
-- |
|
-- |
|
||||||
!(Maybe Text) ->
|
!(Maybe Text) ->
|
||||||
@ -217,20 +221,62 @@ maybeCodec = bimapCodec f g . EitherCodec nullCodec
|
|||||||
instance Functor (Codec input) where
|
instance Functor (Codec input) where
|
||||||
fmap = fmapCodec
|
fmap = fmapCodec
|
||||||
|
|
||||||
|
-- | An autodocodec for objects.
|
||||||
|
-- See 'Codec' for more information about the two type parameters.
|
||||||
data ObjectCodec input output where
|
data ObjectCodec input output where
|
||||||
RequiredKeyCodec :: Text -> Codec input output -> ObjectCodec input output
|
RequiredKeyCodec ::
|
||||||
OptionalKeyCodec :: Text -> Codec input output -> ObjectCodec (Maybe input) (Maybe output)
|
-- |
|
||||||
PureObjectCodec :: output -> ObjectCodec input output
|
Text ->
|
||||||
BimapObjectCodec :: (oldOutput -> newOutput) -> (newInput -> oldInput) -> ObjectCodec oldInput oldOutput -> ObjectCodec newInput newOutput
|
-- |
|
||||||
ApObjectCodec :: ObjectCodec input (output -> newOutput) -> ObjectCodec input output -> ObjectCodec input newOutput
|
Codec input output ->
|
||||||
|
-- |
|
||||||
|
ObjectCodec input output
|
||||||
|
OptionalKeyCodec ::
|
||||||
|
-- |
|
||||||
|
Text ->
|
||||||
|
-- |
|
||||||
|
Codec input output ->
|
||||||
|
-- |
|
||||||
|
ObjectCodec (Maybe input) (Maybe output)
|
||||||
|
PureObjectCodec ::
|
||||||
|
-- |
|
||||||
|
output ->
|
||||||
|
-- |
|
||||||
|
ObjectCodec input output
|
||||||
|
BimapObjectCodec ::
|
||||||
|
-- |
|
||||||
|
(oldOutput -> newOutput) ->
|
||||||
|
-- |
|
||||||
|
(newInput -> oldInput) ->
|
||||||
|
-- |
|
||||||
|
ObjectCodec oldInput oldOutput ->
|
||||||
|
-- |
|
||||||
|
ObjectCodec newInput newOutput
|
||||||
|
ApObjectCodec ::
|
||||||
|
-- |
|
||||||
|
ObjectCodec input (output -> newOutput) ->
|
||||||
|
-- |
|
||||||
|
ObjectCodec input output ->
|
||||||
|
-- |
|
||||||
|
ObjectCodec input newOutput
|
||||||
|
|
||||||
fmapObjectCodec :: (oldOutput -> newOutput) -> ObjectCodec input oldOutput -> ObjectCodec input newOutput
|
fmapObjectCodec ::
|
||||||
|
(oldOutput -> newOutput) ->
|
||||||
|
ObjectCodec input oldOutput ->
|
||||||
|
ObjectCodec input newOutput
|
||||||
fmapObjectCodec f = BimapObjectCodec f id
|
fmapObjectCodec f = BimapObjectCodec f id
|
||||||
|
|
||||||
comapObjectCodec :: (newInput -> oldInput) -> ObjectCodec oldInput output -> ObjectCodec newInput output
|
comapObjectCodec ::
|
||||||
|
(newInput -> oldInput) ->
|
||||||
|
ObjectCodec oldInput output ->
|
||||||
|
ObjectCodec newInput output
|
||||||
comapObjectCodec g = BimapObjectCodec id g
|
comapObjectCodec g = BimapObjectCodec id g
|
||||||
|
|
||||||
bimapObjectCodec :: (oldOutput -> newOutput) -> (newInput -> oldInput) -> ObjectCodec oldInput oldOutput -> ObjectCodec newInput newOutput
|
bimapObjectCodec ::
|
||||||
|
(oldOutput -> newOutput) ->
|
||||||
|
(newInput -> oldInput) ->
|
||||||
|
ObjectCodec oldInput oldOutput ->
|
||||||
|
ObjectCodec newInput newOutput
|
||||||
bimapObjectCodec = BimapObjectCodec
|
bimapObjectCodec = BimapObjectCodec
|
||||||
|
|
||||||
instance Functor (ObjectCodec input) where
|
instance Functor (ObjectCodec input) where
|
||||||
|
Loading…
Reference in New Issue
Block a user