Copyright	(C) 2026 - Eitan Chatav
License	BSD-style (see the file LICENSE)
Maintainer	Eitan Chatav <eitan.chatav@gmail.com>
Stability	provisional
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Control.Lens.PartialIso

Contents

PartialIso
Combinators
Applicators
Patterns
Iterators
Template Haskell
Re-exports

Description

See Rendel & Ostermann, Invertible syntax descriptions

Synopsis

dimapMaybe :: (Choice p, Cochoice p) => (s -> Maybe a) -> (b -> Maybe t) -> p a b -> p s t
type PartialIso s t a b = forall (p :: Type -> Type -> Type) (f :: Type -> Type). (Choice p, Cochoice p, Applicative f, Filterable f) => p a (f b) -> p s (f t)
type PartialIso' s a = PartialIso s s a a
type APartialIso s t a b = PartialExchange a b a (Maybe b) -> PartialExchange a b s (Maybe t)
data PartialExchange a b s t = PartialExchange (s -> Maybe a) (b -> Maybe t)
partialIso :: (s -> Maybe a) -> (b -> Maybe t) -> PartialIso s t a b
partialInvoluted :: (a -> Maybe a) -> PartialIso' a a
withPartialIso :: APartialIso s t a b -> ((s -> Maybe a) -> (b -> Maybe t) -> r) -> r
clonePartialIso :: APartialIso s t a b -> PartialIso s t a b
coPartialIso :: APartialIso b a t s -> PartialIso s t a b
crossPartialIso :: APartialIso s t a b -> APartialIso u v c d -> PartialIso (s, u) (t, v) (a, c) (b, d)
altPartialIso :: APartialIso s t a b -> APartialIso u v c d -> PartialIso (Either s u) (Either t v) (Either a c) (Either b d)
(>?) :: Choice p => APrism s t a b -> p a b -> p s t
(?<) :: Cochoice p => APrism b a t s -> p a b -> p s t
(>?<) :: (Choice p, Cochoice p) => APartialIso s t a b -> p a b -> p s t
(>~) :: Profunctor p => AnIso s t a b -> p a b -> p s t
(~<) :: Profunctor p => AnIso b a t s -> p a b -> p s t
coPrism :: (Profunctor p, Filterable f) => APrism b a t s -> p a (f b) -> p s (f t)
satisfied :: (a -> Bool) -> PartialIso' a a
nulled :: (AsEmpty s, AsEmpty t) => PartialIso s t () ()
notNulled :: (AsEmpty s, AsEmpty t) => PartialIso s t s t
eotMaybe :: forall a b p f. (Profunctor p, Functor f) => p (Either a ()) (f (Either b ())) -> p (Maybe a) (f (Maybe b))
eotList :: (Cons s s a a, AsEmpty t, Cons t t b b) => Iso s t (Either (a, s) ()) (Either (b, t) ())
iterating :: APartialIso a b a b -> Iso a b a b
difoldl1 :: Cons s t a b => APartialIso d c (d, b) (c, a) -> Iso (d, t) (c, s) (d, t) (c, s)
difoldr1 :: Cons s t a b => APartialIso d c (b, d) (a, c) -> Iso (t, d) (s, c) (t, d) (s, c)
difoldl :: (AsEmpty t, Cons s t a b) => APartialIso d c (d, b) (c, a) -> Prism d c (d, t) (c, s)
difoldr :: (AsEmpty t, Cons s t a b) => APartialIso d c (b, d) (a, c) -> Prism d c (t, d) (s, c)
makeNestedPrisms :: Name -> DecsQ
module Control.Lens.Iso
module Control.Lens.Prism

PartialIso

dimapMaybe :: (Choice p, Cochoice p) => (s -> Maybe a) -> (b -> Maybe t) -> p a b -> p s t Source #

The dimapMaybe function endows Choice & Cochoice "partial profunctors" with an action >?< of PartialIsos.

type PartialIso s t a b = forall (p :: Type -> Type -> Type) (f :: Type -> Type). (Choice p, Cochoice p, Applicative f, Filterable f) => p a (f b) -> p s (f t) Source #

PartialIso is a first class inexhaustive pattern, similar to how Prism is a first class exhaustive pattern, by combining Prisms and coPrisms.

Every Iso & Prism is APartialIso.

PartialIsos are isomorphic to PartialExchanges.

