-- | /Caution/: Improper use of this module can lead to unexpected behaviour if the preconditions of the functions are not met.
module Lens.Family.Unchecked (
-- * Adapters
-- | An adapter represents a isomorphism between two types or a parametric isomorphism between two families of types.
-- For example we can build an adapter between the type families @'Either' a a@ and @('Bool', a)@ as follows:
--
-- > timesTwo :: (Functor f, Functor g) => AdapterLike f g (Either a a) (Either b b) (Bool, a) (Bool b)
-- > timesTwo f x = fmap yang . f . fmap yin
-- >  where
-- >   yin (True, a) = Left a
-- >   yin (False, a) = Right a
-- >   yang (Left a) = (True, a)
-- >   yang (Right a) = (False, a)
--
-- /Note/: It is possible to adapters without even depending on @lens-family-core@ by expanding away the type synonym.
--
-- > timesTwo :: (Functor f, Functor g) => (g (Either a a) -> f (Either b b)) -> g (Bool, a) -> f (Bool, b)
--
-- The function 'adapter' can also be used to construct adapters from a pair of mutually inverse functions.

-- * Lenses
-- | A lens focuses on a field of record type.
-- Lenses can be used to get and/or set the focused field.
-- How to create a lens family is best illustrated by the common example of a field of a record:
--
-- > data MyRecord a = MyRecord { _myA :: a, _myInt :: Int }
-- >
-- > -- The use of type variables a and b allow for polymorphic updates.
-- > myA :: Functor f => LensLike f (MyRecord a) (MyRecord b) a b
-- > myA f (MyRecord a i) = (\b -> MyRecord b i) <$> f a
-- >
-- > -- The field _myInt is monomorphic, so we can use a 'LensLike''  type.
-- > -- However, the structure of the function is exactly the same as for LensLike.
-- > myInt :: Functor f => LensLike' f (MyRecord a) Int
-- > myInt f (MyRecord a i) = (\i' -> MyRecord a i') <$> f i
--
-- See the @lens-family-th@ package to generate this sort of code using Template Haskell.
--
-- /Note/: It is possible to build lenses without even depending on @lens-family-core@ by expanding away the type synonym.
--
-- > myA :: Functor f => (a -> f b) -> (MyRecord a) -> f (MyRecord b)
--
-- You can build lenses for more than just fields of records.
-- Any value @l :: Functor f => LensLike f s t a b@ is well-defined when it satisfies the two van Laarhoven lens laws:
--
-- * @l Identity === Identity@
--
-- * @l (Compose . fmap f . g) === Compose . fmap (l f) . (l g)@
--
-- The function 'lens' can also be used to construct lenses.
-- The resulting lenses will be well-defined so long as their preconditions are satisfied.

-- * Traversals
-- | If you have zero or more fields of the same type of a record, a traversal can be used to refer to all of them in order.
-- Multiple references are made by replacing the 'Functor' constraint of lenses with an 'Control.Applicative.Applicative' constraint.
-- Consider the following example of a record with two 'Int' fields.
--
-- > data MyRecord = MyRecord { _myA :: Int, _myB :: Int, _myC :: Bool }
-- >
-- > -- myInts is a traversal over both fields of MyRecord.
-- > myInts :: Applicative f => LensLike' f MyRecord Int
-- > myInts f (MyRecord a b c) = MyRecord <$> f a <*> f b <*> pure c
--
-- If the record and the referenced fields are parametric, you can can build polymrphic traversals.
-- Consider the following example of a record with two 'Maybe' fields.
--
-- > data MyRecord a = MyRecord { _myA0 :: Maybe a, _myA1 :: Maybe a, myC :: Bool }
-- >
-- > -- myMaybes is a traversal over both fields of MyRecord.
-- > myMaybes :: Applicative f => LensLike f (MyRecord a) (MyRecord b) (Maybe a) (Maybe b)
-- > myMaybes f (MyRecord a0 a1 c) = MyRecord <$> f a0 <*> f a1 <*> pure c
--
-- /Note/: It is possible to build traversals without even depending on @lens-family-core@ by expanding away the type synonym.
--
-- > myMaybes :: Applicative f => (Maybe a -> f (Maybe b)) -> MyRecord a -> f (MyRecord b)
-- > myMaybes f (MyRecord a0 a1 c) = MyRecord <$> f a0 <*> f a1 <*> pure c
--
-- Unfortunately, there are no helper functions for making traversals.
-- In most cases, you must make them by hand.
--
-- Any value @t :: Applicative f => LensLike f s t a b@ is well-defined when it satisfies the two van Laarhoven traversal laws:
--
-- * @t Identity === Identity@
--
-- * @t (Compose . fmap f . g) === Compose . fmap (t f) . (t g)@
--
-- 'Data.Traversable.traverse' is the canonical traversal for various containers.

-- * Prisms
-- | A prism focuses on a single variant of a type.
-- They can be used to 'Lens.Family.matching' / 'Lens.Family.review' the focused variant.
-- Consider the following example.
--
-- > data MySum a = MyA a | MyB Int
-- >
-- > -- myA is a prism for the MyA variant of MySum
-- > myA :: (Applicative f, Traversable g) => AdapterLike f g (MySum a) (MySum b) a b
-- > myA f = either pure (fmap MyA . f) . traverse h
-- >  where
-- >   h (MyA a) = Right a
-- >   h (MyB n) = Left (MyB n)
--
-- This prism can be used with 'Lens.Family.matching' via 'Lens.Family.under':
--
-- @ 'Lens.Family.matching' ('Lens.Family.under' myA) :: MySum a -> Either (MySum b) a @
--
-- This prism can be used with 'Lens.Family.review' via 'Lens.Family.over':
--
-- @ 'Lens.Family.review' ('Lens.Family.over' myA) :: a -> MySum a @
--
-- /Note/: It is possible to build prisms without even depending on @lens-family-core@ by expanding away the type synonym.
--
-- > myA :: (Appicative f, Traversable g) => (g a -> f b) -> g (MySum a) -> f (MySum b)
--
-- You can build prism for more than just constructors of sum types.
-- Any value @p :: (Applicative f, Traversable g) => AdapterLike f g s t a b@ is well-defined when it satisfies the prism laws:
--
-- * @matching (under p) (review (over p) b) === Right b@
--
-- * @(id ||| review (over p)) (matching (under p) s) === s@
--
-- * @left (match (under p)) (matching (under p) s) === left Left (matching (under p) s)@
--
-- The function 'prism' can also be used to construct prisms.
-- The resulting prisms will be well-defined so long as their preconditions are satisfied.

-- * Grates
-- | A grate focuses on the contents of a representable functor.
-- In other words, a grate focuses on the codomain of a function type or something isomorphic to a function type.
-- They are used to lift operations on this codomain to operations on the larger structure via zipping.
-- Consider the following example of a stream of 'Int's.
--
-- > data IntStream = IntStream { hd :: Int, tl :: IntStream }
-- >
-- > -- myInts is a grate over the Ints of IntStream.
-- > myInts :: Functor g => GrateLike' g IntStream Int
-- > myInts f s = IntStream (f (hd <$> s)) (myInts f (tl <$> s))
--
-- If the contents are parametric, you can can build polymorphic grates.
-- Consider the following example of a generic stream.
--
-- > data Stream a = Stream { hd :: a, tl :: Stream a }
-- >
-- > -- myStream is a grate over the contents of a Stream.
-- > myStream :: Functor g => GrateLike g (Stream a) (Stream b) a b
-- > myStream f s = Stream (f (hd <$> s)) (myStream f (tl <$> s))
--
-- /Note/: It is possible to build grates without even depending on @lens-family-core@ by expanding away the type synonym.
--
-- > myStream :: Functor g => (g (Stream a) -> Stream b) -> g a -> b
--
-- Any value @t :: Functor g => GrateLike g s t a b@ is a well-defined grate when it satisfies the two van Laarhoven traversal laws:
--
-- * @t runIdentity === runIdentity@
--
-- * @t (f . fmap g . runCompose) === (t f) . fmap (t g) . runCompose@
--
-- The function 'grate' can also be used to construct grates from graters.
-- The resulting grates will be well-defined so long as the preconditions are satisfied.

-- * Grids
-- | A grid is both a traversal and a grate.
-- When you have a type that is isomorphic to a fixed and finite number of copies of another type, a grid can be used to zip or traverse them.
-- Consider the following example of a record with exactly two 'Int' fields.
--
-- > data MyRecord = MyRecord { _myA :: Int, _myB :: Int }
-- >
-- > -- myInts is a grid over both fields of MyRecord.
-- > myInts :: (Applicative f, Functor g) => AdapterLike' f g MyRecord Int
-- > myInts f r = MyRecord <$> f (_myA <$> r) <*> f (_myB <$> r)
--
-- If the record and the referenced fields are parametric, you can can build polymorphic grids.
-- Consider the following example of a record with exactly two 'Maybe' fields.
--
-- > data MyRecord a = MyRecord { _myA0 :: Maybe a, _myA1 :: Maybe a }
-- >
-- > -- myMaybes is a traversal over both fields of MyRecord.
-- > myMaybes :: (Applicative f, Functor g) => AdapterLike f g (MyRecord a) (MyRecord b) (Maybe a) (Maybe b)
-- > myMaybes f r = MyRecord <$> f (_myA0 <$> r) <*> f (_myA1 <$> r)
--
-- A grid is converted into a grate by using the 'Lens.Family.over' function, and it is converted to a traversal by using the 'Lens.Family.under' function.
--
-- /Note/: It is possible to build grids without even depending on @lens-family-core@ by expanding away the type synonym.
--
-- > myMaybes :: (Applicative f, Functor g) => (g (Maybe a) -> f (Maybe b)) -> g (MyRecord a) -> f (MyRecord b)
--
-- Unfortunately, there are no helper functions for making grids.
-- In most cases, you must make them by hand.

-- * Documentation
    adapter
  , lens
  , prism
  , grate
  , setting
  , resetting
-- * Types
  , AdapterLike, AdapterLike'
  , LensLike, LensLike'
  , GrateLike, GrateLike'
  , Identical
  ) where

