-- | All of the functions below work only on «interesting» subterms.
-- It is up to the instance writer to decide which subterms are
-- interesting and which subterms should count as immediate. This can
-- also depend on the context @c@.
--
-- The context, denoted @c@, is a constraint (of kind @* -> Constraint@)
-- that provides additional facilities to work with the data.
-- In most cases, the context cannot be inferred automatically.
-- You need to provide it using the
-- <https://downloads.haskell.org/~ghc/8.0.2/docs/html/users_guide/glasgow_exts.html#visible-type-application type application syntax>:
--
-- > gmap @Show f x
-- > everywhere @Typeable f x
--
-- etc.
--
-- For more information, see:
--
-- [Scrap your boilerplate with class]
-- <https://www.microsoft.com/en-us/research/publication/scrap-your-boilerplate-with-class/>
--
-- [Generalizing generic fold]
-- <http://ro-che.info/articles/2013-03-11-generalizing-gfoldl>

module Data.Generics.Traversable
  (
    -- * Open recursion combinators

    GTraversable(..)
  , gmap
  , gmapM
  , gfoldMap
  , gfoldr
  , gfoldl'

    -- * Closed recursion combinators
  , Rec
  , everywhere
  , everywhere'
  , everywhereM
  , everything
  )
  where

import GHC.Exts (Constraint)

import Control.Applicative
import Control.Monad
import Data.Monoid
import Data.Functor.Identity
import Data.Functor.Constant

import Data.Generics.Traversable.Core
import Data.Generics.Traversable.Instances ()

-- | 'Rec' enables \"deep traversals\".
--
-- It is satisfied automatically when its superclass constraints are
-- satisfied — you are not supposed to declare new instances of this class.
class    (GTraversable (Rec c) a, c a) => Rec (c :: * -> Constraint) a
instance (GTraversable (Rec c) a, c a) => Rec (c :: * -> Constraint) a

-- | Generic map over the immediate subterms
gmap
  :: forall c a . (GTraversable c a)
  => (forall d . (c d) => d -> d)
  -> a -> a
gmap :: (forall d. c d => d -> d) -> a -> a
gmap forall d. c d => d -> d
f a
a = Identity a -> a
forall a. Identity a -> a
runIdentity ((forall d. c d => d -> Identity d) -> a -> Identity a
forall (c :: * -> Constraint) a (f :: * -> *).
(GTraversable c a, Applicative f) =>
(forall d. c d => d -> f d) -> a -> f a
gtraverse @c (d -> Identity d
forall a. a -> Identity a
Identity (d -> Identity d) -> (d -> d) -> d -> Identity d
forall b c a. (b -> c) -> (a -> b) -> a -> c
. d -> d
forall d. c d => d -> d
f) a
a)

-- | Generic monadic map over the immediate subterms
gmapM
  :: forall c m a . (Monad m, GTraversable c a)
  => (forall d . (c d) => d -> m d)
  -> a -> m a
gmapM :: (forall d. c d => d -> m d) -> a -> m a
gmapM forall d. c d => d -> m d
f = WrappedMonad m a -> m a
forall (m :: * -> *) a. WrappedMonad m a -> m a
unwrapMonad (WrappedMonad m a -> m a) -> (a -> WrappedMonad m a) -> a -> m a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (forall d. c d => d -> WrappedMonad m d) -> a -> WrappedMonad m a
forall (c :: * -> Constraint) a (f :: * -> *).
(GTraversable c a, Applicative f) =>
(forall d. c d => d -> f d) -> a -> f a
gtraverse @c (m d -> WrappedMonad m d
forall (m :: * -> *) a. m a -> WrappedMonad m a
WrapMonad (m d -> WrappedMonad m d) -> (d -> m d) -> d -> WrappedMonad m d
forall b c a. (b -> c) -> (a -> b) -> a -> c
. d -> m d
forall d. c d => d -> m d
f)

-- | Generic monoidal fold over the immediate subterms (cf. 'Data.Foldable.foldMap')
gfoldMap
  :: forall c r a . (Monoid r, GTraversable c a)
  => (forall d . (c d) => d -> r)
  -> a -> r
gfoldMap :: (forall d. c d => d -> r) -> a -> r
gfoldMap forall d. c d => d -> r
f = Constant r a -> r
forall a k (b :: k). Constant a b -> a
getConstant (Constant r a -> r) -> (a -> Constant r a) -> a -> r
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (forall d. c d => d -> Constant r d) -> a -> Constant r a
forall (c :: * -> Constraint) a (f :: * -> *).
(GTraversable c a, Applicative f) =>
(forall d. c d => d -> f d) -> a -> f a
gtraverse @c (r -> Constant r d
forall k a (b :: k). a -> Constant a b
Constant (r -> Constant r d) -> (d -> r) -> d -> Constant r d
forall b c a. (b -> c) -> (a -> b) -> a -> c
. d -> r
forall d. c d => d -> r
f)

-- | Generic right fold over the immediate subterms
gfoldr
  :: forall c a r . (GTraversable c a)
  => (forall d . (c d) => d -> r -> r)
  -> r -> a -> r
