lens-5.3.3: Lenses, Folds and Traversals

Copyright | (C) 2012-16 Edward Kmett
License | BSD-style (see the file LICENSE)
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | provisional
Portability | Rank2Types
Safe Haskell | Trustworthy
Language | Haskell2010

Control.Lens.Zoom

Description

Synopsis

- type family Magnified (m :: Type -> Type) :: Type -> Type -> Type
- class (Magnified m ~ Magnified n, MonadReader b m, MonadReader a n) => Magnify (m :: Type -> Type) (n :: Type -> Type) b a | m -> b, n -> a, m a -> n, n b -> m where
  - magnify :: ((Functor (Magnified m c), Contravariant (Magnified m c)) => LensLike' (Magnified m c) a b) -> m c -> n c
- class (MonadState s m, MonadState t n) => Zoom (m :: Type -> Type) (n :: Type -> Type) 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 Zoomed (m :: Type -> Type) :: Type -> Type -> Type

# Documentation

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 Control.Lens.Zoom type Magnified (IdentityT m) = Magnified m
type Magnified (ReaderT b m) # |
Instance details Defined in Control.Lens.Zoom type Magnified (ReaderT b m) = Effect m
type Magnified ((->) b) # |
Instance details Defined in Control.Lens.Zoom type Magnified ((->) b) = Const :: Type -> Type -> Type
type Magnified (RWST a w s m) # |
Instance details Defined in Control.Lens.Zoom type Magnified (RWST a w s m) = EffectRWS w s m
type Magnified (RWST a w s m) # |
Instance details Defined in Control.Lens.Zoom type Magnified (RWST a w s m) = EffectRWS w s m
type Magnified (RWST a w s m) # |
Instance details Defined in Control.Lens.Zoom type Magnified (RWST a w s m) = EffectRWS w s m

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

This class allows us to use `magnify` part of the environment, changing the environment supplied by many different `Monad` transformers. Unlike `zoom` this can change the environment of a deeply nested `Monad` transformer.

Also, unlike `zoom`, this can be used with any valid `Getter`, but cannot be used with a `Traversal` or `Fold`.

Methods

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

Run a monadic action in a larger environment than it was defined in, using a `Getter`.

This acts like `local`, but can in many cases change the type of the environment as well.

This is commonly used to lift actions in a simpler `Reader` `Monad` into a `Monad` with a larger environment type.

This can be used to edit pretty much any `Monad` transformer stack with an environment in it:

    >>> (1,2) & magnify _2 (+1)
    3

    >>> flip Reader.runReader (1,2) $ magnify _1 Reader.ask
    1

    >>> flip Reader.runReader (1,2,[10..20]) $ magnify (_3._tail) Reader.ask
    [11,12,13,14,15,16,17,18,19,20]

The type can be read as

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

but the higher-rank constraints make it easier to apply `magnify` to a `Getter` in highly-polymorphic code.

    magnify :: Getter s a -> (a -> r) -> s -> r
    magnify :: Monoid r => Fold s a   -> (a -> r) -> s -> r

    magnify :: Monoid w                 => Getter s t -> RWS t w st c -> RWS s w st c
    magnify :: (Monoid w, Monoid c) => Fold s a   -> RWS a w st c -> RWS s w st c
    ...

#### Instances

Instances details

Magnify m n b a => Magnify (IdentityT m) (IdentityT n) b a # |
Instance details Defined in Control.Lens.Zoom Methods magnify :: ((Functor (Magnified (IdentityT m) c), Contravariant (Magnified (IdentityT m) c)) => 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 Control.Lens.Zoom Methods magnify :: ((Functor (Magnified (ReaderT b m) c), Contravariant (Magnified (ReaderT b m) c)) => LensLike' (Magnified (ReaderT b m) c) a b) -> ReaderT b m c -> ReaderT a m c #

Magnify ((->) b) ((->) a) b a #

    magnify = views

Instance details Defined in Control.Lens.Zoom Methods magnify :: ((Functor (Magnified ((->) b) c), Contravariant (Magnified ((->) b) c)) => LensLike' (Magnified ((->) b) c) a b) -> (b -> c) -> a -> c #
(Monad m, Monoid w, MonadReader b (RWST b w s m)) => Magnify (RWST b w s m) (RWST a w s m) b a # |
Instance details Defined in Control.Lens.Zoom Methods magnify :: ((Functor (Magnified (RWST b w s m) c), Contravariant (Magnified (RWST b w s m) c)) => 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 Control.Lens.Zoom Methods magnify :: ((Functor (Magnified (RWST b w s m) c), Contravariant (Magnified (RWST b w s m) c)) => 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 Control.Lens.Zoom Methods magnify :: ((Functor (Magnified (RWST b w s m) c), Contravariant (Magnified (RWST b w s m) c)) => LensLike' (Magnified (RWST b w s m) c) a b) -> RWST b w s m c -> RWST a w s m c #

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

This class allows us to use `zoom` in, changing the `State` supplied by many different `Monad` transformers, potentially quite deep in a `Monad` transformer stack.

Methods

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

Run a monadic action in a larger `State` than it was defined in, using a `Lens'` or `Traversal'`.

This is commonly used to lift actions in a simpler `State` `Monad` into a `State` `Monad` with a larger `State` type.

When applied to a `Traversal'` over multiple values, the actions for each target are executed sequentially and the results are aggregated.

This can be used to edit pretty much any `Monad` transformer stack with a `State` in it!

    >>> flip State.evalState (a,b) $ zoom _1 $ use id
    a

    >>> flip State.execState (a,b) $ zoom _1 $ id .= c
    (c,b)

    >>> flip State.execState [(a,b),(c,d)] $ zoom traverse $ _2 %= f
    [(a,f b),(c,f d)]

    >>> flip State.runState [(a,b),(c,d)] $ zoom traverse $ _2 <%= f
    (f b <> f d <> mempty,[(a,f b),(c,f d)])

    >>> flip State.evalState (a,b) $ zoom both (use id)
    a <> b

    zoom :: Monad m             => Lens' s t      -> StateT t m a -> StateT s m a
    zoom :: (Monad m, Monoid c) => Traversal' s t -> StateT t m c -> StateT s m c
    zoom :: (Monad m, Monoid w)             => Lens' s t      -> RWST r w t m c -> RWST r w s m c
    zoom :: (Monad m, Monoid w, Monoid c) => Traversal' s t -> RWST r w t m c -> RWST r w s m c
    zoom :: (Monad m, Monoid w, Error e)  => Lens' s t      -> ErrorT e (RWST r w t m) c -> ErrorT e (RWST r w s m) c
    zoom :: (Monad m, Monoid w, Monoid c, Error e) => Traversal' s t -> ErrorT e (RWST r w t m) c -> ErrorT e (RWST r w s m) c
    ...

#### Instances

Instances details

Zoom m n s t => Zoom (MaybeT m) (MaybeT n) s t # |
Instance details Defined in Control.Lens.Zoom Methods zoom :: LensLike' (Zoomed (MaybeT m) c) t s -> MaybeT m c -> MaybeT n c #
(Functor f, Zoom m n s t) => Zoom (FreeT f m) (FreeT f n) s t # |
Instance details Defined in Control.Lens.Zoom Methods zoom :: LensLike' (Zoomed (FreeT f m) c) t s -> FreeT f m c -> FreeT f n c #
Zoom m n s t => Zoom (ExceptT e m) (ExceptT e n) s t # |
Instance details Defined in Control.Lens.Zoom 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 Control.Lens.Zoom 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 Control.Lens.Zoom 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 Control.Lens.Zoom 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 Control.Lens.Zoom 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 Control.Lens.Zoom 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 Control.Lens.Zoom 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 Control.Lens.Zoom 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 Control.Lens.Zoom 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 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 Control.Lens.Zoom type Zoomed (MaybeT m) = FocusingMay (Zoomed m)
type Zoomed (FreeT f m) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (FreeT f m) = FocusingFree f m (Zoomed m)
type Zoomed (ExceptT e m) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (ExceptT e m) = FocusingErr e (Zoomed m)
type Zoomed (IdentityT m) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (IdentityT m) = Zoomed m
type Zoomed (ReaderT e m) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (ReaderT e m) = Zoomed m
type Zoomed (StateT s z) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (StateT s z) = Focusing z
type Zoomed (StateT s z) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (StateT s z) = Focusing z
type Zoomed (WriterT w m) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (WriterT w m) = FocusingPlus w (Zoomed m)
type Zoomed (WriterT w m) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (WriterT w m) = FocusingPlus w (Zoomed m)
type Zoomed (RWST r w s z) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (RWST r w s z) = FocusingWith w z
type Zoomed (RWST r w s z) # |
Instance details Defined in Control.Lens.Zoom type Zoomed (RWST r w s z) = FocusingWith w z