{-|
Module      : Witherable.Lens
Description : Tools for using the Witherable interface with lens
Copyright   : (c) Carl Howells, 2021-2022
License     : MIT
Maintainer  : chowells79@gmail.com

-}
module Witherable.Lens where


import Data.Functor.Identity (Identity(runIdentity))

import Witherable (Witherable(wither))

import Witherable.Lens.Withering


-- | A variant on 'traverse' that allows the targets to be filtered
-- out of the 'Witherable' structure. Note that this introduces a
-- change in types down the lens composition chain, which means that
-- it is not a a valid optic at all.  The use of 'Withering' in the
-- changed type also means that standard lens combinators don't fit
--
-- To address these issues, you can use 'unwithered' to strip the
-- 'Withering' type back out. This allows the composed optic to be
-- used with standard combinators from lens. In addition, the sequence
-- @'withered' . 'unwithered'@ will act like a type-restricted version
-- of 'traverse' for all lawful instances of 'Witherable'.
--
-- In some sense, this is a @catch@-like combinator. This marks the
-- point where removing elements stops propagating and actually
-- modifies the structure being focused.
withered
    :: (Applicative f, Witherable t)
    => (a -> Withering f b) -> t a -> f (t b)
withered :: forall (f :: * -> *) (t :: * -> *) a b.
(Applicative f, Witherable t) =>
(a -> Withering f b) -> t a -> f (t b)
withered a -> Withering f b
f = forall (t :: * -> *) (f :: * -> *) a b.
(Witherable t, Applicative f) =>
(a -> f (Maybe b)) -> t a -> f (t b)
wither (forall (f :: * -> *) a. Withering f a -> f (Maybe a)
runWithering forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> Withering f b
f)

-- | Restore types in a lens composition chain that has had
-- 'Withering' introduced. Makes no changes to what elements are
-- focused on.
unwithered :: Functor f => (a -> f b) -> a -> Withering f b
unwithered :: forall (f :: * -> *) a b.
Functor f =>
(a -> f b) -> a -> Withering f b
unwithered a -> f b
f a
s = forall (f :: * -> *) a. f (Maybe a) -> Withering f a
Withering (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a. a -> Maybe a
Just (a -> f b
f a
s))

-- | A variant of withered for when you're already working in a
-- Withering chain and want to change what structure elements are
-- being removed from.
--
-- @'rewithered' = 'unwithered' . 'withered'@
rewithered
    :: (Applicative f, Witherable t)
    => (a -> Withering f b) -> t a -> Withering f (t b)
rewithered :: forall (f :: * -> *) (t :: * -> *) a b.
(Applicative f, Witherable t) =>
(a -> Withering f b) -> t a -> Withering f (t b)
rewithered = forall (f :: * -> *) a b.
Functor f =>
(a -> f b) -> a -> Withering f b
unwithered forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (f :: * -> *) (t :: * -> *) a b.
(Applicative f, Witherable t) =>
(a -> Withering f b) -> t a -> f (t b)
withered

-- | The trivial optic in a Withering chain that removes everything.
--
-- The arguments are unused.
decayed :: Applicative f => pafb -> s -> Withering f t
decayed :: forall (f :: * -> *) pafb s t.
Applicative f =>
pafb -> s -> Withering f t
decayed pafb
_ s
_ = forall (f :: * -> *) a. Applicative f => Withering f a
empty

-- | Remove elements from the current 'Withering' context if they
-- don't match the predicate. This is similar in concept to @filtered@
-- from lens. The major that instead of merely removing non-matching
-- targets from the traversal, it removes those targets (and their
-- parents up to the next 'withered' combinator) from the data
-- structure entirely.
guarded
    :: Applicative f
    => (a -> Bool) -> (a -> Withering f b)
    -> a -> Withering f b
guarded :: forall (f :: * -> *) a b.
Applicative f =>
(a -> Bool) -> (a -> Withering f b) -> a -> Withering f b
guarded a -> Bool
p a -> Withering f b
f a
a
    | a -> Bool
p a
a = a -> Withering f b
f a
a
    | Bool
otherwise = forall (f :: * -> *) a. Applicative f => Withering f a
empty


-- | Remove elements matched by a specific 'Withering' context if they
-- don't match a predicate.
filterOf
    :: ((a -> Withering Identity a) -> s -> Identity s)
    -> (a -> Bool) -> s -> s
filterOf :: forall a s.
((a -> Withering Identity a) -> s -> Identity s)
-> (a -> Bool) -> s -> s
filterOf (a -> Withering Identity a) -> s -> Identity s
w a -> Bool
p = forall a. Identity a -> a
runIdentity forall b c a. (b -> c) -> (a -> b) -> a -> c
. (a -> Withering Identity a) -> s -> Identity s
w (forall {f :: * -> *} {a}.
Applicative f =>
(a -> Bool) -> a -> Withering f a
guarding a -> Bool
p)
  where
    guarding :: (a -> Bool) -> a -> Withering f a
guarding a -> Bool
p a
a
        | a -> Bool
p a
a = forall (f :: * -> *) a. Applicative f => a -> f a
pure a
a
        | Bool
otherwise = forall (f :: * -> *) a. Applicative f => Withering f a
empty
infix 2 `filterOf`

-- | Transform and filter elements matched by a specific 'Withering'
-- context, a la 'Data.Maybe.mapMaybe'.
mapMaybeOf
    :: ((a -> Withering Identity b) -> s -> Identity t)
    -> (a -> Maybe b) -> s -> t
mapMaybeOf :: forall a b s t.
((a -> Withering Identity b) -> s -> Identity t)
-> (a -> Maybe b) -> s -> t
mapMaybeOf (a -> Withering Identity b) -> s -> Identity t
w a -> Maybe b
p = forall a. Identity a -> a
runIdentity forall b c a. (b -> c) -> (a -> b) -> a -> c
. (a -> Withering Identity b) -> s -> Identity t
w (forall (f :: * -> *) a. f (Maybe a) -> Withering f a
Withering forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (f :: * -> *) a. Applicative f => a -> f a
pure forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> Maybe b
p)
infix 2 `mapMaybeOf`

-- | Transform and effectfully filter elements matched by a specific
-- 'Withering' context, a la 'wither'.
witherOf
    :: ((a -> Withering f b) -> s -> f t)
    -> (a -> f (Maybe b)) -> s -> f t
witherOf :: forall a (f :: * -> *) b s t.
((a -> Withering f b) -> s -> f t)
-> (a -> f (Maybe b)) -> s -> f t
witherOf (a -> Withering f b) -> s -> f t
w a -> f (Maybe b)
p = (a -> Withering f b) -> s -> f t
w (forall (f :: * -> *) a. f (Maybe a) -> Withering f a
Withering forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> f (Maybe b)
p)
infix 2 `witherOf`