Data.Profunctor.Optic.Prelude

Documentation

re :: Optic (Re p a b) s t a b -> Optic p b a t s

Reverse an optic to obtain its dual.

>>> 5 ^. re left'
Left 5

>>> 6 ^. re (left' . from succ)
Left 7

re . re  ≡ id

re :: Iso s t a b   -> Iso b a t s
re :: Lens s t a b  -> Colens b a t s
re :: Prism s t a b -> Coprism b a t s

invert :: AIso s t a b -> Iso b a t s

Invert an isomorphism.

invert (invert o) ≡ o

(&) :: a -> (a -> b) -> b infixl 1

& is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator $, which allows & to be nested in $.

>>> 5 & (+1) & show
"6"

Since: base-4.8.0.0

Composition

(.) :: (b -> c) -> (a -> b) -> a -> c infixr 9

Function composition.

(%) :: Semigroup i => Representable p => IndexedOptic p i b1 b2 a1 a2 -> IndexedOptic p i c1 c2 b1 b2 -> IndexedOptic p i c1 c2 a1 a2 infixr 8

Compose two indexed traversals, combining indices.

Its precedence is one lower than that of function composition, which allows . to be nested in %.

>>> ilists (itraversed . itraversed) exercises
[("crunches",25),("handstands",5),("crunches",20),("pushups",10),("handstands",3),("pushups",15)]

>>> ilists (itraversed % itraversed) exercises
[("Fridaycrunches",25),("Fridayhandstands",5),("Mondaycrunches",20),("Mondaypushups",10),("Wednesdayhandstands",3),("Wednesdaypushups",15)]

If you only need the final index then use .:

>>> ilists (itraversed . itraversed) foobar
[(0,"foo"),(1,"bar"),(0,"baz"),(1,"bip")]

This is identical to the more convoluted:

>>> ilistsFrom (ilast itraversed % ilast itraversed) (Last 0) foobar & fmapped . first' ..~ getLast
[(0,"foo"),(1,"bar"),(0,"baz"),(1,"bip")]

(#) :: Semigroup k => Corepresentable p => CoindexedOptic p k b1 b2 a1 a2 -> CoindexedOptic p k c1 c2 b1 b2 -> CoindexedOptic p k c1 c2 a1 a2 infixr 8

Compose two coindexed traversals, combining indices.

Its precedence is one lower than that of function composition, which allows . to be nested in #.

If you only need the final index then use ..

View operators

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"

(^.) :: 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

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)

(^%) :: 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)

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

