Data.Profunctor.Optic.View

Types

type View s a = forall p. (Strong p, forall x. Contravariant (p x)) => Optic' p s a

type Ixview i s a = forall p. (Strong p, forall x. Contravariant (p x)) => IndexedOptic' p i s a

type PrimView s t a b = forall p. (Profunctor p, forall x. Contravariant (p x)) => Optic p s t a b

type Review t b = forall p. (Closed p, Bifunctor p) => Optic' p t b

type Cxview k t b = forall p. (Closed p, Bifunctor p) => CoindexedOptic' p k t b

type PrimReview s t a b = forall p. (Profunctor p, Bifunctor p) => Optic p s t a b

Constructors

to :: (s -> a) -> PrimView s t a b

Obtain a View from an arbitrary function.

to f . to g ≡ to (g . f)
a ^. to f ≡ f a

>>> ("hello","world") ^. to snd
"world"

>>> 5 ^. to succ
6

>>> (0, -5) ^. second' . to abs
5

to :: (s -> a) -> View s a

ito :: (s -> (i, a)) -> Ixview i s a

TODO: Document

from :: (b -> t) -> PrimReview s t a b

Obtain a Review from an arbitrary function.

from ≡ re . to

>>> (from Prelude.length) #^ [1,2,3]
3

from :: (b -> t) -> Review t b

kfrom :: ((k -> b) -> t) -> Cxview k t b

TODO: Document

cloneView :: AView s a -> PrimView s s a a

TODO: Document

cloneView ::             AView s a -> View s a
cloneView :: Monoid a => AView s a -> Fold s a

cloneReview :: AReview t b -> PrimReview t t b b

TODO: Document

Optics

like :: a -> PrimView s t a b

Obtain a constant-valued (index-preserving) View from an arbitrary value.

This can be useful as a second case failing a Fold e.g. foo failing like 0

like a . like b ≡ like b
a ^. like b ≡ b
a ^. like b ≡ a ^. to (const b)

like :: a -> View s a

ilike :: i -> a -> Ixview i s a

TODO: Document

relike :: t -> PrimReview s t a b

Obtain a constant-valued (index-preserving) Review from an arbitrary value.

relike a . relike b ≡ relike a
relike a # b ≡ a
relike a # b ≡ from (const a) # b

klike :: t -> Cxview k t b

Obtain a constant-valued Cxview from an arbitrary value.

toProduct :: AView s a1 -> AView s a2 -> PrimView s t (a1, a2) b

Combine two Views into a View to a product.

toProduct :: View s a1 -> View s a2 -> View s (a1 , a2)

fromSum :: AReview t b1 -> AReview t b2 -> PrimReview s t a (b1 + b2)

Combine two Reviews into a Review from a sum.

fromSum :: Review t b1 -> Review t b2 -> Review t (b1 + b2)

Primitive operators

withPrimView :: APrimView r s t a b -> (a -> r) -> s -> r

TODO: Document

withPrimReview :: APrimReview s t a b -> (t -> r) -> b -> r

TODO: Document

Operators

(^.) :: s -> AView s a -> a infixl 8

View the focus of an optic.

Fixity and semantics are such that subsequent field accesses can be performed with (.).

>>> ("hello","world") ^. second'
"world"

>>> 5 ^. to succ
6

>>> import Data.Complex
>>> ((0, 1 :+ 2), 3) ^. first' . second' . to magnitude
2.23606797749979

(^%) :: Monoid i => s -> AIxview i s a -> (Maybe i, a) infixl 8

View the focus of an indexed optic along with its index.

>>> ("foo", 42) ^% ifirst
(Just (),"foo")

>>> [(0,'f'),(1,'o'),(2,'o') :: (Int, Char)] ^% iat 2 . ifirst
(Just 2,2)

In order to iview a Choice optic (e.g. Ixaffine, Ixtraversal, Ixfold, etc), a must have a Monoid instance:

>>> ([] :: [Int]) ^% iat 0
(Nothing,0)

>>> ([1] :: [Int]) ^% iat 0
(Just 0,1)

view :: MonadReader s m => AView s a -> m a

A prefix alias for ^..

view . to ≡ id

>>> view second' (1, "hello")
"hello"

>>> view (to succ) 5
6

>>> view (second' . first') ("hello",("world","!!!"))
"world"

iview :: MonadReader s m => Monoid i => AIxview i s a -> m (Maybe i, a)

A prefix alias for ^%.

>>> iview ifirst ("foo", 42)
(Just (),"foo")

>>> iview (iat 3 . ifirst) [(0,'f'),(1,'o'),(2,'o'),(3,'b'),(4,'a'),(5,'r') :: (Int, Char)]
(Just 3,3)

In order to iview a Choice optic (e.g. Ixaffine, Ixtraversal, Ixfold, etc), a must have a Monoid instance:

>>> iview (iat 0) ([] :: [Int])
(Nothing,0)
>>> iview (iat 0) ([1] :: [Int])
(Just 0,1)

Note when applied to a Ixtraversal or Ixfold, then iview will return a monoidal summary of the indices tupled with a monoidal summary of the values:

>>> (iview @_ @_ @Int @Int) itraversed [1,2,3,4]
(Just 6,10)

views :: MonadReader s m => Optic' (Star (Const r)) s a -> (a -> r) -> m r

Map each part of a structure viewed to a semantic editor combinator.

'views o f ≡ withFold o f'
foldMap = views folding'

>>> views both id (["foo"], ["bar", "baz"])
["foo","bar","baz"]

