The type signature of iso provides a nice interpretation of Iso. If you want to apply a function a -> b to a type s, you'd have to convert with s -> a, apply your function a -> b, and convert back with b -> t.

iso :: (s -> a) -> (b -> t) -> Iso s t a b
-- or, put monomorphically
iso :: (s -> a) -> (a -> s) -> Iso' s a

The type of monomorphic isomorphisms, i.e. isos that change neither the outer type s nor the inner type a.

Construct an Iso from two inverse functions.

Invert an Iso. Should you define any Isos, it's expected that they abide by the following law, essentially saying that inverting an Iso twice yields the same Iso you started with.

from (from l) ≡ l

Shorthand for over . from, e.g.

s & over (from l) f ≡ s & under l f

non lets you “relabel” a Maybe by equating Nothing to an arbitrary value (which you can choose):

>>> Just 1 ^. non 0 1

>>> Nothing ^. non 0 0

The most useful thing about non is that relabeling also works in other direction. If you try to set the “forbidden” value, it'll be turned to Nothing:

>>> Just 1 & non 0 .~ 0 Nothing

Setting anything else works just fine:

>>> Just 1 & non 0 .~ 5 Just 5

Same happens if you try to modify a value:

>>> Just 1 & non 0 %~ subtract 1 Nothing

>>> Just 1 & non 0 %~ (+ 1) Just 2

non is often useful when combined with at. For instance, if you have a map of songs and their playcounts, it makes sense not to store songs with 0 plays in the map; non can act as a filter that wouldn't pass such entries.

Decrease playcount of a song to 0, and it'll be gone:

>>> fromList [("Soon",1),("Yesterday",3)] & at "Soon" . non 0 %~ subtract 1
fromList [("Yesterday",3)]

Try to add a song with 0 plays, and it won't be added:

>>> fromList [("Yesterday",3)] & at "Soon" . non 0 .~ 0
fromList [("Yesterday",3)]

But it will be added if you set any other number:

>>> fromList [("Yesterday",3)] & at "Soon" . non 0 .~ 1
fromList [("Soon",1),("Yesterday",3)]

non is also useful when working with nested maps. Here a nested map is created when it's missing:

>>> Map.empty & at "Dez Mona" . non Map.empty . at "Soon" .~ Just 1
fromList [("Dez Mona",fromList [("Soon",1)])]

and here it is deleted when its last entry is deleted (notice that non is used twice here):

>>> fromList [("Dez Mona",fromList [("Soon",1)])] & at "Dez Mona" . non Map.empty . at "Soon" . non 0 %~ subtract 1
fromList []

To understand the last example better, observe the flow of values in it:

• the map goes into at "Dez Mona" * the nested map (wrapped into Just) goes into non Map.empty * Just is unwrapped and the nested map goes into at "Soon" * Just 1 is unwrapped by non 0

Then the final value – i.e. 1 – is modified by subtract 1 and the result (which is 0) starts flowing backwards:

• non 0 sees the 0 and produces a Nothing
• at "Soon" sees Nothing and deletes the corresponding value from the map
• the resulting empty map is passed to non Map.empty, which sees that it's empty and thus produces Nothing
• at "Dez Mona" sees Nothing and removes the key from the map

non, but instead of equality with a value, non' equates Nothing to anything a Prism of your choice doesn't match.

>>> Just [] & non' _Empty .~ [1,2,3]
Just [1,2,3]
>>> Just [] & non' _Empty .~ []
Nothing

See non for cases this may be useful.

Lawful instances of Show and Read give rise to this isomorphism.

>>> 123 & from _Show %~ reverse
321
>>> "123" & _Show %~ (*2)
"246"

enum is a questionable inclusion, as many (most) Enum instances throw errors for out-of-bounds integers, but it is occasionally useful when used with that information in mind. Handle with care!

>>> 97 ^. enum :: Char
'a'
>>> (-1) ^. enum :: Char
*** Exception: Prelude.chr: bad argument: (-1)
>>> [True,False] ^. mapping (from enum)
[1,0]

Coercible types have the same runtime representation, i.e. they are isomorphic.

>>> (Sum 123 :: Sum Int) ^. coerced :: Int
123