(#^) :: 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

Setter operators

set :: Optic (->) s t a b -> b -> s -> t

Prefix variant of .~.

 set l y (set l x a) ≡ set l y a

(.~) :: Optic (->) s t a b -> b -> s -> t infixr 4

Set all referenced fields to the given value.

iset :: Monoid i => AIxsetter i s t a b -> (i -> b) -> s -> t

Prefix alias of %~.

Equivalent to iover with the current value ignored.

set o ≡ iset o . const

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

>>> iset (iat 5) (const 0) [1,2,3 :: Int]
[1,2,3]

(%~) :: Monoid i => AIxsetter i s t a b -> (i -> b) -> s -> t infixr 4

Set the focus of an indexed optic.

See also #~.

Note if you're looking for the infix over it is ..~.

kset :: Monoid k => ACxsetter k s t a b -> (k -> b) -> s -> t

Prefix alias of #~.

Equivalent to kover with the current value ignored.

(#~) :: Monoid k => ACxsetter k s t a b -> (k -> b) -> s -> t infixr 4

Set the focus of a coindexed optic.

See also %~.

over :: Optic (->) s t a b -> (a -> b) -> s -> t

Prefix alias of ..~.

over o id ≡ id 
over o f . over o g ≡ over o (f . g)
over . setter ≡ id
over . resetter ≡ id

>>> over fmapped (+1) (Just 1)
Just 2

>>> over fmapped (*10) [1,2,3]
[10,20,30]

>>> over first' (+1) (1,2)
(2,2)

>>> over first' show (10,20)
("10",20)

(..~) :: Optic (->) s t a b -> (a -> b) -> s -> t infixr 4

Map over an optic.

>>> Just 1 & just ..~ (+1)
Just 2

>>> Nothing & just ..~ (+1)
Nothing

>>> [1,2,3] & fmapped ..~ (*10)
[10,20,30]

>>> (1,2) & first' ..~ (+1)
(2,2)

>>> (10,20) & first' ..~ show
("10",20)

iover :: Monoid i => AIxsetter i s t a b -> (i -> a -> b) -> s -> t

Prefix alias of %%~.

>>> iover (iat 1) (+) [1,2,3 :: Int]
[1,3,3]

>>> iover (iat 5) (+) [1,2,3 :: Int]
[1,2,3]

(%%~) :: Monoid i => AIxsetter i s t a b -> (i -> a -> b) -> s -> t infixr 4

Map over an indexed optic.

See also ##~.

kover :: Monoid k => ACxsetter k s t a b -> (k -> a -> b) -> s -> t

Prefix alias of ##~.

(##~) :: Monoid k => ACxsetter k s t a b -> (k -> a -> b) -> s -> t infixr 4

Map over a coindexed optic.

Infix variant of kover.

See also %%~.

(<>~) :: Semigroup a => Optic (->) s t a a -> a -> s -> t infixr 4

Modify the target by adding another value.

>>> both <>~ True $ (False,True)
(True,True)

>>> both <>~ "!" $ ("bar","baz")
("bar!","baz!")

(><~) :: Semiring a => Optic (->) s t a a -> a -> s -> t infixr 4

Modify the target by multiplying by another value.

>>> both ><~ False $ (False,True)
(False,False)

>>> both ><~ ["!"] $ (["bar","baz"], [])
(["bar!","baz!"],[])

Fold operators

preview :: MonadReader s m => AOption a s a -> m (Maybe a)

TODO: Document

(^?) :: s -> AOption a s a -> Maybe a infixl 8

An infix alias for preview'.

(^?) ≡ flip preview'

Perform a safe head of a Fold or Traversal or retrieve Just the result from a View or Lens.

When using a Traversal as a partial Lens, or a Fold as a partial View this can be a convenient way to extract the optional value.

>>> Left 4 ^? left'
Just 4

>>> Right 4 ^? left'
Nothing

is :: AOption a s a -> s -> Bool

Check whether the optic is matched.

>>> is just Nothing
False

isnt :: AOption a s a -> s -> Bool

Check whether the optic isn't matched.

>>> isnt just Nothing
True

matches :: AAffine s t a b -> s -> t + a

Test whether the optic matches or not.

>>> matches just (Just 2)
Right 2

>>> matches just (Nothing :: Maybe Int) :: Either (Maybe Bool) Int
Left Nothing

lists :: AFold (Endo [a]) s a -> s -> [a]

Collect the foci of an optic into a list.

(^..) :: s -> AFold (Endo [a]) s a -> [a] infixl 8

Infix alias of lists.

toList xs ≡ xs ^.. folding
(^..) ≡ flip lists

>>> [[1,2], [3 :: Int]] ^.. id
[[[1,2],[3]]]
>>> [[1,2], [3 :: Int]] ^.. traversed
[[1,2],[3]]
>>> [[1,2], [3 :: Int]] ^.. traversed . traversed
[1,2,3]

>>> (1,2) ^.. bitraversed
[1,2]

(^..) :: s -> View s a     -> a :: s -> Fold s a       -> a :: s -> Lens' s a      -> a :: s -> Iso' s a       -> a :: s -> Traversal' s a -> a :: s -> Prism' s a     -> a :: s -> Affine' s a    -> [a]

ilists :: Monoid i => AIxfold (Endo [(i, a)]) i s a -> s -> [(i, a)]

Collect the foci of an indexed optic into a list of index-value pairs.

lists l ≡ map snd . ilists l

ilistsFrom :: AIxfold (Endo [(i, a)]) i s a -> i -> s -> [(i, a)]

Collect the foci of an indexed optic into a list of index-value pairs.

This is only for use with the few indexed optics that don't ignore their output index. You most likely want to use ilists.

(^%%) :: Monoid i => s -> AIxfold (Endo [(i, a)]) i s a -> [(i, a)] infixl 8

Infix version of ilists.

folds :: Monoid a => AFold a s a -> s -> a

TODO: Document

foldsa :: Applicative f => Monoid (f a) => AFold (f a) s a -> s -> f a

TODO: Document

foldsa :: Fold s a -> s -> [a]
foldsa :: Applicative f => Setter s t a b -> s -> f a

foldsp :: Monoid r => Semiring r => AFold (Prod r) s a -> (a -> r) -> s -> r

Compute the semiring product of the foci of an optic.

For semirings without a multiplicative unit this is equivalent to const mempty:

>>> foldsp folded Just [1..(5 :: Int)]
Just 0

In this situation you most likely want to use folds1p.

foldsr :: AFold (Endo r) s a -> (a -> r -> r) -> r -> s -> r

Right fold over an optic.

>>> foldsr folded (<>) 0 [1..5::Int]
15

ifoldsr :: Monoid i => AIxfold (Endo r) i s a -> (i -> a -> r -> r) -> r -> s -> r

Indexed right fold over an indexed optic.

foldsr o ≡ ifoldsr o . const

>>> ifoldsr itraversed (\i a -> ((show i ++ ":" ++ show a ++ ", ") ++)) [] [1,3,5,7,9]
"0:1, 1:3, 2:5, 3:7, 4:9, "

ifoldsrFrom :: AIxfold (Endo r) i s a -> (i -> a -> r -> r) -> i -> r -> s -> r

Indexed right fold over an indexed optic, using an initial index value.

This is only for use with the few indexed optics that don't ignore their output index. You most likely want to use ifoldsr.

foldsl :: AFold (Dual (Endo r)) s a -> (r -> a -> r) -> r -> s -> r

Left fold over an optic.

ifoldsl :: Monoid i => AIxfold (Dual (Endo r)) i s a -> (i -> r -> a -> r) -> r -> s -> r

Left fold over an indexed optic.

ifoldslFrom :: AIxfold (Dual (Endo r)) i s a -> (i -> r -> a -> r) -> i -> r -> s -> r

Left fold over an indexed optic, using an initial index value.

This is only for use with the few indexed optics that don't ignore their output index. You most likely want to use ifoldsl.

foldsr' :: AFold (Dual (Endo (Endo r))) s a -> (a -> r -> r) -> r -> s -> r

Strict right fold over an optic.

ifoldsr' :: Monoid i => AIxfold (Dual (Endo (r -> r))) i s a -> (i -> a -> r -> r) -> r -> s -> r

Strict right fold over an indexed optic.

foldsl' :: AFold (Endo (Endo r)) s a -> (r -> a -> r) -> r -> s -> r

Strict left fold over an optic.

foldl' ≡ foldsl' folding

foldsl' :: Iso' s a        -> (c -> a -> c) -> c -> s -> c
foldsl' :: Lens' s a       -> (c -> a -> c) -> c -> s -> c
foldsl' :: View s a        -> (c -> a -> c) -> c -> s -> c
foldsl' :: Fold s a        -> (c -> a -> c) -> c -> s -> c
foldsl' :: Traversal' s a  -> (c -> a -> c) -> c -> s -> c
foldsl' :: Affine' s a -> (c -> a -> c) -> c -> s -> c

ifoldsl' :: Monoid i => AIxfold (Endo (r -> r)) i s a -> (i -> r -> a -> r) -> r -> s -> r

Strict left fold over an indexed optic.

foldsrM :: Monad m => AFold (Dual (Endo (r -> m r))) s a -> (a -> r -> m r) -> r -> s -> m r

Monadic right fold over an optic.

ifoldsrM :: Monoid i => Monad m => AIxfold (Dual (Endo (r -> m r))) i s a -> (i -> a -> r -> m r) -> r -> s -> m r

Monadic right fold over an indexed optic.

foldsrM ≡ ifoldrM . const

foldslM :: Monad m => AFold (Endo (r -> m r)) s a -> (r -> a -> m r) -> r -> s -> m r

Monadic left fold over an optic.

ifoldslM :: Monoid i => Monad m => AIxfold (Endo (r -> m r)) i s a -> (i -> r -> a -> m r) -> r -> s -> m r

Monadic left fold over an indexed optic.

foldslM ≡ ifoldslM . const

traverses_ :: Applicative f => AFold (Endo (f ())) s a -> (a -> f r) -> s -> f ()

Applicative fold over an optic.

>>> traverses_ both putStrLn ("hello","world")
hello
world

traverse_ ≡ traverses_ folded

itraverses_ :: Monoid i => Applicative f => AIxfold (Endo (f ())) i s a -> (i -> a -> f r) -> s -> f ()

Applicative fold over an indexed optic.

asums :: Alternative f => AFold (Endo (Endo (f a))) s (f a) -> s -> f a

The sum of a collection of actions, generalizing concats.

>>> asums both ("hello","world")
"helloworld"

>>> asums both (Nothing, Just "hello")
Just "hello"

asum ≡ asums folded

concats :: AFold [r] s a -> (a -> [r]) -> s -> [r]

Map a function over the foci of an optic and concatenate the resulting lists.

>>> concats both (\x -> [x, x + 1]) (1,3)
[1,2,3,4]

concatMap ≡ concats folded

iconcats :: Monoid i => AIxfold [r] i s a -> (i -> a -> [r]) -> s -> [r]

Concatenate the results of a function of the foci of an indexed optic.

concats o ≡ iconcats o . const

>>> iconcats itraversed (\i x -> [i + x, i + x + 1]) [1,2,3,4]
[1,2,3,4,5,6,7,8]

endo :: AFold (Endo (a -> a)) s (a -> a) -> s -> a -> a

TODO: Document

endoM :: Monad m => AFold (Endo (a -> m a)) s (a -> m a) -> s -> a -> m a

TODO: Document

finds :: AFold (Endo (Maybe a)) s a -> (a -> Bool) -> s -> Maybe a

Find the first focus of an optic that satisfies a predicate, if one exists.

>>> finds both even (1,4)
Just 4

>>> finds folded even [1,3,5,7]
Nothing

find ≡ finds folded

ifinds :: Monoid i => AIxfold (Endo (Maybe (i, a))) i s a -> (i -> a -> Bool) -> s -> Maybe (i, a)

Find the first focus of an indexed optic that satisfies a predicate, if one exists.

has :: AFold Any s a -> s -> Bool

Determine whether an optic has at least one focus.

hasnt :: AFold All s a -> s -> Bool

Determine whether an optic does not have a focus.

elem :: Eq a => AFold Any s a -> a -> s -> Bool

Determine whether the targets of a Fold contain a given element.

pelem :: Prd a => AFold Any s a -> a -> s -> Bool

Determine whether the foci of an optic contain an element equivalent to a given element.

joins :: Lattice a => AFold (Endo (Endo a)) s a -> a -> s -> a

Compute the join of the foci of an optic.

joins' :: Lattice a => Minimal a => AFold (Endo (Endo a)) s a -> s -> a

Compute the join of the foci of an optic including a least element.

meets :: Lattice a => AFold (Endo (Endo a)) s a -> a -> s -> a

Compute the meet of the foci of an optic .

meets' :: Lattice a => Maximal a => AFold (Endo (Endo a)) s a -> s -> a

Compute the meet of the foci of an optic including a greatest element.

min :: Ord a => AFold (Endo (Endo a)) s a -> a -> s -> a

Compute the minimum of the targets of a totally ordered fold.

max :: Ord a => AFold (Endo (Endo a)) s a -> a -> s -> a

Compute the maximum of the targets of a totally ordered fold.