views ::                AView s a       -> (a -> r) -> s -> r
views ::                Iso' s a        -> (a -> r) -> s -> r
views ::                Lens' s a       -> (a -> r) -> s -> r
views ::                Coprism' s a    -> (a -> r) -> s -> r
views :: Monoid r    => Traversal' s a  -> (a -> r) -> s -> r
views :: Semigroup r => Traversal1' s a -> (a -> r) -> s -> r
views :: Monoid r    => Fold s a        -> (a -> r) -> s -> r
views :: Semigroup r => Fold1 s a       -> (a -> r) -> s -> r

iviews :: MonadReader s m => Monoid i => IndexedOptic' (Star (Const r)) i s a -> (i -> a -> r) -> m r

Bring a function of the index and value of an indexed optic into the current environment.

iviews ≡ iwithFold

>>> iviews (iat 2) (-) ([0,1,2] :: [Int])
0

In order to iviews a Choice optic (e.g. Ixaffine, Ixtraversal, Ixfold, etc), a must have a Monoid instance (here from the rings package):

>>> iviews (iat 3) (flip const) ([1] :: [Int])
0

Use iview if there is a need to disambiguate between mempty as a miss vs. as a return value.

use :: MonadState s m => AView s a -> m a

TODO: Document

iuse :: MonadState s m => Monoid i => AIxview i s a -> m (Maybe i, a)

Bring the index and value of an indexed optic into the current environment as a pair.

uses :: MonadState s m => Optic' (Star (Const r)) s a -> (a -> r) -> m r

Use the target of a Lens, Iso or View in the current state, or use a summary of a Fold or Traversal that points to a monoidal value.

>>> evalState (uses first' length) ("hello","world!")
5

uses :: MonadState s m             => Iso' s a       -> (a -> r) -> m r
uses :: MonadState s m             => View s a     -> (a -> r) -> m r
uses :: MonadState s m             => Lens' s a      -> (a -> r) -> m r
uses :: MonadState s m             => Coprism' s a      -> (a -> r) -> m r
uses :: MonadState s m => Monoid r => Traversal' s a -> (a -> r) -> m r
uses :: MonadState s m => Monoid r => Fold s a       -> (a -> r) -> m r

uses :: MonadState s m => Getting r s t a b -> (a -> r) -> m r

iuses :: MonadState s m => Monoid i => IndexedOptic' (Star (Const r)) i s a -> (i -> a -> r) -> m r

Bring a function of the index and value of an indexed optic into the current environment.

(#^) :: AReview t b -> b -> t infixr 8

Dual to ^..

from f #^ x ≡ f x
o #^ x ≡ x ^. re o

This is commonly used when using a Prism as a smart constructor.

>>> left' #^ 4
Left 4

review :: MonadReader b m => AReview t b -> m t

A prefix alias of #^.

review ≡ view . re
review . from ≡ id

>>> review (from succ) 5
6

review :: Iso' s a   -> a -> s
review :: Prism' s a -> a -> s
review :: Colens' s a -> a -> s

kview :: MonadReader b m => ACxview k t b -> m (k -> t)

Bring a function of the index of a co-indexed optic into the current environment.

reviews :: MonadReader b m => AReview t b -> (t -> r) -> m r

Turn an optic around and look through the other end, applying a function.

reviews ≡ views . re
reviews (from f) g ≡ g . f

>>> reviews left' isRight "mustard"
False

>>> reviews (from succ) (*2) 3
8

reviews :: Iso' t b -> (t -> r) -> b -> r
reviews :: Prism' t b -> (t -> r) -> b -> r
reviews :: Colens' t b -> (t -> r) -> b -> r

kviews :: MonadReader b m => ACxview k t b -> ((k -> t) -> r) -> m r

Bring a continuation of the index of a co-indexed optic into the current environment.

kviews :: ACxview k t b -> ((k -> t) -> r) -> b -> r

reuse :: MonadState b m => AReview t b -> m t

Turn an optic around and use a value (or the current environment) through it the other way.

reuse ≡ use . re
reuse . from ≡ gets

>>> evalState (reuse left') 5
Left 5

>>> evalState (reuse (from succ)) 5
6

reuse :: MonadState a m => Iso' s a   -> m s
reuse :: MonadState a m => Prism' s a -> m s
reuse :: MonadState a m => Colens' s a -> m s

reuses :: MonadState b m => AReview t b -> (t -> r) -> m r

Turn an optic around and use the current state through it the other way, applying a function.

reuses ≡ uses . re
reuses (from f) g ≡ gets (g . f)

>>> evalState (reuses left' isLeft) (5 :: Int)
True

reuses :: MonadState a m => Iso' s a   -> (s -> r) -> m r
reuses :: MonadState a m => Prism' s a -> (s -> r) -> m r
reuses :: MonadState a m => Prism' s a -> (s -> r) -> m r

kuse :: MonadState b m => ACxview k t b -> m (k -> t)

TODO: Document

kuses :: MonadState b m => ACxview k t b -> ((k -> t) -> r) -> m r

TODO: Document

MonadIO

throws :: MonadIO m => Exception e => AReview e b -> b -> m r

Throw an exception described by an optic.

throws o e `seq` x  ≡ throws o e

throws_ :: MonadIO m => Exception e => AReview e () -> m r

Variant of throws for error constructors with no arguments.

throwsTo :: MonadIO m => Exception e => ThreadId -> AReview e b -> b -> m ()

Raise an Exception specified by an optic in the target thread.

throwsTo thread o ≡ throwTo thread . review o