type PartialIso' s a = PartialIso s s a a Source #

A simple PartialIso' s a is an identification of a subset of s with a subset of a.

Given a simple PartialIso', partialIso f g, has properties:

Just = f <=< g

Just = g <=< f

These are left and right inverse laws for proper PartialIso's. However, sometimes an improper PartialIso' will be useful. For an improper PartialIso', only the left inverse law holds.

Just = f <=< g

For an improper PartialIso', norm = g <=< f is an idempotent

norm = norm <=< norm

and can be regarded as a normalization within some equivalence class of terms.

type APartialIso s t a b = PartialExchange a b a (Maybe b) -> PartialExchange a b s (Maybe t) Source #

APartialIso is monomorphically a PartialIso.

data PartialExchange a b s t Source #

A PartialExchange provides efficient access to the two functions that make up a PartialIso.

Constructors

PartialExchange (s -> Maybe a) (b -> Maybe t)

Instances

Instances details

Filtrator (PartialExchange a b) Source #
Instance details Defined in Data.Profunctor.Filtrator Methods filtrate :: PartialExchange a b (Either a0 c) (Either b0 d) -> (PartialExchange a b a0 b0, PartialExchange a b c d) Source #
Choice (PartialExchange a b) Source #
Instance details Defined in Control.Lens.PartialIso Methods left' :: PartialExchange a b a0 b0 -> PartialExchange a b (Either a0 c) (Either b0 c) # right' :: PartialExchange a b a0 b0 -> PartialExchange a b (Either c a0) (Either c b0) #
Cochoice (PartialExchange a b) Source #
Instance details Defined in Control.Lens.PartialIso Methods unleft :: PartialExchange a b (Either a0 d) (Either b0 d) -> PartialExchange a b a0 b0 # unright :: PartialExchange a b (Either d a0) (Either d b0) -> PartialExchange a b a0 b0 #
Profunctor (PartialExchange a b) Source #
Instance details Defined in Control.Lens.PartialIso Methods dimap :: (a0 -> b0) -> (c -> d) -> PartialExchange a b b0 c -> PartialExchange a b a0 d # lmap :: (a0 -> b0) -> PartialExchange a b b0 c -> PartialExchange a b a0 c # rmap :: (b0 -> c) -> PartialExchange a b a0 b0 -> PartialExchange a b a0 c # (#.) :: forall a0 b0 c q. Coercible c b0 => q b0 c -> PartialExchange a b a0 b0 -> PartialExchange a b a0 c # (.#) :: forall a0 b0 c q. Coercible b0 a0 => PartialExchange a b b0 c -> q a0 b0 -> PartialExchange a b a0 c #
Functor (PartialExchange a b s) Source #
Instance details Defined in Control.Lens.PartialIso Methods fmap :: (a0 -> b0) -> PartialExchange a b s a0 -> PartialExchange a b s b0 # (<$) :: a0 -> PartialExchange a b s b0 -> PartialExchange a b s a0 #
Filterable (PartialExchange a b s) Source #
Instance details Defined in Control.Lens.PartialIso Methods mapMaybe :: (a0 -> Maybe b0) -> PartialExchange a b s a0 -> PartialExchange a b s b0 # catMaybes :: PartialExchange a b s (Maybe a0) -> PartialExchange a b s a0 # filter :: (a0 -> Bool) -> PartialExchange a b s a0 -> PartialExchange a b s a0 # drain :: PartialExchange a b s a0 -> PartialExchange a b s b0 #

Combinators

partialIso :: (s -> Maybe a) -> (b -> Maybe t) -> PartialIso s t a b Source #

Build a PartialIso.

partialInvoluted :: (a -> Maybe a) -> PartialIso' a a Source #

Given a partial function that is its own inverse, this gives you a PartialIso' using it in both directions.

withPartialIso :: APartialIso s t a b -> ((s -> Maybe a) -> (b -> Maybe t) -> r) -> r Source #

Convert APartialIso to the pair of functions that characterize it.

clonePartialIso :: APartialIso s t a b -> PartialIso s t a b Source #

Clone APartialIso so that you can reuse the same monomorphically typed partial isomorphism for different purposes.

coPartialIso :: APartialIso b a t s -> PartialIso s t a b Source #

Clone and invert APartialIso.