import Lens.Family.Identical

type AdapterLike f g s t a b = (g a -> f b) -> (g s -> f t)
type AdapterLike' f g s a = (g a -> f a) -> (g s -> f s)
type LensLike f s t a b = (a -> f b) -> (s -> f t)
type LensLike' f s a = (a -> f a) -> (s -> f s)
type GrateLike g s t a b = (g a -> b) -> (g s -> t)
type GrateLike' g s a = (g a -> a) -> (g s -> s)

adapter :: (Functor f, Functor g)
        => (s -> a) -- ^ yin
        -> (b -> t) -- ^ yang
        -> AdapterLike f g s t a b
-- ^ @
-- adapter :: (s -> a) -> (b -> t) -> Adapter s t a b
-- @
--
-- Build an adapter from an isomorphism family.
--
-- /Caution/: In order for the generated adapter family to be well-defined, you must ensure that the two isomorphism laws hold:
--
-- * @yin . yang === id@
--
-- * @yang . yin === id@
adapter yin yang f s = yang <$> f (yin <$> s)

lens :: Functor f
     => (s -> a) -- ^ getter
     -> (s -> b -> t) -- ^ setter
     -> LensLike f s t a b
-- ^ @
-- lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b
-- @
--
-- Build a lens from a @getter@ and @setter@ family.
--
-- /Caution/: In order for the generated lens family to be well-defined, you must ensure that the three lens laws hold:
--
-- * @getter (setter s a) === a@
--
-- * @setter s (getter s) === s@
--
-- * @setter (setter s a1) a2 === setter s a2@
lens getter setter f s = setter s <$> f (getter s)

