From c2fff2a58a0732a2e9991c7513b8ddc4698295eb Mon Sep 17 00:00:00 2001 From: Peter Becich Date: Wed, 3 Jan 2024 23:55:58 -0800 Subject: [PATCH] improve readme, clean-up --- README.md | 134 +++++++++++---------- example/readme.md | 17 +-- example/src/Main.purs | 2 +- example/src/Types.hs | 5 +- example/static/index.html | 2 +- flake.nix | 9 +- src/Language/PureScript/Bridge.hs | 4 +- src/Language/PureScript/Bridge/Printer.hs | 4 +- src/Language/PureScript/Bridge/SumType.hs | 23 ++-- test/RoundTripArgonautAesonGeneric/Spec.hs | 11 +- test/RoundTripJsonHelpers/Spec.hs | 13 +- 11 files changed, 114 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 2aa450b5..58217b45 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,84 @@ # purescript-bridge - - -[![Haskell library and example](https://github.com/eskimor/purescript-bridge/actions/workflows/haskell.yml/badge.svg)](https://github.com/eskimor/purescript-bridge/actions/workflows/haskell.yml) [![Purescript example](https://github.com/eskimor/purescript-bridge/actions/workflows/purescript.yml/badge.svg)](https://github.com/eskimor/purescript-bridge/actions/workflows/purescript.yml) [![Nix Flake](https://github.com/eskimor/purescript-bridge/actions/workflows/nix-flake.yml/badge.svg)](https://github.com/eskimor/purescript-bridge/actions/workflows/nix-flake.yml) - - +[![Haskell library and example](https://github.com/eskimor/purescript-bridge/actions/workflows/haskell.yml/badge.svg)](https://github.com/eskimor/purescript-bridge/actions/workflows/haskell.yml) [![PureScript example](https://github.com/eskimor/purescript-bridge/actions/workflows/purescript.yml/badge.svg)](https://github.com/eskimor/purescript-bridge/actions/workflows/purescript.yml) [![Nix Flake](https://github.com/eskimor/purescript-bridge/actions/workflows/nix-flake.yml/badge.svg)](https://github.com/eskimor/purescript-bridge/actions/workflows/nix-flake.yml) Translate your Haskell types to PureScript types. It should in theory work for almost all Haskell types, including type constructors! You just have to instantiate it with dummy parameters from e.g. "Language.PureScript.Bridge.TypeParameters". Data type translation is fully and easily customizable by providing your own `BridgePart` instances! -The latest version of this project requires **Purescript 0.15**. +The latest version of this project requires **PureScript 0.15**. ## JSON encoding / decoding +### Haskell +Use [`aeson`](http://hackage.haskell.org/package/aeson)'s generic encoding/decoding with default options + +### PureScript +There are two PureScript libraries which can interface with Aeson through PureScript bridge. The second, `purescript-argonaut-aeson-generic`, has issues. + +#### [`input-output-hk/purescript-bridge-json-helpers`](https://github.com/input-output-hk/purescript-bridge-json-helpers.git) + +Enable this on the Haskell side with `Language.PureScript.Bridge.SumType.jsonHelpers`. + +* see `./test/RoundTripJsonHelpers` for example +* sample Dhall config (for [spago-legacy](https://github.com/purescript/spago-legacy)): +``` +, json-helpers = + { dependencies = + [ "aff" + , "argonaut-codecs" + , "argonaut-core" + , "arrays" + , "bifunctors" + , "contravariant" + , "control" + , "effect" + , "either" + , "enums" + , "foldable-traversable" + , "foreign-object" + , "maybe" + , "newtype" + , "ordered-collections" + , "prelude" + , "profunctor" + , "psci-support" + , "quickcheck" + , "record" + , "spec" + , "spec-quickcheck" + , "transformers" + , "tuples" + , "typelevel-prelude" + ] + , repo = + "https://github.com/input-output-hk/purescript-bridge-json-helpers.git" + , version = "486db9ee62882baa42cca24f556848c5f6bec565" + } +``` + +#### [`purescript-argonaut-aeson-generic >=0.4.1`](https://pursuit.purescript.org/packages/purescript-argonaut-aeson-generic/0.4.1) ([GitHub](https://github.com/coot/purescript-argonaut-aeson-generic)) + +Enable this on the Haskell side with `Language.PureScript.Bridge.SumType.argonautAesonGeneric`. -For compatible JSON representations: - -* On Haskell side, use: - * Use [`aeson`](http://hackage.haskell.org/package/aeson)'s generic encoding/decoding with default options -* On Purescript side, use: - * [`purescript-argonaut-aeson-generic >=0.4.1`](https://pursuit.purescript.org/packages/purescript-argonaut-aeson-generic/0.4.1) ([GitHub](https://github.com/coot/purescript-argonaut-aeson-generic)) - * additional requirement [`peterbecich/purescript-argonaut-codecs`](https://github.com/peterbecich/purescript-argonaut-codecs.git) - * commit `04abb3eb24a4deafe125be0eb23e2786c642e66b` - * see `./test/RoundTripArgonautAesonGeneric` for example - * sample Dhall config: - ``` - , argonaut-codecs = - { dependencies = [ "console" ] - , repo = "https://github.com/peterbecich/purescript-argonaut-codecs.git" - , version = "04abb3eb24a4deafe125be0eb23e2786c642e66b" - } - ``` - * forked from [`purescript-contrib/purescript-argonaut-codecs`](https://github.com/purescript-contrib/purescript-argonaut-codecs) - * [discussion](https://github.com/purescript-contrib/purescript-argonaut-codecs/issues/115) - * *or* [`input-output-hk/purescript-bridge-json-helpers`](https://github.com/input-output-hk/purescript-bridge-json-helpers.git) - * commit `486db9ee62882baa42cca24f556848c5f6bec565` - * see `./test/RoundTripJsonHelpers` for example - * sample Dhall config: - ``` - , json-helpers = - { dependencies = - [ "aff" - , "argonaut-codecs" - , "argonaut-core" - , "arrays" - , "bifunctors" - , "contravariant" - , "control" - , "effect" - , "either" - , "enums" - , "foldable-traversable" - , "foreign-object" - , "maybe" - , "newtype" - , "ordered-collections" - , "prelude" - , "profunctor" - , "psci-support" - , "quickcheck" - , "record" - , "spec" - , "spec-quickcheck" - , "transformers" - , "tuples" - , "typelevel-prelude" - ] - , repo = - "https://github.com/input-output-hk/purescript-bridge-json-helpers.git" - , version = "486db9ee62882baa42cca24f556848c5f6bec565" - } - ``` +This library is demonstrated by the `example`; see `./example/readme.md`. + +**TODO**: [resolve incompatibility between Argonaut and Aeson](https://github.com/purescript-contrib/purescript-argonaut-codecs/issues/115) + +**Additional requirement**: [`peterbecich/purescript-argonaut-codecs`](https://github.com/peterbecich/purescript-argonaut-codecs.git) +* commit `04abb3eb24a4deafe125be0eb23e2786c642e66b` +* see `./test/RoundTripArgonautAesonGeneric` for example + * note that some types have been disabled from the `RoundTripArgonautAesonGeneric` test + * `RoundTripJsonHelpers` tests more types + * the types tested can be expanded when the incompatibility issue is resolved +* sample Dhall config: +``` + , argonaut-codecs = + { dependencies = [ "console" ] + , repo = "https://github.com/peterbecich/purescript-argonaut-codecs.git" + , version = "04abb3eb24a4deafe125be0eb23e2786c642e66b" + } +``` +* forked from [`purescript-contrib/purescript-argonaut-codecs`](https://github.com/purescript-contrib/purescript-argonaut-codecs) ## Documentation diff --git a/example/readme.md b/example/readme.md index 5b93379a..5c426845 100644 --- a/example/readme.md +++ b/example/readme.md @@ -1,16 +1,17 @@ -# Purescript Bridge example +# PureScript Bridge example -This project demonstrates the libraries Purescript Bridge and [`input-output-hk/purescript-bridge-json-helpers`](https://github.com/input-output-hk/purescript-bridge-json-helpers.git). +This project demonstrates the libraries PureScript Bridge and [`purescript-argonaut-aeson-generic`](https://pursuit.purescript.org/packages/purescript-argonaut-aeson-generic) ([GitHub](https://github.com/coot/purescript-argonaut-aeson-generic)) -It does not use [`purescript-argonaut-aeson-generic`](https://pursuit.purescript.org/packages/purescript-argonaut-aeson-generic) ([GitHub](https://github.com/coot/purescript-argonaut-aeson-generic)). +It does not use [`input-output-hk/purescript-bridge-json-helpers`](https://github.com/input-output-hk/purescript-bridge-json-helpers.git). +To demonstrate this library in the example, more work is needed in `Main.purs`. -The Haskell type `Foo`, in `src/Types.hs`, is generated for Purescript by Purescript Bridge. `purescript-bridge-json-helpers` is used to decode and encode this type, client-side. +The Haskell type `Foo`, in `src/Types.hs`, is generated for PureScript by PureScript Bridge. Some of values in `Foo` are randomly generated every time the page is loaded. `purescript-argonaut-aeson-generic` is used to decode and encode this payload, client-side. The client modifies some of the payload's values and sends it back to the server. # Dependencies ## Nix -The `nix develop` shell will provide Purescipt 0.15 and Spago. +The `nix develop` shell will provide PureScript 0.15 and Spago. ## Without Nix -You must install Purescript 0.15 and Spago. +You must install PureScript 0.15 and [spago-legacy](https://github.com/purescript/spago-legacy). # Running the example - Enter the `example` directory @@ -38,10 +39,10 @@ Foo message: Hello Foo number: 123 Foo list length: 11 Foo message: Hola Foo number: 124 Foo list length: 22 ``` -# Updating the Purescript Bridge +# Updating the PureScript Bridge - Enter the `example` directory -- Regenerate the Purescript Bridge types: +- Regenerate the PureScript Bridge types: ``` cabal run generate-purescript ``` diff --git a/example/src/Main.purs b/example/src/Main.purs index 642efc90..7d87f06f 100644 --- a/example/src/Main.purs +++ b/example/src/Main.purs @@ -34,7 +34,7 @@ testFoo = Foo } main :: Effect Unit -main = log "Hello, Purescript!" *> launchAff_ do +main = log "Hello, PureScript!" *> launchAff_ do -- request a Foo fooResponse <- get json "/foo" for_ fooResponse \fooPayload -> do diff --git a/example/src/Types.hs b/example/src/Types.hs index 263fb26c..beb92363 100644 --- a/example/src/Types.hs +++ b/example/src/Types.hs @@ -119,9 +119,8 @@ myBridge = defaultBridge additionalInstances = lenses . genericShow . argonautAesonGeneric - - -- . jsonHelper - -- To use json-helpers with the example, a modification is necessary + -- . jsonHelpers + -- To use json-helpers with the example, more work is needed -- in Main.purs myTypes :: [SumType 'Haskell] diff --git a/example/static/index.html b/example/static/index.html index 9cc032cf..68fe7ba7 100644 --- a/example/static/index.html +++ b/example/static/index.html @@ -1,7 +1,7 @@ - Purescript Bridge Example + PureScript Bridge Example