Merge pull request #47 from reflex-frp/fix-docs-and-improve-patch-or-replacement

Fix docs, also replace odd-end `PatchOrReplacement` function with prisms

Author: Ericson2314

src/Data/Functor/Misc.hs

@@ -61,8 +61,9 @@ import Data.Typeable hiding (Refl)
 -- Const2
 --------------------------------------------------------------------------------
 
--- | 'Const2' stores a value of a given type 'k' and ensures that a particular
--- type 'v' is always given for the last type parameter
+-- | @'Const2' k v v@ stores a value of a given type @k@ and ensures
+-- that a particular type @v@ is always given for the last type
+-- parameter
 data Const2 :: Type -> x -> x -> Type where
   Const2 :: k -> Const2 k v v
   deriving (Typeable)
@@ -227,9 +228,10 @@ dsumToEither = \case
 -- ComposeMaybe
 --------------------------------------------------------------------------------
 
--- | We can't use @Compose Maybe@ instead of 'ComposeMaybe', because that would
--- make the 'f' parameter have a nominal type role.  We need f to be
--- representational so that we can use safe 'coerce'.
+-- | We can't use @'Data.Functor.Compose.Compose' 'Maybe'@ instead of @'ComposeMaybe'@,
+-- because that would make the @f@ parameter have a nominal type role.
+-- We need @f@ to be representational so that we can use safe
+-- @'Data.Coerce.coerce'@.
 newtype ComposeMaybe f a =
   ComposeMaybe { getComposeMaybe :: Maybe (f a) } deriving (Show, Eq, Ord)
 

src/Data/Patch/MapWithMove.hs

