Copyright	(C) 2013-2016 Edward Kmett 2015-2016 Artyom Kazak 2018 Monadfix
License	BSD-style (see the file LICENSE)
Safe Haskell	Trustworthy
Language	Haskell2010

Lens.Micro.Mtl.Internal

Contents

Classes
Focusing (used for Zoom)
Effect (used for Magnify)
Utilities

Description

This module lets you define your own instances of Zoom and Magnify.

The warning from Lens.Micro.Internal applies to this module as well. Don't export functions that have Zoom or Magnify in their type signatures. If you absolutely need to define an instance (e.g. for internal use), only do it for your own types, because otherwise I might add an instance to one of the microlens packages later and if our instances are different it might lead to subtle bugs.

Synopsis

type family Zoomed (m :: Type -> Type) :: Type -> Type -> Type
class (MonadState s m, MonadState t n) => Zoom m n s t | m -> s, n -> t, m t -> n, n s -> m where
- zoom :: LensLike' (Zoomed m c) t s -> m c -> n c
type family Magnified (m :: Type -> Type) :: Type -> Type -> Type
class (MonadReader b m, MonadReader a n) => Magnify m n b a | m -> b, n -> a, m a -> n, n b -> m where
- magnify :: LensLike' (Magnified m c) a b -> m c -> n c
newtype Focusing m s a = Focusing {
- unfocusing :: m (s, a)
}
newtype FocusingWith w m s a = FocusingWith {
- unfocusingWith :: m (s, a, w)
}
newtype FocusingPlus w k s a = FocusingPlus {
- unfocusingPlus :: k (s, w) a
}
newtype FocusingOn f k s a = FocusingOn {
- unfocusingOn :: k (f s) a
}
newtype FocusingMay k s a = FocusingMay {
- unfocusingMay :: k (May s) a
}
newtype FocusingErr e k s a = FocusingErr {
- unfocusingErr :: k (Err e s) a
}
newtype Effect m r a = Effect {
- getEffect :: m r
}
newtype EffectRWS w st m s a = EffectRWS {
- getEffectRWS :: st -> m (s, st, w)
}
newtype May a = May {
- getMay :: Maybe a
}
newtype Err e a = Err {
- getErr :: Either e a
}

Classes

type family Zoomed (m :: Type -> Type) :: Type -> Type -> Type #

This type family is used by Zoom to describe the common effect type.

Instances

Instances details

