diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,32 @@ +Version 1.0.1 +--------------- +* Fixed the doctests + +Version 1.0 +--------------- +* Swapped distributeWith with cotraverse +* Documentation improvements + +Version 0.2.1.1 +--------------- +* Corrected the README + +Version 0.2.1 +--------------- +* Incremented the dependency bounds for GHC 8.2.1 + +Version 0.2 +--------------- +* Introduced `DistributiveTraversable` as a generalization of `Distributive` +* Export "cotraverse" and "cotraverseTraversable" +* Added `liftA3`, `liftA4`, `liftA5` +* Added more convienence functions +* Fixed grammatical errors and overlong lines + +Version 0.1.1 +--------------- +* Generalized the classes with `{-# LANGUAGE PolyKinds" #-}` + +Version 0.1 +--------------- +* Initial release diff --git a/rank2classes.cabal b/rank2classes.cabal --- a/rank2classes.cabal +++ b/rank2classes.cabal @@ -1,5 +1,5 @@ name: rank2classes -version: 1.0 +version: 1.0.1 synopsis: standard type constructor class hierarchy, only with methods of rank 2 types description: A mirror image of the standard type constructor class hierarchy rooted in 'Functor', except with methods of rank 2 @@ -17,7 +17,7 @@ build-type: Simple -- extra-source-files: cabal-version: >=1.10 -extra-source-files: README.md +extra-source-files: README.md, CHANGELOG.md, test/README.lhs source-repository head type: git location: https://github.com/blamario/grampa diff --git a/test/README.lhs b/test/README.lhs new file mode 100644 --- /dev/null +++ b/test/README.lhs @@ -0,0 +1,210 @@ +Rank 2 Classes +============== + +### The standard constructor type classes in the parallel rank-2 universe ### + +The rank2 package exports module `Rank2`, meant to be imported qualified like this: + +~~~ {.haskell} +{-# LANGUAGE RankNTypes, TemplateHaskell #-} +module MyModule where +import qualified Rank2 +import qualified Rank2.TH +~~~ + +Several more imports for the examples... + +~~~ {.haskell} +import Data.Functor.Classes (Show1, showsPrec1) +import Data.Functor.Identity (Identity(..)) +import Data.Functor.Const (Const(..)) +import Data.List (find) +~~~ + +The `Rank2` import will make available the following type classes: + * [Rank2.Functor](http://hackage.haskell.org/packages/rank2/doc/html/Rank2.html#t:Functor) + * [Rank2.Apply](http://hackage.haskell.org/packages/rank2/doc/html/Rank2.html#t:Apply) + * [Rank2.Applicative](http://hackage.haskell.org/packages/rank2/doc/html/Rank2.html#t:Applicative) + * [Rank2.Foldable](http://hackage.haskell.org/packages/archive/doc/html/Rank2.html#t:Foldable) + * [Rank2.Traversable](http://hackage.haskell.org/packages/archive/doc/html/Rank2.html#t:Traversable) + * [Rank2.Distributive](http://hackage.haskell.org/packages/archive/doc/html/Rank2.html#t:Distributive) + +The methods of these type classes all have rank-2 types. The class instances are data types of kind `(k -> *) -> *`, +one example of which would be a database record with different field types but all wrapped by the same type +constructor: + +~~~ {.haskell} +data Person f = Person{ + name :: f String, + age :: f Int, + mother, father :: f (Maybe PersonVerified) + } +~~~ + +By wrapping each field we have declared a generalized record type. It can made to play different roles by switching the +value of the parameter `f`. Some examples would be + +~~~ {.haskell} +type PersonVerified = Person Identity +type PersonText = Person (Const String) +type PersonWithErrors = Person (Either String) +type PersonDatabase = [PersonVerified] +type PersonDatabaseByColumns = Person [] +~~~ + +If you wish to have the standard [Eq](http://hackage.haskell.org/package/base/docs/Data-Eq.html#t:Eq) and +[Show](http://hackage.haskell.org/package/base/docs/Text-Show.html#t:Show) instances for a record type like `Person`, +it's best if they refer to the +[Eq1](http://hackage.haskell.org/package/base-4.9.1.0/docs/Data-Functor-Classes.html#t:Eq1) and +[Show1](http://hackage.haskell.org/package/base-4.9.1.0/docs/Data-Functor-Classes.html#t:Show1) instances for its +parameter `f`: + +~~~ {.haskell} +instance Show1 f => Show (Person f) where + showsPrec prec person rest = + "Person{" ++ separator ++ "name=" ++ showsPrec1 prec' (name person) + ("," ++ separator ++ "age=" ++ showsPrec1 prec' (age person) + ("," ++ separator ++ "mother=" ++ showsPrec1 prec' (mother person) + ("," ++ separator ++ "father=" ++ showsPrec1 prec' (father person) + ("}" ++ rest)))) + where prec' = succ prec + separator = "\n" ++ replicate prec' ' ' +~~~ + +You can create the rank-2 class instances for your data types manually, or you can generate the instances using the +templates imported from the `Rank2.TH` module with a single line of code per data type: + +~~~ {.haskell} +$(Rank2.TH.deriveAll ''Person) +~~~ + +Either way, once you have the rank-2 type class instances, you can use them to easily convert between records with +different parameters `f`. + +### Record construction and modification examples ### + +In case of our `Person` record, a couple of helper functions will prove handy: + +~~~ {.haskell} +findPerson :: PersonDatabase -> String -> Maybe PersonVerified +findPerson db nameToFind = find ((nameToFind ==) . runIdentity . name) db + +personByName :: PersonDatabase -> String -> Either String (Maybe PersonVerified) +personByName db personName + | null personName = Right Nothing + | p@Just{} <- findPerson db personName = Right p + | otherwise = Left ("Nobody by name of " ++ personName) +~~~ + +Now we can start by constructing a `Person` record with rank-2 functions for fields. This record is not so much a person +as a field-by-field person verifier: + +~~~ {.haskell} +personChecker :: PersonDatabase -> Person (Rank2.Arrow (Const String) (Either String)) +personChecker db = + Person{name= Rank2.Arrow (Right . getConst), + age= Rank2.Arrow $ \(Const age)-> + case reads age + of [(n, "")] -> Right n + _ -> Left (age ++ " is not an integer"), + mother= Rank2.Arrow (personByName db . getConst), + father= Rank2.Arrow (personByName db . getConst)} +~~~ + +We can apply it using the [Rank2.<*>](http://hackage.haskell.org/packages/rank2/doc/html/Rank2.html#v:-60--42--62-) +method of the [Rank2.Apply](http://hackage.haskell.org/packages/rank2/doc/html/Rank2.html#t:Apply) type class to a bunch +of textual fields for `Person`, and get back either errors or proper field values: + +~~~ {.haskell} +verify :: PersonDatabase -> PersonText -> PersonWithErrors +verify db person = personChecker db Rank2.<*> person +~~~ + +If there are no errors, we can get a fully verified record by applying +[Rank2.traverse](http://hackage.haskell.org/packages/rank2/doc/html/Rank2.html#v:traverse) to the result: + +~~~ {.haskell} +completeVerified :: PersonWithErrors -> Either String PersonVerified +completeVerified = Rank2.traverse (Identity <$>) +~~~ + +or we can go in the opposite direction with +[Rank2.<$>](http://hackage.haskell.org/packages/rank2/doc/html/Rank2.html#v:-60--36--62-): + +~~~ {.haskell} +uncompleteVerified :: PersonVerified -> PersonWithErrors +uncompleteVerified = Rank2.fmap (Right . runIdentity) +~~~ + +If on the other hand there *are* errors, we can collect them using +[Rank2.foldMap](http://hackage.haskell.org/packages/rank2/doc/html#v:foldMap): + +~~~ {.haskell} +verificationErrors :: PersonWithErrors -> [String] +verificationErrors = Rank2.foldMap (either (:[]) (const [])) +~~~ + +Here is an example GHCi session: + +~~~ {.haskell} +-- | +-- >>> :{ +--let Right alice = completeVerified $ +-- verify [] Person{name= Const "Alice", age= Const "44", +-- mother= Const "", father= Const ""} +-- Right bob = completeVerified $ +-- verify [] Person{name= Const "Bob", age= Const "45", +-- mother= Const "", father= Const ""} +-- Right charlie = completeVerified $ +-- verify [alice, bob] Person{name= Const "Charlie", age= Const "19", +-- mother= Const "Alice", father= Const "Bob"} +-- :} +-- +-- >>> charlie +-- Person{ +-- name=Identity "Charlie", +-- age=Identity 19, +-- mother=Identity (Just Person{ +-- name=(Identity "Alice"), +-- age=(Identity 44), +-- mother=(Identity Nothing), +-- father=(Identity Nothing)}), +-- father=Identity (Just Person{ +-- name=(Identity "Bob"), +-- age=(Identity 45), +-- mother=(Identity Nothing), +-- father=(Identity Nothing)})} +-- >>> :{ +--let dave = verify [alice, bob, charlie] +-- Person{name= Const "Dave", age= Const "young", +-- mother= Const "Lise", father= Const "Mike"} +-- :} +-- +-- >>> dave +-- Person{ +-- name=Right "Dave", +-- age=Left "young is not an integer", +-- mother=Left "Nobody by name of Lise", +-- father=Left "Nobody by name of Mike"} +-- >>> completeVerified dave +-- Left "young is not an integer" +-- >>> verificationErrors dave +-- ["young is not an integer","Nobody by name of Lise","Nobody by name of Mike"] +-- >>> Rank2.distribute [alice, bob, charlie] +-- Person{ +-- name=Compose [Identity "Alice",Identity "Bob",Identity "Charlie"], +-- age=Compose [Identity 44,Identity 45,Identity 19], +-- mother=Compose [Identity Nothing,Identity Nothing,Identity (Just Person{ +-- name=(Identity "Alice"), +-- age=(Identity 44), +-- mother=(Identity Nothing), +-- father=(Identity Nothing)})], +-- father=Compose [Identity Nothing,Identity Nothing,Identity (Just Person{ +-- name=(Identity "Bob"), +-- age=(Identity 45), +-- mother=(Identity Nothing), +-- father=(Identity Nothing)})]} +~~~ + +Grammars are another use case that is almost, but not quite, completely unlike database records. See +[grammatical-parsers](https://github.com/blamario/grampa/tree/master/grammatical-parsers) about that.