Optics.Extra

At provides a Lens that can be used to read, write or delete the value associated with a key in a Map-like container on an ad hoc basis.

An instance of At should satisfy:

ix k ≡ at k % _Just

This class provides a way to attach or detach elements on the left side of a structure in a flexible manner.

Extract each element of a (potentially monomorphic) container.

>>> over each (*10) (1,2,3)(10,20,30)

>>> iover each (\i a -> a*10 + succ i) (1,2,3)(11,22,33)

Pattern synonym for matching on any type with an AsEmpty instance.

>>> case Nothing of { Empty -> True; _ -> False }True

Type family that takes a key-value container type and returns the type of keys (indices) into the container, for example Index (Map k a) ~ k. This is shared by Ixed, At and Contains.

Type family that takes a key-value container type and returns the type of values stored in the container, for example IxValue (Map k a) ~ a. This is shared by both Ixed and At.

Provides a simple AffineTraversal lets you traverse the value at a given key in a Map or element at an ordinal position in a list or Seq.

A definition of ix for types with an At instance. This is the default if you don't specify a definition for ix.

Version of at strict in the value inside the Just constructor.

Example:

>>> (at () .~ Just (error "oops") $ Nothing) `seq` ()()

>>> (at' () .~ Just (error "oops") $ Nothing) `seq` ()*** Exception: oops...

>>> view (at ()) (Just $ error "oops") `seq` ()()

>>> view (at' ()) (Just $ error "oops") `seq` ()*** Exception: oops...

It also works as expected for other data structures:

>>> (at 1 .~ Just (error "oops") $ Map.empty) `seq` ()()

>>> (at' 1 .~ Just (error "oops") $ Map.empty) `seq` ()*** Exception: oops...

Delete the value associated with a key in a Map-like container

sans k = at k .~ Nothing

This class provides a simple Lens that lets you view (and modify) information about whether or not a container contains a given Index. Instances are provided for Set-like containers only.

cons an element onto a container.

This is an infix alias for cons.

>>> 1 <| [][1]

>>> 'a' <| "bc""abc"

>>> 1 <| [][1]

>>> 1 <| [2, 3][1,2,3]

cons an element onto a container.

>>> cons 'a' """a"

>>> cons 'a' "bc""abc"

Attempt to extract the left-most element from a container, and a version of the container without that element.

>>> uncons []Nothing

>>> uncons [1, 2, 3]Just (1,[2,3])

An AffineTraversal reading and writing to the head of a non-empty container.

>>> "abc" ^? _headJust 'a'

>>> "abc" & _head .~ 'd'"dbc"

>>> [1,2,3] & _head %~ (*10)[10,2,3]

>>> [] & _head %~ absurd[]

>>> [1,2,3] ^? _headJust 1

>>> [] ^? _headNothing

>>> [1,2] ^? _headJust 1

>>> [] & _head .~ 1[]

>>> [0] & _head .~ 2[2]

>>> [0,1] & _head .~ 2[2,1]

An AffineTraversal reading and writing to the tail of a non-empty container.

>>> "ab" & _tail .~ "cde""acde"

>>> [] & _tail .~ [1,2][]

>>> [1,2,3,4,5] & _tail % traversed %~ (*10)[1,20,30,40,50]

>>> [1,2] & _tail .~ [3,4,5][1,3,4,5]

>>> [] & _tail .~ [1,2][]

>>> "abc" ^? _tailJust "bc"

>>> "hello" ^? _tailJust "ello"

>>> "" ^? _tailNothing

Pattern synonym for matching on the leftmost element of a structure.

>>> case ['a','b','c'] of (x :< _) -> x'a'

This class provides a way to attach or detach elements on the right side of a structure in a flexible manner.

snoc an element onto the end of a container.

This is an infix alias for snoc.

>>> "" |> 'a'"a"

>>> "bc" |> 'a'"bca"

snoc an element onto the end of a container.

>>> snoc "hello" '!'"hello!"

Attempt to extract the right-most element from a container, and a version of the container without that element.

>>> unsnoc "hello!"Just ("hello",'!')

>>> unsnoc ""Nothing

An AffineTraversal reading and replacing all but the a last element of a non-empty container.

>>> "abcd" ^? _initJust "abc"

>>> "" ^? _initNothing

>>> "ab" & _init .~ "cde""cdeb"

>>> [] & _init .~ [1,2][]

>>> [1,2,3,4] & _init % traversed %~ (*10)[10,20,30,4]

>>> [1,2,3] ^? _initJust [1,2]

>>> "hello" ^? _initJust "hell"

>>> [] ^? _initNothing

An AffineTraversal reading and writing to the last element of a non-empty container.

>>> "abc" ^? _lastJust 'c'

>>> "" ^? _lastNothing

>>> [1,2,3] & _last %~ (+1)[1,2,4]

>>> [1,2] ^? _lastJust 2

>>> [] & _last .~ 1[]

>>> [0] & _last .~ 2[2]

>>> [0,1] & _last .~ 2[0,2]

Pattern synonym for matching on the rightmost element of a structure.

>>> case ['a','b','c'] of (_ :> x) -> x'c'

Class for types that may be _Empty.

Class for optic kinds that can have indices.

Construct a conjoined indexed optic that provides a separate code path when used without indices. Useful for defining indexed optics that are as efficient as their unindexed equivalents when used without indices.

Note: conjoined f g is well-defined if and only if f ≡ noIx g.

Compose two indexed optics. Their indices are composed as a pair.

>>> itoListOf (ifolded <%> ifolded) ["foo", "bar"][((0,0),'f'),((0,1),'o'),((0,2),'o'),((1,0),'b'),((1,1),'a'),((1,2),'r')]

Compose two indexed optics and drop indices of the left one. (If you want to compose a non-indexed and an indexed optic, you can just use (%).)

>>> itoListOf (ifolded %> ifolded) ["foo", "bar"][(0,'f'),(1,'o'),(2,'o'),(0,'b'),(1,'a'),(2,'r')]

Compose two indexed optics and drop indices of the right one. (If you want to compose an indexed and a non-indexed optic, you can just use (%).)

>>> itoListOf (ifolded <% ifolded) ["foo", "bar"][(0,'f'),(0,'o'),(0,'o'),(1,'b'),(1,'a'),(1,'r')]

Remap the index.

>>> itoListOf (reindexed succ ifolded) "foo"[(1,'f'),(2,'o'),(3,'o')]

>>> itoListOf (ifolded %& reindexed succ) "foo"[(1,'f'),(2,'o'),(3,'o')]

Flatten indices obtained from two indexed optics.

>>> itoListOf (ifolded % ifolded %& icompose (,)) ["foo","bar"][((0,0),'f'),((0,1),'o'),((0,2),'o'),((1,0),'b'),((1,1),'a'),((1,2),'r')]

Flatten indices obtained from three indexed optics.

>>> itoListOf (ifolded % ifolded % ifolded %& icompose3 (,,)) [["foo","bar"],["xyz"]][((0,0,0),'f'),((0,0,1),'o'),((0,0,2),'o'),((0,1,0),'b'),((0,1,1),'a'),((0,1,2),'r'),((1,0,0),'x'),((1,0,1),'y'),((1,0,2),'z')]

Flatten indices obtained from four indexed optics.

Flatten indices obtained from five indexed optics.

Flatten indices obtained from arbitrary number of indexed optics.

Type synonym for an indexed affine fold.

Type synonym for a type-modifying indexed affine traversal.

Type synonym for an indexed fold.

Type synonym for an indexed getter.

Type synonym for a type-modifying indexed lens.

Type synonym for a type-modifying indexed setter.

Type synonym for a type-modifying indexed traversal.

A Functor with an additional index.

Instances must satisfy a modified form of the Functor laws:

imap f . imap g ≡ imap (\i -> f i . g i)
imap (\_ a -> a) ≡ id

A container that supports folding with an additional index.

Traverse elements with access to the index i, discarding the results.

When you don't need access to the index then traverse_ is more flexible in what it accepts.

traverse_ l = itraverse . const

Traverse elements with access to the index i, discarding the results (with the arguments flipped).

ifor_ ≡ flip itraverse_

When you don't need access to the index then for_ is more flexible in what it accepts.

for_ a ≡ ifor_ a . const

Extract the key-value pairs from a structure.

When you don't need access to the indices in the result, then toList is more flexible in what it accepts.

toList ≡ map snd . itoList

A Traversable with an additional index.

An instance must satisfy a (modified) form of the Traversable laws:

itraverse (const Identity) ≡ Identity
fmap (itraverse f) . itraverse g ≡ getCompose . itraverse (\i -> Compose . fmap (f i) . g i)

Traverse with an index (and the arguments flipped).

for a ≡ ifor a . const
ifor ≡ flip itraverse

Subtyping relationship between kinds of optics.

An instance of Is k l means that any Optic k can be used as an Optic l. For example, we have an Is A_Lens A_Traversal instance, but not Is A_Traversal A_Lens.

This class needs instances for all possible combinations of tags.

Tag for a traversal.

Wrapper newtype for the whole family of optics.

The first parameter k identifies the particular optic kind (e.g. A_Lens or A_Traversal).

The parameter is is a list of types available as indices. This will typically be NoIx for unindexed optics, or WithIx for optics with a single index. See the "Indexed optics" section of the overview documentation in the Optics module of the main optics package for more details.

The parameters s and t represent the "big" structure, whereas a and b represent the "small" structure.

Type synonym for a type-modifying affine traversal.

Type synonym for a type-modifying lens.

Type synonym for a type-modifying prism.

Type synonym for a type-modifying traversal.

Type synonym for a fold.

Type synonym for a type-modifying setter.

Type synonym for a type-preserving iso.

Build an iso from a pair of inverse functions.

If you want to build an Iso from the van Laarhoven representation, use isoVL from the optics-vl package.

Class for optics that can be reversed.

Type synonym for a type-preserving indexed traversal.

Type synonym for a type-preserving prism.

This is usually used to build a Prism', when you have to use an operation like cast which already returns a Maybe.

Retrieve the value targeted by an AffineFold.

>>> let _Right = prism Right $ either (Left . Left) Right

>>> preview _Right (Right 'x')Just 'x'

>>> preview _Right (Left 'y')Nothing

A Prism that matches on the Right constructor of Either.

View the value pointed to by a getter.

If you want to view a type-modifying optic that is insufficiently polymorphic to be type-preserving, use getting.

Retrieve the value targeted by a Review.

>>> review _Left "hi"Left "hi"

Build a lens from the van Laarhoven representation.

Flipped version of <$>.

(<&>) = flip fmap

Examples

Apply (+1) to a list, a Just and a Right:

>>> Just 2 <&> (+1)Just 3

>>> [1,2,3] <&> (+1)[2,3,4]

>>> Right 3 <&> (+1)Right 4

Build a setter from a function to modify the element(s), which must respect the well-formedness laws.

This Prism compares for approximate equality with a given value and a predicate for testing, an example where the value is the empty list and the predicate checks that a list is empty (same as _Empty with the AsEmpty list instance):

>>> nearly [] null # ()[]>>> [1,2,3,4] ^? nearly [] nullNothing

nearly [] null :: Prism' [a] ()

To comply with the Prism laws the arguments you supply to nearly a p are somewhat constrained.

We assume p x holds iff x ≡ a. Under that assumption then this is a valid Prism.

This is useful when working with a type where you can test equality for only a subset of its values, and the prism selects such a value.

Tag for a fold.

Common special case of Optic where source and target types are equal.

Here, we need only one "big" and one "small" type. For lenses, this means that in the restricted form we cannot do type-changing updates.

Fold via embedding into a monoid.

Build an affine traversal from the van Laarhoven representation.

Example:

>>> :{azSnd = atraversalVL $ \point f ab@(a, b) ->  if a >= 'a' && a <= 'z'  then (a, ) <$> f b  else point ab:}

>>> preview azSnd ('a', "Hi")Just "Hi"

>>> preview azSnd ('@', "Hi")Nothing

>>> over azSnd (++ "!!!") ('f', "Hi")('f',"Hi!!!")

>>> set azSnd "Bye" ('Y', "Hi")('Y',"Hi")

Generate sensible error messages in case a user tries to pass either an unindexed optic or indexed optic with unflattened indices where indexed optic with a single index is expected.

Compose two optics of compatible flavours.

Returns an optic of the appropriate supertype. If either or both optics are indexed, the composition preserves all the indices.

Fold with index via embedding into a monoid.

Tag for a lens.