Portability | Rank2Types |
---|---|

Stability | provisional |

Maintainer | Edward Kmett <ekmett@gmail.com> |

Safe Haskell | Trustworthy |

- type Iso s t a b = forall k f. (Isomorphic k, Functor f) => k (a -> f b) (s -> f t)
- type AnIso s t a b = Overloaded Isoid Mutator s t a b
- class Category k => Isomorphic k where
- data Isoid ab st where
- from :: AnIso s t a b -> Iso b a t s
- cloneIso :: AnIso s t a b -> Iso s t a b
- au :: AnIso s t a b -> ((s -> a) -> e -> b) -> e -> t
- auf :: AnIso s t a b -> ((r -> a) -> e -> b) -> (r -> s) -> e -> t
- under :: AnIso s t a b -> (t -> s) -> b -> a
- mapping :: Functor f => AnIso s t a b -> Iso (f s) (f t) (f a) (f b)
- simple :: Simple Iso a a
- non :: Eq a => a -> Simple Iso (Maybe a) a
- anon :: a -> (a -> Bool) -> Simple Iso (Maybe a) a
- enum :: Enum a => Simple Iso Int a
- curried :: Iso ((a, b) -> c) ((d, e) -> f) (a -> b -> c) (d -> e -> f)
- uncurried :: Iso (a -> b -> c) (d -> e -> f) ((a, b) -> c) ((d, e) -> f)
- class Strict s t a b | s -> a, a -> s, b -> t, t -> b, s b -> a t, a t -> s b where
- type SimpleIso s a = Iso s s a a
- type family CoA x :: *
- type family CoB x :: *

# Isomorphism Lenses

type Iso s t a b = forall k f. (Isomorphic k, Functor f) => k (a -> f b) (s -> f t)Source

type AnIso s t a b = Overloaded Isoid Mutator s t a bSource

When you see this as an argument to a function, it expects an `Iso`

.

# Isomorphism Construction

class Category k => Isomorphic k whereSource

Used to provide overloading of isomorphism application

An instance of `Isomorphic`

is a `Category`

with a canonical mapping to it from the
category of isomorphisms over Haskell types.

Reify all of the information given to you by being `Isomorphic`

.

# Consuming Isomorphisms

cloneIso :: AnIso s t a b -> Iso s t a bSource

Convert from an `Isomorphism`

back to any `Isomorphic`

value.

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.

See `cloneLens`

or `cloneTraversal`

for more information on why you might want to do this.

# Working with isomorphisms

auf :: AnIso s t a b -> ((r -> a) -> e -> b) -> (r -> s) -> e -> tSource

Based on `ala'`

from Conor McBride's work on Epigram.

This version is generalized to accept any `Iso`

, not just a `newtype`

.

For a version you pass the name of the `newtype`

constructor to, see `alaf`

.

Mnemonically, the German *auf* plays a similar role to *à la*, and the combinator
is `au`

with an extra function argument.

`>>>`

10`auf (wrapping Sum) (foldMapOf both) Prelude.length ("hello","world")`

mapping :: Functor f => AnIso s t a b -> Iso (f s) (f t) (f a) (f b)Source

This can be used to lift any `SimpleIso`

into an arbitrary functor.

## Common Isomorphisms

non :: Eq a => a -> Simple Iso (Maybe a) aSource

If `v`

is an element of a type `a`

, and `a'`

is `a`

sans the element `v`

, then `non v`

is an isomorphism from
`Maybe a'`

to `a`

.

Keep in mind this is only a real isomorphism if you treat the domain as being `Maybe`

(a sans v)

This is practically quite useful when you want to have a map where all the entries should have non-zero values.

`>>>`

fromList [("hello",3)]`Map.fromList [("hello",1)] & at "hello" . non 0 +~ 2`

`>>>`

fromList []`Map.fromList [("hello",1)] & at "hello" . non 0 -~ 1`

`>>>`

1`Map.fromList [("hello",1)] ^. at "hello" . non 0`

`>>>`

0`Map.fromList [] ^. at "hello" . non 0`

This combinator is also particularly useful when working with nested maps.

*e.g.* When you want to create the nested map when it is missing:

`>>>`

fromList [("hello",fromList [("world","!!!")])]`Map.empty & at "hello" . non Map.empty . at "world" ?~ "!!!"`

and when have deleting the last entry from the nested map mean that we should delete its entry from the surrounding one:

`>>>`

fromList []`fromList [("hello",fromList [("world","!!!")])] & at "hello" . non Map.empty . at "world" .~ Nothing`

anon :: a -> (a -> Bool) -> Simple Iso (Maybe a) aSource

generalizes `anon`

a p

to take any value and a predicate.
`non`

a

This function assumes that `p a`

holds `True`

and generates an isomorphism between

and `Maybe`

(a | not (p a))`a`

`>>>`

fromList [("hello",fromList [("world","!!!")])]`Map.empty & at "hello" . anon Map.empty Map.null . at "world" ?~ "!!!"`

`>>>`

fromList []`fromList [("hello",fromList [("world","!!!")])] & at "hello" . anon Map.empty Map.null . at "world" .~ Nothing`

enum :: Enum a => Simple Iso Int aSource

This isomorphism can be used to convert to or from an instance of `Enum`

.

`>>>`

0`LT^.from enum`

`>>>`

'a'`97^.enum :: Char`

Note: this is only an isomorphism from the numeric range actually used
and it is a bit of a pleasant fiction, since there are questionable
`Enum`

instances for `Double`

, and `Float`

that exist solely for
`[1.0 .. 4.0]`

sugar and the instances for those and `Integer`

don't
cover all values in their range.

class Strict s t a b | s -> a, a -> s, b -> t, t -> b, s b -> a t, a t -> s b whereSource

Ad hoc conversion between "strict" and "lazy" versions of a structure,
such as `Text`

or `ByteString`

.