gfoldr :: (forall d. c d => d -> r -> r) -> r -> a -> r
gfoldr forall d. c d => d -> r -> r
f r
z a
t = Endo r -> r -> r
forall a. Endo a -> a -> a
appEndo ((forall d. c d => d -> Endo r) -> a -> Endo r
forall (c :: * -> Constraint) r a.
(Monoid r, GTraversable c a) =>
(forall d. c d => d -> r) -> a -> r
gfoldMap @c ((r -> r) -> Endo r
forall a. (a -> a) -> Endo a
Endo ((r -> r) -> Endo r) -> (d -> r -> r) -> d -> Endo r
forall b c a. (b -> c) -> (a -> b) -> a -> c
. d -> r -> r
forall d. c d => d -> r -> r
f) a
t) r
z

-- | Generic strict left fold over the immediate subterms
gfoldl'
  :: forall c a r . (GTraversable c a)
  => (forall d . (c d) => r -> d -> r)
  -> r -> a -> r
gfoldl' :: (forall d. c d => r -> d -> r) -> r -> a -> r
gfoldl' forall d. c d => r -> d -> r
f r
z0 a
xs = (forall d. c d => d -> (r -> r) -> r -> r)
-> (r -> r) -> a -> r -> r
forall (c :: * -> Constraint) a r.
GTraversable c a =>
(forall d. c d => d -> r -> r) -> r -> a -> r
gfoldr @c forall d. c d => d -> (r -> r) -> r -> r
forall d b. c d => d -> (r -> b) -> r -> b
f' r -> r
forall a. a -> a
id a
xs r
z0
  where f' :: d -> (r -> b) -> r -> b
f' d
x r -> b
k r
z = r -> b
k (r -> b) -> r -> b
forall a b. (a -> b) -> a -> b
$! r -> d -> r
forall d. c d => r -> d -> r
f r
z d
x

-- | Apply a transformation everywhere in bottom-up manner
everywhere
  :: forall c a .
     (Rec c a)
  => (forall d. (Rec c d) => d -> d)
  -> a -> a
everywhere :: (forall d. Rec c d => d -> d) -> a -> a
everywhere forall d. Rec c d => d -> d
f =
  let
    go :: forall b . Rec c b => b -> b
    go :: b -> b
go = b -> b
forall d. Rec c d => d -> d
f (b -> b) -> (b -> b) -> b -> b
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (forall d. Rec c d => d -> d) -> b -> b
forall (c :: * -> Constraint) a.
GTraversable c a =>
(forall d. c d => d -> d) -> a -> a
gmap @(Rec c) forall d. Rec c d => d -> d
go
  in a -> a
forall d. Rec c d => d -> d
go

-- | Apply a transformation everywhere in top-down manner
everywhere'
  :: forall c a .
     (Rec c a)
  => (forall d. (Rec c d) => d -> d)
  -> a -> a
everywhere' :: (forall d. Rec c d => d -> d) -> a -> a
everywhere' forall d. Rec c d => d -> d
f =
  let
    go :: forall b . Rec c b => b -> b
    go :: b -> b
go = (forall d. Rec c d => d -> d) -> b -> b
forall (c :: * -> Constraint) a.
GTraversable c a =>
(forall d. c d => d -> d) -> a -> a
gmap @(Rec c) forall d. Rec c d => d -> d
go (b -> b) -> (b -> b) -> b -> b
forall b c a. (b -> c) -> (a -> b) -> a -> c
. b -> b
forall d. Rec c d => d -> d
f
  in a -> a
forall d. Rec c d => d -> d
go

-- | Monadic variation on everywhere
everywhereM
  :: forall c m a .
     (Monad m, Rec c a)
  => (forall d. (Rec c d) => d -> m d)
  -> a -> m a
everywhereM :: (forall d. Rec c d => d -> m d) -> a -> m a
everywhereM forall d. Rec c d => d -> m d
f =
  let
    go :: forall b . Rec c b => b -> m b
    go :: b -> m b
go = b -> m b
forall d. Rec c d => d -> m d
f (b -> m b) -> (b -> m b) -> b -> m b
forall (m :: * -> *) b c a.
Monad m =>
(b -> m c) -> (a -> m b) -> a -> m c
<=< (forall d. Rec c d => d -> m d) -> b -> m b
forall (c :: * -> Constraint) (m :: * -> *) a.
(Monad m, GTraversable c a) =>
(forall d. c d => d -> m d) -> a -> m a
gmapM @(Rec c) forall d. Rec c d => d -> m d
go
  in a -> m a
forall d. Rec c d => d -> m d
go

-- | Strict left fold over all elements, top-down
everything
  :: forall c r a .
     (Rec c a)
  => (r -> r -> r)
  -> (forall d . (Rec c d) => d -> r)
  -> a -> r
everything :: (r -> r -> r) -> (forall d. Rec c d => d -> r) -> a -> r
everything r -> r -> r
combine forall d. Rec c d => d -> r
f =
  let
    go :: forall b . Rec c b => b -> r
    go :: b -> r
go b
x = (forall d. Rec c d => r -> d -> r) -> r -> b -> r
forall (c :: * -> Constraint) a r.
GTraversable c a =>
(forall d. c d => r -> d -> r) -> r -> a -> r
gfoldl' @(Rec c) (\r
a d
y -> r -> r -> r
combine r
a (d -> r
forall d. Rec c d => d -> r
go d
y)) (b -> r
forall d. Rec c d => d -> r
f b
x) b
x
  in a -> r
forall d. Rec c d => d -> r
go