crossPartialIso :: APartialIso s t a b -> APartialIso u v c d -> PartialIso (s, u) (t, v) (a, c) (b, d) Source #

Construct a PartialIso on pairs from components.

altPartialIso :: APartialIso s t a b -> APartialIso u v c d -> PartialIso (Either s u) (Either t v) (Either a c) (Either b d) Source #

Construct a PartialIso on Eithers from components.

Applicators

(>?) :: Choice p => APrism s t a b -> p a b -> p s t infixl 4 Source #

Action of APrism on Choice Profunctors.

(?<) :: Cochoice p => APrism b a t s -> p a b -> p s t infixl 4 Source #

Action of a coPrism on Cochoice Profunctors.

(>?<) :: (Choice p, Cochoice p) => APartialIso s t a b -> p a b -> p s t infixl 4 Source #

Action of APartialIso on Choice & Cochoice partial profunctors.

(>~) :: Profunctor p => AnIso s t a b -> p a b -> p s t infixl 2 Source #

Action of AnIso on Profunctors.

(~<) :: Profunctor p => AnIso b a t s -> p a b -> p s t infixl 2 Source #

Inverse action of AnIso on Profunctors.

coPrism :: (Profunctor p, Filterable f) => APrism b a t s -> p a (f b) -> p s (f t) Source #

Action of a coPrism on the composition of a Profunctor and Filterable.

Patterns

satisfied :: (a -> Bool) -> PartialIso' a a Source #

satisfied is the prototypical proper partial isomorphism, identifying a subset which satisfies a predicate.

nulled :: (AsEmpty s, AsEmpty t) => PartialIso s t () () Source #

nulled matches an Empty pattern, like _Empty.

notNulled :: (AsEmpty s, AsEmpty t) => PartialIso s t s t Source #

notNulled matches a non-Empty pattern.

eotMaybe :: forall a b p f. (Profunctor p, Functor f) => p (Either a ()) (f (Either b ())) -> p (Maybe a) (f (Maybe b)) Source #

The either-of-tuples representation of Maybe.

eotList :: (Cons s s a a, AsEmpty t, Cons t t b b) => Iso s t (Either (a, s) ()) (Either (b, t) ()) Source #

The either-of-tuples representation of list-like streams.

Iterators

iterating :: APartialIso a b a b -> Iso a b a b Source #

Iterate the application of a partial isomorphism, useful for constructing fold/unfold isomorphisms.

difoldl1 :: Cons s t a b => APartialIso d c (d, b) (c, a) -> Iso (d, t) (c, s) (d, t) (c, s) Source #

Left fold & unfold APartialIso to an Iso.

difoldr1 :: Cons s t a b => APartialIso d c (b, d) (a, c) -> Iso (t, d) (s, c) (t, d) (s, c) Source #

Right fold & unfold APartialIso to an Iso.

difoldl :: (AsEmpty t, Cons s t a b) => APartialIso d c (d, b) (c, a) -> Prism d c (d, t) (c, s) Source #

Left fold & unfold APartialIso to a Prism.

difoldr :: (AsEmpty t, Cons s t a b) => APartialIso d c (b, d) (a, c) -> Prism d c (t, d) (s, c) Source #

Right fold & unfold APartialIso to a Prism.

Template Haskell

makeNestedPrisms :: Name -> DecsQ Source #

Similar to makePrisms, makeNestedPrisms generates a Prism for each constructor of a data type. Isos are generated when possible. Reviews are generated for constructors with existentially quantified constructors and GADTs. The difference in makeNestedPrisms is that constructors with n > 2 arguments will use right-nested pairs, rather than a flat n-tuple. This makes them suitable for pattern bonding, by use of the applicator >? to Monoidal idiom notation with >*<, or to Monadic qualified do-notation.

e.g.

data FooBar a
  = Foo a
  | Bar Int
  | Baz Int Char
  | Buzz Double String Bool
  | Boop
makeNestedPrisms ''FooBar

will create

_Foo :: Prism (FooBar a) (FooBar b) a b
_Bar :: Prism' (FooBar a) Int
_Baz :: Prism' (FooBar a) (Int, Char)
_Buzz :: Prism' (FooBar a) (Double, (String, Bool))
_Boop :: Prism' (FooBar a) ()

Re-exports

module Control.Lens.Iso

module Control.Lens.Prism