type Zoomed (MaybeT m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (MaybeT m) = FocusingMay (Zoomed m)
type Zoomed (ExceptT e m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (ExceptT e m) = FocusingErr e (Zoomed m)
type Zoomed (IdentityT m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (IdentityT m) = Zoomed m
type Zoomed (ReaderT e m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (ReaderT e m) = Zoomed m
type Zoomed (StateT s z) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (StateT s z) = Focusing z
type Zoomed (StateT s z) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (StateT s z) = Focusing z
type Zoomed (WriterT w m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (WriterT w m) = FocusingPlus w (Zoomed m)
type Zoomed (WriterT w m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (WriterT w m) = FocusingPlus w (Zoomed m)
type Zoomed (RWST r w s z) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (RWST r w s z) = FocusingWith w z
type Zoomed (RWST r w s z) #
Instance details Defined in Lens.Micro.Mtl.Internal type Zoomed (RWST r w s z) = FocusingWith w z

class (MonadState s m, MonadState t n) => Zoom m n s t | m -> s, n -> t, m t -> n, n s -> m where #

Methods

zoom :: LensLike' (Zoomed m c) t s -> m c -> n c infixr 2 #

When you're in a state monad, this function lets you operate on a part of your state. For instance, if your state was a record containing a position field, after zooming position would become your whole state (and when you modify it, the bigger structure would be modified as well).

(Your State / StateT or RWS / RWST can be anywhere in the stack, but you can't use zoom with arbitrary MonadState because it doesn't provide any methods to change the type of the state. See this issue for details.)

For the sake of the example, let's define some types first:

data Position = Position {
  _x, _y :: Int }

data Player = Player {
  _position :: Position,
  ... }

data Game = Game {
  _player :: Player,
  _obstacles :: [Position],
  ... }

concat <$> mapM makeLenses [''Position, ''Player, ''Game]

Now, here's an action that moves the player north-east:

moveNE :: State Game ()
moveNE = do
  player.position.x += 1
  player.position.y += 1

With zoom, you can use player.position to focus just on a part of the state:

moveNE :: State Game ()
moveNE = do
  zoom (player.position) $ do
    x += 1
    y += 1

You can just as well use it for retrieving things out of the state:

getCoords :: State Game (Int, Int)
getCoords = zoom (player.position) ((,) <$> use x <*> use y)

Or more explicitly:

getCoords = zoom (player.position) $ do
  x' <- use x
  y' <- use y
  return (x', y')

When you pass a traversal to zoom, it'll work as a loop. For instance, here we move all obstacles:

moveObstaclesNE :: State Game ()
moveObstaclesNE = do
  zoom (obstacles.each) $ do
    x += 1
    y += 1

If the action returns a result, all results would be combined with <> – the same way they're combined when ^. is passed a traversal. In this example, moveObstaclesNE returns a list of old coordinates of obstacles in addition to moving them:

moveObstaclesNE = do
  xys <- zoom (obstacles.each) $ do
    -- Get old coordinates.
    x' <- use x
    y' <- use y
    -- Update them.
    x .= x' + 1
    y .= y' + 1
    -- Return a single-element list with old coordinates.
    return [(x', y')]
  ...

Finally, you might need to write your own instances of Zoom if you use newtyped transformers in your monad stack. This can be done as follows:

import Lens.Micro.Mtl.Internal

type instance Zoomed (MyStateT s m) = Zoomed (StateT s m)

instance Monad m => Zoom (MyStateT s m) (MyStateT t m) s t where
    zoom l (MyStateT m) = MyStateT (zoom l m)

Instances

Instances details

Zoom m n s t => Zoom (MaybeT m) (MaybeT n) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (MaybeT m) c) t s -> MaybeT m c -> MaybeT n c #
Zoom m n s t => Zoom (ExceptT e m) (ExceptT e n) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (ExceptT e m) c) t s -> ExceptT e m c -> ExceptT e n c #
Zoom m n s t => Zoom (IdentityT m) (IdentityT n) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (IdentityT m) c) t s -> IdentityT m c -> IdentityT n c #
Zoom m n s t => Zoom (ReaderT e m) (ReaderT e n) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (ReaderT e m) c) t s -> ReaderT e m c -> ReaderT e n c #
Monad z => Zoom (StateT s z) (StateT t z) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (StateT s z) c) t s -> StateT s z c -> StateT t z c #
Monad z => Zoom (StateT s z) (StateT t z) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (StateT s z) c) t s -> StateT s z c -> StateT t z c #
(Monoid w, Zoom m n s t) => Zoom (WriterT w m) (WriterT w n) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (WriterT w m) c) t s -> WriterT w m c -> WriterT w n c #
(Monoid w, Zoom m n s t) => Zoom (WriterT w m) (WriterT w n) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (WriterT w m) c) t s -> WriterT w m c -> WriterT w n c #
(Monoid w, Monad z) => Zoom (RWST r w s z) (RWST r w t z) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (RWST r w s z) c) t s -> RWST r w s z c -> RWST r w t z c #
(Monoid w, Monad z) => Zoom (RWST r w s z) (RWST r w t z) s t #
Instance details Defined in Lens.Micro.Mtl.Internal Methods zoom :: LensLike' (Zoomed (RWST r w s z) c) t s -> RWST r w s z c -> RWST r w t z c #

type family Magnified (m :: Type -> Type) :: Type -> Type -> Type #

This type family is used by Magnify to describe the common effect type.

Instances

Instances details