An isomorphism holds when lifted into a functor. For example, if a list contains a bunch of a's which are each isomorphic to a b, the whole list of a's is isomorphic to a list of b's.

>>> ["1","2","3"] ^. mapping _Show :: [Int]
[1,2,3]
>>> ([1,2,3] :: [Int]) ^. from (mapping _Show)
["1","2","3"]

This also hold across different functors:

>>> let l = mapping @[] @Maybe _Show
>>> :t l
l :: (Read b, Show b) => Iso [String] (Maybe String) [b] (Maybe b)
>>> ["1","2","3"] & l %~ Just . sum
Just "6"

packed lets you convert between String and Text (strict or lazy). It can be used as a replacement for pack or as a way to modify some String if you have a function like Text -> Text.

unpacked is like packed but works in the opposite direction.

This type is used for efficient "deconstruction" of an Iso, reifying the type into a concrete pair of inverse functions. From the user's perspective, a function with an AnIso as an argument is simply expecting a normal Iso.

Monomorphic AnIso.

Convert AnIso to Iso. This is useful when you need to store an isomorphism as a data type inside a container and later reconstitute it as an overloaded function.

Extract the two functions, s -> a and one b -> t that characterize an Iso.

• s is the type of the whole structure
• t is the type of the reconstructed structure
• a is the type of the target
• b is the type of the value used for reconstruction

The type of monomorphic prisms, i.e. prisms that change neither the outer type s nor the inner type a.

Generate a Prism out of a constructor and a selector. You may wonder why the selector function returns an 'Either t a' rather than the more obvious choice of 'Maybe a'; This is to allow s and t to differ — see prism'.

_Left = prism Left $ either Right (Left . Right)

Generate a Prism out of a constructor and a selector.

_Nothing = prism Left $ either Right (Left . Right)

nearly a p is a prism that matches "loose equality" with a by assuming p x is true iff x ≡ a.

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

A prism that matches equality with a value:

>>> 1 ^? only 2
Nothing
>>> 1 ^? only 1
Just 1

Focus the Left component of an Either

>>> Left "doge" ^? _Left
Just "doge"
>>> Right "soge" ^? _Left
Nothing
>>> review _Left "quoge"
Left "quoge"

Focus the Right component of an Either

>>> Left "doge" ^? _Right
Nothing
>>> Right "soge" ^? _Right
Just "soge"
>>> review _Right "quoge"
Right "quoge"

Focus the Just of a Maybe. This might seem redundant, as:

>>> Just "pikyben" ^? _Just
Just "pikyben"

but _Just proves useful when composing with other optics.

_Nothing focuses the Nothing in a Maybe.

>>> Nothing ^? _Nothing
Just ()
>>> Just "wassa" ^? _Nothing
Nothing
>>> 'has' _Nothing (Just "something")
False

A prism that matches the empty structure.

>>> has _Empty []
True

This type is used for effecient "deconstruction" of a Prism. From the user's perspective, a function with an AnPrism as an argument is simply expecting a normal Prism.

Monomorphic APrism.

Clone a Prism so that you can reuse the same monomorphically typed Prism for different purposes.

Cloning a Prism is one way to make sure you aren't given something weaker, such as a Traversal and can be used as a way to pass around lenses that have to be monomorphic in f.

Convert a Prism into the constructor and selector that characterise it. See: prism.

If you see this in a signature for a function, the function is expecting a Review. This usually means a Prism or an Iso.

Review, from lens, is limited form of Prism that can only be used for re operations.

Similarly to SimpleGetter from microlens, microlens-pro does not define Review and opts for a less general SimpleReview in order to avoid a distributive dependency.

Reverse a Prism or Iso turning it into a getter. re is a weaker version of from, in that you can't flip it back around after reversing it the first time.

>>> "hello worms" ^. re _Just
Just "hello worms"

Reverse a Prism or Iso and view it

review ≡ view . re

>>> review _Just "sploink"
Just "sploink"

review is often used with the function monad, ((->)r):

review :: AReview t b -> b -> t

An infix synonym of review

Construct a Review out of a constructor. Consider this more pleasant type signature:

unto :: (b -> t) -> Review' t b

Pardon the actual type signature — microlens defines neither Optic (used in lens' unto) nor Review'. Here we simply expand the definition of Optic.