@@ -111,8 +111,8 @@ pattern Coerce x <- (coerce -> x)
 
 {-# COMPLETE PatchMapWithMove #-}
 pattern PatchMapWithMove :: Map k (NodeInfo k v) -> PatchMapWithMove k v
--- | Extract the representation of the 'PatchMapWithMove' as a map of
--- 'NodeInfo'.
+-- | Extract the representation of the t'PatchMapWithMove' as a map of
+-- t'NodeInfo'.
 unPatchMapWithMove :: PatchMapWithMove k v -> Map k (NodeInfo k v)
 pattern PatchMapWithMove { unPatchMapWithMove } = PatchMapWithMove' (PatchMapWithPatchingMove (Coerce unPatchMapWithMove))
 
@@ -147,27 +147,27 @@ instance L.FoldableWithIndex k   (PatchMapWithMove k) where ifoldMap = Data.Fold
 instance L.TraversableWithIndex k (PatchMapWithMove k) where itraverse = Data.Traversable.WithIndex.itraverse
 #endif
 
--- | Create a 'PatchMapWithMove', validating it
+-- | Create a t'PatchMapWithMove', validating it
 patchMapWithMove :: Ord k => Map k (NodeInfo k v) -> Maybe (PatchMapWithMove k v)
 patchMapWithMove = fmap PatchMapWithMove' . PM.patchMapWithPatchingMove . coerce
 
--- | Create a 'PatchMapWithMove' that inserts everything in the given 'Map'
+-- | Create a t'PatchMapWithMove' that inserts everything in the given 'Map'
 patchMapWithMoveInsertAll :: Map k v -> PatchMapWithMove k v
 patchMapWithMoveInsertAll = PatchMapWithMove' . PM.patchMapWithPatchingMoveInsertAll
 
--- | Make a @'PatchMapWithMove' k v@ which has the effect of inserting or updating a value @v@ to the given key @k@, like 'Map.insert'.
+-- | Make a @t'PatchMapWithMove' k v@ which has the effect of inserting or updating a value @v@ to the given key @k@, like 'Map.insert'.
 insertMapKey :: k -> v -> PatchMapWithMove k v
 insertMapKey k v = PatchMapWithMove' $ PM.insertMapKey k v
 
--- |Make a @'PatchMapWithMove' k v@ which has the effect of moving the value from the first key @k@ to the second key @k@, equivalent to:
+-- |Make a @t'PatchMapWithMove' k v@ which has the effect of moving the value from the first key @k@ to the second key @k@, equivalent to:
 --
 -- @
 --     'Map.delete' src (maybe map ('Map.insert' dst) (Map.lookup src map))
 -- @
 moveMapKey :: Ord k => k -> k -> PatchMapWithMove k v
 moveMapKey src dst = PatchMapWithMove' $ PM.moveMapKey src dst
 
--- |Make a @'PatchMapWithMove' k v@ which has the effect of swapping two keys in the mapping, equivalent to:
+-- |Make a @t'PatchMapWithMove' k v@ which has the effect of swapping two keys in the mapping, equivalent to:
 --
 -- @
 --     let aMay = Map.lookup a map
@@ -179,13 +179,13 @@ moveMapKey src dst = PatchMapWithMove' $ PM.moveMapKey src dst
 swapMapKey :: Ord k => k -> k -> PatchMapWithMove k v
 swapMapKey src dst = PatchMapWithMove' $ PM.swapMapKey src dst
 
--- |Make a @'PatchMapWithMove' k v@ which has the effect of deleting a key in the mapping, equivalent to 'Map.delete'.
+-- |Make a @t'PatchMapWithMove' k v@ which has the effect of deleting a key in the mapping, equivalent to 'Map.delete'.
 deleteMapKey :: k -> PatchMapWithMove k v
 deleteMapKey = PatchMapWithMove' . PM.deleteMapKey
 
--- | Wrap a @'Map' k (NodeInfo k v)@ representing patch changes into a @'PatchMapWithMove' k v@, without checking any invariants.
+-- | Wrap a @'Map' k (NodeInfo k v)@ representing patch changes into a @t'PatchMapWithMove' k v@, without checking any invariants.
 --
--- __Warning:__ when using this function, you must ensure that the invariants of 'PatchMapWithMove' are preserved; they will not be checked.
+-- __Warning:__ when using this function, you must ensure that the invariants of t'PatchMapWithMove' are preserved; they will not be checked.
 unsafePatchMapWithMove :: Map k (NodeInfo k v) -> PatchMapWithMove k v
 unsafePatchMapWithMove = coerce PM.unsafePatchMapWithPatchingMove
 
@@ -198,25 +198,25 @@ instance Ord k => Patch (PatchMapWithMove k v) where
 patchMapWithMoveNewElements :: PatchMapWithMove k v -> [v]
 patchMapWithMoveNewElements = PM.patchMapWithPatchingMoveNewElements . unPatchMapWithMove'
 
--- | Return a @'Map' k v@ with all the inserts/updates from the given @'PatchMapWithMove' k v@.
+-- | Return a @'Map' k v@ with all the inserts/updates from the given @t'PatchMapWithMove' k v@.
 patchMapWithMoveNewElementsMap :: PatchMapWithMove k v -> Map k v
 patchMapWithMoveNewElementsMap = PM.patchMapWithPatchingMoveNewElementsMap . unPatchMapWithMove'
 
--- | Create a 'PatchMapWithMove' that, if applied to the given 'Map', will sort
+-- | Create a t'PatchMapWithMove' that, if applied to the given 'Map', will sort
 -- its values using the given ordering function.  The set keys of the 'Map' is
 -- not changed.
 patchThatSortsMapWith :: Ord k => (v -> v -> Ordering) -> Map k v -> PatchMapWithMove k v
 patchThatSortsMapWith cmp = PatchMapWithMove' . PM.patchThatSortsMapWith cmp
 
--- | Create a 'PatchMapWithMove' that, if applied to the first 'Map' provided,
+-- | Create a t'PatchMapWithMove' that, if applied to the first 'Map' provided,
 -- will produce a 'Map' with the same values as the second 'Map' but with the
 -- values sorted with the given ordering function.
 patchThatChangesAndSortsMapWith :: (Ord k, Ord v) => (v -> v -> Ordering) -> Map k v -> Map k v -> PatchMapWithMove k v
 patchThatChangesAndSortsMapWith cmp oldByIndex newByIndexUnsorted = patchThatChangesMap oldByIndex newByIndex
   where newList = Map.toList newByIndexUnsorted
         newByIndex = Map.fromList $ zip (fst <$> newList) $ sortBy cmp $ snd <$> newList
 
--- | Create a 'PatchMapWithMove' that, if applied to the first 'Map' provided,
+-- | Create a t'PatchMapWithMove' that, if applied to the first 'Map' provided,
 -- will produce the second 'Map'.
 patchThatChangesMap :: (Ord k, Ord v) => Map k v -> Map k v -> PatchMapWithMove k v
 patchThatChangesMap oldByIndex newByIndex = PatchMapWithMove' $
@@ -262,6 +262,7 @@ instance Foldable (NodeInfo k) where
 instance Traversable (NodeInfo k) where
   traverse = bitraverseNodeInfo pure
 
+-- | Like 'Data.Bitraversable.bitraverse'
 bitraverseNodeInfo
   :: Applicative f
   => (k0 -> f k1)
@@ -271,11 +272,11 @@ bitraverseNodeInfo fk fv = fmap NodeInfo'
   . PM.bitraverseNodeInfo fk (\ ~Proxy -> pure Proxy) fv
   . coerce
 
--- | Change the 'From' value of a 'NodeInfo'
+-- | Change the 'From' value of a t'NodeInfo'
 nodeInfoMapFrom :: (From k v -> From k v) -> NodeInfo k v -> NodeInfo k v
 nodeInfoMapFrom f = coerce $ PM.nodeInfoMapFrom (unFrom' . f . From')
 
--- | Change the 'From' value of a 'NodeInfo', using a 'Functor' (or
+-- | Change the 'From' value of a t'NodeInfo', using a 'Functor' (or
 -- 'Applicative', 'Monad', etc.) action to get the new value
 nodeInfoMapMFrom
   :: Functor f
@@ -285,7 +286,7 @@ nodeInfoMapMFrom f = fmap NodeInfo'
   . PM.nodeInfoMapMFrom (fmap unFrom' . f . From')
   . coerce
 
--- | Set the 'To' field of a 'NodeInfo'
+-- | Set the 'To' field of a t'NodeInfo'
 nodeInfoSetTo :: To k -> NodeInfo k v -> NodeInfo k v
 nodeInfoSetTo = coerce . PM.nodeInfoSetTo
 
@@ -310,6 +311,7 @@ pattern From_Delete = From' PM.From_Delete
 pattern From_Move :: k -> From k v
 pattern From_Move k = From' (PM.From_Move k Proxy)
 
+-- | Like 'Data.Bitraversable.bitraverse'
 bitraverseFrom
   :: Applicative f
   => (k0 -> f k1)

src/Data/Patch/PatchOrReplacement.hs

@@ -4,11 +4,21 @@
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE StandaloneDeriving #-}
+{-# LANGUAGE TemplateHaskell #-}
 {-# LANGUAGE TypeFamilies #-}
 {-# LANGUAGE UndecidableInstances #-}
 
-module Data.Patch.PatchOrReplacement where
+{-|
+Description: A 'Patch' combinator type for patching or replacing with a separate new value.
+-}
+module Data.Patch.PatchOrReplacement
+  ( PatchOrReplacement (..)
+  , _PatchOrReplacement_Patch
+  , _PatchOrReplacement_Replacement
+  , traversePatchOrReplacement
+  ) where
 
+import Control.Lens.TH (makePrisms)
 import Data.Patch
 #if !MIN_VERSION_base(4,11,0)
 import Data.Semigroup (Semigroup (..))
@@ -34,13 +44,18 @@ deriving instance (Ord p, Ord (PatchTarget p)) => Ord (PatchOrReplacement p)
 deriving instance (Show p, Show (PatchTarget p)) => Show (PatchOrReplacement p)
 deriving instance (Read p, Read (PatchTarget p)) => Read (PatchOrReplacement p)
 
-completePatchOrReplacement :: PatchOrReplacement p -> Maybe (PatchTarget p)
-completePatchOrReplacement = \case
-  PatchOrReplacement_Replacement t -> Just t
-  PatchOrReplacement_Patch _ -> Nothing
+-- | Traverse a 'PatchOrReplacement' with a function for each case
+traversePatchOrReplacement
+  :: Functor f
+  => (a -> f b)
+  -> (PatchTarget a -> f (PatchTarget b))
+  -> PatchOrReplacement a -> f (PatchOrReplacement b)
+traversePatchOrReplacement f g = \case
+  PatchOrReplacement_Patch p -> PatchOrReplacement_Patch <$> f p
+  PatchOrReplacement_Replacement p -> PatchOrReplacement_Replacement <$> g p
 
--- | To apply a 'PatchOrReplacement p' apply the the underlying 'p' or
--- substitute the replacement 'PatchTarget p'.
+-- | To apply a @'PatchOrReplacement' p@ apply the the underlying @p@ or
+-- substitute the replacement @'PatchTarget' p@.
 instance Patch p => Patch (PatchOrReplacement p) where
   type PatchTarget (PatchOrReplacement p) = PatchTarget p
   apply = \case
@@ -61,3 +76,5 @@ instance (Semigroup p, Patch p) => Semigroup (PatchOrReplacement p) where
     (PatchOrReplacement_Patch a, PatchOrReplacement_Patch b) -> PatchOrReplacement_Patch $ a <> b
     (PatchOrReplacement_Patch a, PatchOrReplacement_Replacement b) -> PatchOrReplacement_Replacement $ applyAlways a b
     (PatchOrReplacement_Replacement a, _) -> PatchOrReplacement_Replacement a
+
+makePrisms ''PatchOrReplacement