grate :: Functor g
      => (((s -> a) -> b) -> t) -- ^ grater
      -> GrateLike g s t a b
-- ^ @
-- grate :: (((s -> a) -> b) -> t) -> Grate s t a b
-- @
--
-- Build a grate from a @grater@ family.
--
-- /Caution/: In order for the generated grate family to be well-defined, you must ensure that the two grater laws hold:
--
-- * @grater ($ s) === s@
--
-- * @grater (\k -> h (k . grater)) === grater (\k -> h ($ k))@
--
-- Note: The grater laws are that of an algebra for the parameterised continuation monad, `Lens.Family.PCont`.
grate grater f s = grater $ \h -> f (h <$> s)

prism :: (Applicative f, Traversable g)
      => (s -> Either t a) -- ^ matcher
      -> (b -> t) -- ^ reviewer
      -> AdapterLike f g s t a b
-- ^ @
-- prism :: (s -> Either t a) -> (b -> t) -> Prism s t a b
-- @
--
-- Build a prism from a @matcher@ and @reviewer@ family.
--
-- /Caution/: In order for the generated prism family to be well-defined, you must ensure that the three prism laws hold:
--
-- * @matcher (reviewer b) === Right b@
--
-- * @(id ||| reviewer) (matcher s) === s@
--
-- * @left matcher (matcher s) === left Left (matcher s)@
prism matcher reviewer f s = either pure (fmap reviewer . f) $ traverse matcher s

-- | 'setting' promotes a \"semantic editor combinator\" to a modify-only lens.
-- To demote a lens to a semantic edit combinator, use the section @(l %~)@ or @over l@ from "Lens.Family".
--
-- >>> [("The",0),("quick",1),("brown",1),("fox",2)] & setting map . fstL %~ length
-- [(3,0),(5,1),(5,1),(3,2)]
--
-- /Caution/: In order for the generated family to be well-defined, you must ensure that the two functors laws hold:
--
-- * @sec id === id@
--
-- * @sec f . sec g === sec (f . g)@
setting :: Identical f
        => ((a -> b) -> s -> t) -- ^ sec (semantic editor combinator)
        -> LensLike f s t a b
setting sec f = pure . sec (extract . f)

-- | 'resetting' promotes a \"semantic editor combinator\" to a form of grate that can only lift unary functions.
-- To demote a grate to a semantic edit combinator, use @under l@ from "Lens.Family".
--
-- /Caution/: In order for the generated family to be well-defined, you must ensure that the two functors laws hold:
--
-- * @sec id === id@
--
-- * @sec f . sec g === sec (f . g)@
resetting :: Identical g
        => ((a -> b) -> s -> t) -- ^ sec (semantic editor combinator)
        -> GrateLike g s t a b
resetting sec f = sec (f . pure) . extract