type Magnified (IdentityT m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Magnified (IdentityT m) = Magnified m
type Magnified (ReaderT b m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Magnified (ReaderT b m) = Effect m
type Magnified ((->) b) #
Instance details Defined in Lens.Micro.Mtl.Internal type Magnified ((->) b) = Const :: Type -> Type -> Type
type Magnified (RWST a w s m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Magnified (RWST a w s m) = EffectRWS w s m
type Magnified (RWST a w s m) #
Instance details Defined in Lens.Micro.Mtl.Internal type Magnified (RWST a w s m) = EffectRWS w s m

class (MonadReader b m, MonadReader a n) => Magnify m n b a | m -> b, n -> a, m a -> n, n b -> m where #

Methods

magnify :: LensLike' (Magnified m c) a b -> m c -> n c infixr 2 #

This is an equivalent of local which lets you apply a getter to your environment instead of merely applying a function (and it also lets you change the type of the environment).

local   :: (r -> r)   -> Reader r a -> Reader r a
magnify :: Getter r x -> Reader x a -> Reader r a

magnify works with Reader / ReaderT, RWS / RWST, and (->).

Here's an example of magnify being used to work with a part of a bigger config. First, the types:

data URL = URL {
  _protocol :: Maybe String,
  _path :: String }

data Config = Config {
  _base :: URL,
  ... }

makeLenses ''URL
makeLenses ''Config

Now, let's define a function which returns the base url:

getBase :: Reader Config String
getBase = do
  protocol <- fromMaybe "https" <$> view (base.protocol)
  path     <- view (base.path)
  return (protocol ++ path)

With magnify, we can factor out base:

getBase = magnify base $ do
  protocol <- fromMaybe "https" <$> view protocol
  path     <- view path
  return (protocol ++ path)

This concludes the example.

Finally, you should know writing instances of Magnify for your own types can be done as follows:

import Lens.Micro.Mtl.Internal

type instance Magnified (MyReaderT r m) = Magnified (ReaderT r m)

instance Monad m => Magnify (MyReaderT r m) (MyReaderT t m) r t where
    magnify l (MyReaderT m) = MyReaderT (magnify l m)

Instances

Instances details

Magnify m n b a => Magnify (IdentityT m) (IdentityT n) b a #
Instance details Defined in Lens.Micro.Mtl.Internal Methods magnify :: LensLike' (Magnified (IdentityT m) c) a b -> IdentityT m c -> IdentityT n c #
Monad m => Magnify (ReaderT b m) (ReaderT a m) b a #
Instance details Defined in Lens.Micro.Mtl.Internal Methods magnify :: LensLike' (Magnified (ReaderT b m) c) a b -> ReaderT b m c -> ReaderT a m c #
Magnify ((->) b) ((->) a) b a #
Instance details Defined in Lens.Micro.Mtl.Internal Methods magnify :: LensLike' (Magnified ((->) b) c) a b -> (b -> c) -> a -> c #
(Monad m, Monoid w) => Magnify (RWST b w s m) (RWST a w s m) b a #
Instance details Defined in Lens.Micro.Mtl.Internal Methods magnify :: LensLike' (Magnified (RWST b w s m) c) a b -> RWST b w s m c -> RWST a w s m c #
(Monad m, Monoid w) => Magnify (RWST b w s m) (RWST a w s m) b a #
Instance details Defined in Lens.Micro.Mtl.Internal Methods magnify :: LensLike' (Magnified (RWST b w s m) c) a b -> RWST b w s m c -> RWST a w s m c #

Focusing (used for `Zoom`)

newtype Focusing m s a #

Used by Zoom to zoom into StateT.

Constructors

Focusing
Fields unfocusing :: m (s, a)

Instances

Instances details

(Monad m, Monoid s) => Applicative (Focusing m s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> Focusing m s a (<>) :: Focusing m s (a -> b) -> Focusing m s a -> Focusing m s b liftA2 :: (a -> b -> c) -> Focusing m s a -> Focusing m s b -> Focusing m s c (>) :: Focusing m s a -> Focusing m s b -> Focusing m s b (<*) :: Focusing m s a -> Focusing m s b -> Focusing m s a
Monad m => Functor (Focusing m s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> Focusing m s a -> Focusing m s b (<$) :: a -> Focusing m s b -> Focusing m s a

newtype FocusingWith w m s a #

Used by Zoom to zoom into RWST.

Constructors

FocusingWith
Fields unfocusingWith :: m (s, a, w)

Instances

Instances details

(Monad m, Monoid s, Monoid w) => Applicative (FocusingWith w m s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> FocusingWith w m s a (<>) :: FocusingWith w m s (a -> b) -> FocusingWith w m s a -> FocusingWith w m s b liftA2 :: (a -> b -> c) -> FocusingWith w m s a -> FocusingWith w m s b -> FocusingWith w m s c (>) :: FocusingWith w m s a -> FocusingWith w m s b -> FocusingWith w m s b (<*) :: FocusingWith w m s a -> FocusingWith w m s b -> FocusingWith w m s a
Monad m => Functor (FocusingWith w m s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> FocusingWith w m s a -> FocusingWith w m s b (<$) :: a -> FocusingWith w m s b -> FocusingWith w m s a

newtype FocusingPlus w k s a #

Used by Zoom to zoom into WriterT.

Constructors

FocusingPlus
Fields unfocusingPlus :: k (s, w) a

Instances

Instances details

Applicative (k (s, w)) => Applicative (FocusingPlus w k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> FocusingPlus w k s a (<>) :: FocusingPlus w k s (a -> b) -> FocusingPlus w k s a -> FocusingPlus w k s b liftA2 :: (a -> b -> c) -> FocusingPlus w k s a -> FocusingPlus w k s b -> FocusingPlus w k s c (>) :: FocusingPlus w k s a -> FocusingPlus w k s b -> FocusingPlus w k s b (<*) :: FocusingPlus w k s a -> FocusingPlus w k s b -> FocusingPlus w k s a
Functor (k (s, w)) => Functor (FocusingPlus w k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> FocusingPlus w k s a -> FocusingPlus w k s b (<$) :: a -> FocusingPlus w k s b -> FocusingPlus w k s a

newtype FocusingOn f k s a #

Used by Zoom to zoom into MaybeT or ListT.

Constructors

FocusingOn
Fields unfocusingOn :: k (f s) a

Instances

Instances details

Applicative (k (f s)) => Applicative (FocusingOn f k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> FocusingOn f k s a (<>) :: FocusingOn f k s (a -> b) -> FocusingOn f k s a -> FocusingOn f k s b liftA2 :: (a -> b -> c) -> FocusingOn f k s a -> FocusingOn f k s b -> FocusingOn f k s c (>) :: FocusingOn f k s a -> FocusingOn f k s b -> FocusingOn f k s b (<*) :: FocusingOn f k s a -> FocusingOn f k s b -> FocusingOn f k s a
Functor (k (f s)) => Functor (FocusingOn f k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> FocusingOn f k s a -> FocusingOn f k s b (<$) :: a -> FocusingOn f k s b -> FocusingOn f k s a

newtype FocusingMay k s a #

Used by Zoom to zoom into ErrorT.

Constructors

FocusingMay
Fields unfocusingMay :: k (May s) a

Instances

Instances details

Applicative (k (May s)) => Applicative (FocusingMay k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> FocusingMay k s a (<>) :: FocusingMay k s (a -> b) -> FocusingMay k s a -> FocusingMay k s b liftA2 :: (a -> b -> c) -> FocusingMay k s a -> FocusingMay k s b -> FocusingMay k s c (>) :: FocusingMay k s a -> FocusingMay k s b -> FocusingMay k s b (<*) :: FocusingMay k s a -> FocusingMay k s b -> FocusingMay k s a
Functor (k (May s)) => Functor (FocusingMay k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> FocusingMay k s a -> FocusingMay k s b (<$) :: a -> FocusingMay k s b -> FocusingMay k s a

newtype FocusingErr e k s a #

Used by Zoom to zoom into ErrorT.

Constructors

FocusingErr
Fields unfocusingErr :: k (Err e s) a

Instances

Instances details

Applicative (k (Err e s)) => Applicative (FocusingErr e k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> FocusingErr e k s a (<>) :: FocusingErr e k s (a -> b) -> FocusingErr e k s a -> FocusingErr e k s b liftA2 :: (a -> b -> c) -> FocusingErr e k s a -> FocusingErr e k s b -> FocusingErr e k s c (>) :: FocusingErr e k s a -> FocusingErr e k s b -> FocusingErr e k s b (<*) :: FocusingErr e k s a -> FocusingErr e k s b -> FocusingErr e k s a
Functor (k (Err e s)) => Functor (FocusingErr e k s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> FocusingErr e k s a -> FocusingErr e k s b (<$) :: a -> FocusingErr e k s b -> FocusingErr e k s a

Effect (used for `Magnify`)

newtype Effect m r a #

Wrap a monadic effect with a phantom type argument.

Constructors

Effect
Fields getEffect :: m r

Instances

Instances details

(Monad m, Monoid r) => Applicative (Effect m r) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> Effect m r a (<>) :: Effect m r (a -> b) -> Effect m r a -> Effect m r b liftA2 :: (a -> b -> c) -> Effect m r a -> Effect m r b -> Effect m r c (>) :: Effect m r a -> Effect m r b -> Effect m r b (<*) :: Effect m r a -> Effect m r b -> Effect m r a
Functor (Effect m r) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> Effect m r a -> Effect m r b (<$) :: a -> Effect m r b -> Effect m r a
(Monad m, Monoid r) => Monoid (Effect m r a) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods mempty :: Effect m r a mappend :: Effect m r a -> Effect m r a -> Effect m r a mconcat :: [Effect m r a] -> Effect m r a
(Monad m, Semigroup r) => Semigroup (Effect m r a) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods (<>) :: Effect m r a -> Effect m r a -> Effect m r a sconcat :: NonEmpty (Effect m r a) -> Effect m r a stimes :: Integral b => b -> Effect m r a -> Effect m r a

newtype EffectRWS w st m s a #

Wrap a monadic effect with a phantom type argument. Used when magnifying RWST.

Constructors

EffectRWS
Fields getEffectRWS :: st -> m (s, st, w)

Instances

Instances details

(Monoid s, Monoid w, Monad m) => Applicative (EffectRWS w st m s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods pure :: a -> EffectRWS w st m s a (<>) :: EffectRWS w st m s (a -> b) -> EffectRWS w st m s a -> EffectRWS w st m s b liftA2 :: (a -> b -> c) -> EffectRWS w st m s a -> EffectRWS w st m s b -> EffectRWS w st m s c (>) :: EffectRWS w st m s a -> EffectRWS w st m s b -> EffectRWS w st m s b (<*) :: EffectRWS w st m s a -> EffectRWS w st m s b -> EffectRWS w st m s a
Functor (EffectRWS w st m s) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods fmap :: (a -> b) -> EffectRWS w st m s a -> EffectRWS w st m s b (<$) :: a -> EffectRWS w st m s b -> EffectRWS w st m s a

Utilities

newtype May a #

Make a Monoid out of Maybe for error handling.

Constructors

May
Fields getMay :: Maybe a

Instances

Instances details

Monoid a => Monoid (May a) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods mempty :: May a mappend :: May a -> May a -> May a mconcat :: [May a] -> May a
Semigroup a => Semigroup (May a) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods (<>) :: May a -> May a -> May a sconcat :: NonEmpty (May a) -> May a stimes :: Integral b => b -> May a -> May a

newtype Err e a #

Make a Monoid out of Either for error handling.

Constructors

Err
Fields getErr :: Either e a

Instances

Instances details

Monoid a => Monoid (Err e a) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods mempty :: Err e a mappend :: Err e a -> Err e a -> Err e a mconcat :: [Err e a] -> Err e a
Semigroup a => Semigroup (Err e a) #
Instance details Defined in Lens.Micro.Mtl.Internal Methods (<>) :: Err e a -> Err e a -> Err e a sconcat :: NonEmpty (Err e a) -> Err e a stimes :: Integral b => b -> Err e a -> Err e a

Classes

Instances

Instances

Instances

Instances

Focusing (used for Zoom)

Instances

Instances

Instances

Instances

Instances

Instances

Effect (used for Magnify)

Instances

Instances

Utilities

Instances

Instances

Focusing (used for `Zoom`)

Effect (used for `Magnify`)