diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +# 0.2.1 + +- Expand and correct documentations + +# 0.2 + +- Add new derivation syntax taken from "recursion-schemes" package + (see [Data.Functor.Foldable.TH](https://hackage.haskell.org/package/recursion-schemes-5.2.2.2/docs/Data-Functor-Foldable-TH.html)) + # 0.1.2.1 - Require cabal-version: 2.0 diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ -- Test case for using [], tuple, and another Bimatchable instance data BiG a b = BiG0 | BiG1 [a] [b] | BiG2 (Int, BiF a b) - deriving (Show, Eq) + deriving (Show, Eq, Functor) deriveInstances [d| deriving instance Bifunctor BiG diff --git a/matchable-th.cabal b/matchable-th.cabal --- a/matchable-th.cabal +++ b/matchable-th.cabal @@ -1,5 +1,5 @@ name: matchable-th -version: 0.2 +version: 0.2.1 synopsis: Generates Matchable instances using TemplateHaskell description: This package provides TemplateHaskell function to generate instances of @Matchable@ and @Bimatchable@ type classes, @@ -13,7 +13,7 @@ extra-source-files: README.md extra-doc-files: CHANGELOG.md cabal-version: 2.0 -tested-with: GHC ==9.0.2, GHC ==9.2.7, GHC ==9.4.4, GHC ==9.6.1 +tested-with: GHC ==9.2.8, GHC ==9.4.8, GHC ==9.6.6, GHC ==9.8.2, GHC ==9.10.1 source-repository head type: git @@ -27,7 +27,7 @@ build-depends: base >= 4.10 && <5, matchable >= 0.1.2, bifunctors >= 5.1, - template-haskell >= 2.4 && < 2.21, + template-haskell >= 2.4 && < 2.24, th-abstraction >= 0.4.0.0 ghc-options: -Wall default-language: Haskell2010 diff --git a/src/Data/Matchable/TH.hs b/src/Data/Matchable/TH.hs --- a/src/Data/Matchable/TH.hs +++ b/src/Data/Matchable/TH.hs @@ -4,12 +4,15 @@ {-# LANGUAGE ViewPatterns #-} {-# LANGUAGE DeriveFunctor #-} module Data.Matchable.TH ( + -- * @derive@ functions deriveInstances, - - deriveMatchable, makeZipMatchWith, - deriveBimatchable, makeBizipMatchWith, + deriveMatchable, deriveBimatchable, - makeLiftEq, makeLiftEq2 + -- * @make-@ functions + makeZipMatchWith, + makeBizipMatchWith, + makeLiftEq, + makeLiftEq2, ) where import Data.Bifunctor (Bifunctor (..)) @@ -45,9 +48,23 @@ _ -> do reportError ("Instance declaration must be of shape Cls (TyCon ty1 ty2 ...), but it's" ++ show ty) pure [] --- | This function transforms multiple instance declarations written in @StandaloneDeriving@ --- format to instances derived by TemplateHaskell. +-- | Derive multiple instances of 'Matchable', 'Bimatchable', or their superclasses, +-- each written in @StandaloneDeriving@ syntax. -- +-- Passing declarations other than standalone deriving instances is an error. +-- Also, passing any instances other than 'Matchable', 'Bimatchable' or their superclasses is an error. +-- Explicitly, it accepts standalone deriving declarations of the following types: +-- +-- - 'Eq1' +-- - 'Eq2' +-- - 'Bifunctor' +-- - 'Matchable' +-- - 'Bimatchable' +-- +-- Passing an 'Eq' or 'Functor' instance declarations does not cause a compilation error +-- and generates the same standalone deriving declaration passed in, but also causes +-- a /warning/ telling you that you can use stock deriving for them. +-- -- ==== Example -- -- @ @@ -93,11 +110,11 @@ bifunctorDeriver, eq1Deriver, matchableDeriver, eq2Deriver, bimatchableDeriver :: Deriver bifunctorDeriver = Deriver ''Bifunctor [ ('bimap, makeBimap) ] eq1Deriver = Deriver ''Eq1 [ ('liftEq, makeLiftEq) ] - eq2Deriver = Deriver ''Eq2 [ ('liftEq2, makeLiftEq2 ) ] matchableDeriver = Deriver ''Matchable [ ('zipMatchWith, makeZipMatchWith) ] bimatchableDeriver = Deriver ''Bimatchable [ ('bizipMatchWith, makeBizipMatchWith) ] +-- | Generates an expression which behaves like 'liftEq' for the given data type. makeLiftEq :: Name -> Q Exp makeLiftEq name = do DatatypeInfo { datatypeVars = dtVarsNames , datatypeCons = cons } @@ -143,6 +160,7 @@ pure $ combineMatchers tupP andBoolExprs matchers _ -> unexpectedType ty "Eq1" +-- | Generates an expression which behaves like 'liftEq2' for the given data type. makeLiftEq2 :: Name -> Q Exp makeLiftEq2 name = do DatatypeInfo { datatypeVars = dtVarsNames , datatypeCons = cons } @@ -193,14 +211,20 @@ -- | Build an instance of 'Matchable' for a data type. -- --- /e.g./ +-- Note that 'deriveMatchable' generates the 'Matchable' instance only. Because 'Matchable' +-- requires 'Functor' and 'Eq1' (and 'Eq' transitively) as its superclasses, to actually use the generated instance, +-- it's necessary to provide them too. -- +-- Use 'deriveInstances' to generate both @Matchable@ and @Eq1@ instances at once. +-- +-- ==== Example +-- -- @ -- data Exp a = Plus a a | Times a a -- 'deriveMatchable' ''Exp -- @ -- --- will create +-- will generate the following instance. -- -- @ -- instance Matchable Exp where @@ -217,6 +241,7 @@ pure [dec] +-- | Generates an expression which behaves like 'zipMatchWith' for the given data type. makeZipMatchWith :: Name -> ExpQ makeZipMatchWith name = do (_, clauses) <- makeZipMatchWith' name @@ -282,17 +307,23 @@ -- | Build an instance of 'Bimatchable' for a data type. -- --- /e.g./ +-- Note that 'deriveBimatchable' generates the 'Bimatchable' instance only. Because 'Bimatchable' +-- requires 'Bifunctor' and 'Eq2' (and 'Functor', 'Eq', 'Eq1' transitively) as its superclasses, +-- to actually use the generated instance, it's necessary to provide them too. -- +-- Use 'deriveInstances' to generate all of these instances at once. +-- +-- ==== Example +-- -- @ -- data Sum a b = InL a | InR b --- 'deriveMatchable' ''Sum +-- 'deriveBimatchable' ''Sum -- @ -- -- will create -- -- @ --- instance Matchable Sum where +-- instance Bimatchable Sum where -- bizipMatchWith f _ (InL l1) (InL r1) = pure InL <$> f l1 r1 -- bizipMatchWith _ g (InR l1) (InR r1) = pure InR <$> g l1 r1 -- @ @@ -305,6 +336,7 @@ pure [dec] +-- | Generates an expression which behaves like 'bizipMatchWith' for the given data type. makeBizipMatchWith :: Name -> ExpQ makeBizipMatchWith name = do (_, clauses) <- makeBizipMatchWith' name