optics-core-0.3.0.1: Optics as an abstract interface: core definitions

Safe HaskellNone
LanguageHaskell2010

Optics.Optic

Contents

Description

This module provides core definitions:

  • an opaque Optic type, which is parameterised over a type representing an optic kind (instantiated with tag types such as A_Lens);
  • the optic composition operator (%);
  • the subtyping relation Is with an accompanying castOptic function to convert an optic kind;
  • the Join operation used to find the optic kind resulting from a composition.

Each optic kind is identified by a "tag type" (such as A_Lens), which is an empty data type. The type of the actual optics (such as Lens) is obtained by applying Optic to the tag type.

See the Optics module in the main optics package for overview documentation.

Synopsis

Documentation

type OpticKind = Type Source #

Kind for types used as optic tags, such as A_Lens.

Since: 0.2

data Optic (k :: OpticKind) (is :: IxList) s t a b Source #

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.

Instances
(LabelOptic name k s t a b, is ~ NoIx) => IsLabel name (Optic k is s t a b) Source # 
Instance details

Defined in Optics.Internal.Optic

Methods

fromLabel :: Optic k is s t a b #

type Optic' k is s a = Optic k is s s a a Source #

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.

Subtyping

castOptic :: forall destKind srcKind is s t a b. Is srcKind destKind => Optic srcKind is s t a b -> Optic destKind is s t a b Source #

Explicit cast from one optic flavour to another.

The resulting optic kind is given in the first type argument, so you can use TypeApplications to set it. For example

 castOptic @A_Lens o

turns o into a Lens.

This is the identity function, modulo some constraint jiggery-pokery.

class Is k l Source #

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.

Minimal complete definition

implies

Instances
(TypeError ((((ShowType k :<>: Text " cannot be used as ") :<>: ShowType l) :$$: Text "Perhaps you meant one of these:") :$$: ShowEliminations (EliminationForms k)) :: Constraint) => Is k l Source #

Overlappable instance for a custom type error.

Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints k p -> r) -> Constraints l p -> r Source #

Is k k Source #

Every kind of optic can be used as itself.

Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints k p -> r) -> Constraints k p -> r Source #

Is A_ReversedLens A_Review Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_AffineFold A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Getter A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints A_Getter p -> r) -> Constraints A_Fold p -> r Source #

Is A_Getter An_AffineFold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_ReversedPrism A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_ReversedPrism An_AffineFold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_ReversedPrism A_Getter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Traversal A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Traversal A_Setter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_AffineTraversal A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_AffineTraversal An_AffineFold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_AffineTraversal A_Setter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_AffineTraversal A_Traversal Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Prism A_Review Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints A_Prism p -> r) -> Constraints A_Review p -> r Source #

Is A_Prism A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints A_Prism p -> r) -> Constraints A_Fold p -> r Source #

Is A_Prism An_AffineFold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Prism A_Setter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints A_Prism p -> r) -> Constraints A_Setter p -> r Source #

Is A_Prism A_Traversal Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Prism An_AffineTraversal Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Lens A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints A_Lens p -> r) -> Constraints A_Fold p -> r Source #

Is A_Lens An_AffineFold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Lens A_Getter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints A_Lens p -> r) -> Constraints A_Getter p -> r Source #

Is A_Lens A_Setter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints A_Lens p -> r) -> Constraints A_Setter p -> r Source #

Is A_Lens A_Traversal Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is A_Lens An_AffineTraversal Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_Iso A_Review Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints An_Iso p -> r) -> Constraints A_Review p -> r Source #

Is An_Iso A_ReversedLens Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_Iso A_Fold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints An_Iso p -> r) -> Constraints A_Fold p -> r Source #

Is An_Iso An_AffineFold Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_Iso A_Getter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints An_Iso p -> r) -> Constraints A_Getter p -> r Source #

Is An_Iso A_ReversedPrism Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_Iso A_Setter Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints An_Iso p -> r) -> Constraints A_Setter p -> r Source #

Is An_Iso A_Traversal Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_Iso An_AffineTraversal Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Is An_Iso A_Prism Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints An_Iso p -> r) -> Constraints A_Prism p -> r Source #

Is An_Iso A_Lens Source # 
Instance details

Defined in Optics.Internal.Optic.Subtyping

Methods

implies :: (Constraints An_Iso p -> r) -> Constraints A_Lens p -> r Source #

type family Join (k :: OpticKind) (l :: OpticKind) where ... Source #

Computes the least upper bound of two optics kinds.

Join k l represents the least upper bound of an Optic k and an Optic l. This means in particular that composition of an Optic k and an Optic k will yield an Optic (Join k l).

Equations

Join An_Iso A_ReversedLens = A_ReversedLens 
Join An_Iso A_ReversedPrism = A_ReversedPrism 
Join An_Iso A_Prism = A_Prism 
Join An_Iso A_Review = A_Review 
Join An_Iso A_Lens = A_Lens 
Join An_Iso A_Getter = A_Getter 
Join An_Iso An_AffineTraversal = An_AffineTraversal 
Join An_Iso An_AffineFold = An_AffineFold 
Join An_Iso A_Traversal = A_Traversal 
Join An_Iso A_Fold = A_Fold 
Join An_Iso A_Setter = A_Setter 
Join A_ReversedLens An_Iso = A_ReversedLens 
Join A_ReversedLens A_Prism = A_Review 
Join A_ReversedLens A_Review = A_Review 
Join A_ReversedPrism An_Iso = A_ReversedPrism 
Join A_ReversedPrism A_Prism = An_AffineFold 
Join A_ReversedPrism A_Lens = A_Getter 
Join A_ReversedPrism A_Getter = A_Getter 
Join A_ReversedPrism An_AffineTraversal = An_AffineFold 
Join A_ReversedPrism An_AffineFold = An_AffineFold 
Join A_ReversedPrism A_Traversal = A_Fold 
Join A_ReversedPrism A_Fold = A_Fold 
Join A_Prism An_Iso = A_Prism 
Join A_Prism A_ReversedLens = A_Review 
Join A_Prism A_ReversedPrism = An_AffineFold 
Join A_Prism A_Review = A_Review 
Join A_Prism A_Lens = An_AffineTraversal 
Join A_Prism A_Getter = An_AffineFold 
Join A_Prism An_AffineTraversal = An_AffineTraversal 
Join A_Prism An_AffineFold = An_AffineFold 
Join A_Prism A_Traversal = A_Traversal 
Join A_Prism A_Fold = A_Fold 
Join A_Prism A_Setter = A_Setter 
Join A_Review An_Iso = A_Review 
Join A_Review A_ReversedLens = A_Review 
Join A_Review A_Prism = A_Review 
Join A_Lens An_Iso = A_Lens 
Join A_Lens A_ReversedPrism = A_Getter 
Join A_Lens A_Prism = An_AffineTraversal 
Join A_Lens A_Getter = A_Getter 
Join A_Lens An_AffineTraversal = An_AffineTraversal 
Join A_Lens An_AffineFold = An_AffineFold 
Join A_Lens A_Traversal = A_Traversal 
Join A_Lens A_Fold = A_Fold 
Join A_Lens A_Setter = A_Setter 
Join A_Getter An_Iso = A_Getter 
Join A_Getter A_ReversedPrism = A_Getter 
Join A_Getter A_Prism = An_AffineFold 
Join A_Getter A_Lens = A_Getter 
Join A_Getter An_AffineTraversal = An_AffineFold 
Join A_Getter An_AffineFold = An_AffineFold 
Join A_Getter A_Traversal = A_Fold 
Join A_Getter A_Fold = A_Fold 
Join An_AffineTraversal An_Iso = An_AffineTraversal 
Join An_AffineTraversal A_ReversedPrism = An_AffineFold 
Join An_AffineTraversal A_Prism = An_AffineTraversal 
Join An_AffineTraversal A_Lens = An_AffineTraversal 
Join An_AffineTraversal A_Getter = An_AffineFold 
Join An_AffineTraversal An_AffineFold = An_AffineFold 
Join An_AffineTraversal A_Traversal = A_Traversal 
Join An_AffineTraversal A_Fold = A_Fold 
Join An_AffineTraversal A_Setter = A_Setter 
Join An_AffineFold An_Iso = An_AffineFold 
Join An_AffineFold A_ReversedPrism = An_AffineFold 
Join An_AffineFold A_Prism = An_AffineFold 
Join An_AffineFold A_Lens = An_AffineFold 
Join An_AffineFold A_Getter = An_AffineFold 
Join An_AffineFold An_AffineTraversal = An_AffineFold 
Join An_AffineFold A_Traversal = A_Fold 
Join An_AffineFold A_Fold = A_Fold 
Join A_Traversal An_Iso = A_Traversal 
Join A_Traversal A_ReversedPrism = A_Fold 
Join A_Traversal A_Prism = A_Traversal 
Join A_Traversal A_Lens = A_Traversal 
Join A_Traversal A_Getter = A_Fold 
Join A_Traversal An_AffineTraversal = A_Traversal 
Join A_Traversal An_AffineFold = A_Fold 
Join A_Traversal A_Fold = A_Fold 
Join A_Traversal A_Setter = A_Setter 
Join A_Fold An_Iso = A_Fold 
Join A_Fold A_ReversedPrism = A_Fold 
Join A_Fold A_Prism = A_Fold 
Join A_Fold A_Lens = A_Fold 
Join A_Fold A_Getter = A_Fold 
Join A_Fold An_AffineTraversal = A_Fold 
Join A_Fold An_AffineFold = A_Fold 
Join A_Fold A_Traversal = A_Fold 
Join A_Setter An_Iso = A_Setter 
Join A_Setter A_Prism = A_Setter 
Join A_Setter A_Lens = A_Setter 
Join A_Setter An_AffineTraversal = A_Setter 
Join A_Setter A_Traversal = A_Setter 
Join k k = k 
Join k l = TypeError ((ShowType k :<>: Text " cannot be composed with ") :<>: ShowType l) 

Composition

The usual operator for composing optics is (%), which allows different optic kinds to be composed, automatically calculating the resulting optic kind using Join.

The (.) function composition operator cannot be used to compose optics, because optics are not functions. The (.) operator from Control.Category cannot be used either, because it would not support type-changing optics or composing optics of different kinds.

(%) :: (Is k m, Is l m, m ~ Join k l, ks ~ Append is js) => Optic k is s t u v -> Optic l js u v a b -> Optic m ks s t a b infixl 9 Source #

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.

(%%) :: forall k is js ks s t u v a b. ks ~ Append is js => Optic k is s t u v -> Optic k js u v a b -> Optic k ks s t a b infixl 9 Source #

Compose two optics of the same flavour.

Normally you can simply use (%) instead, but this may be useful to help type inference if the type of one of the optics is otherwise under-constrained.

(%&) :: Optic k is s t a b -> (Optic k is s t a b -> Optic l js s' t' a' b') -> Optic l js s' t' a' b' infixl 9 Source #

Flipped function application, specialised to optics and binding tightly.

Useful for post-composing optics transformations:

>>> toListOf (ifolded %& ifiltered (\i s -> length s <= i)) ["", "a","abc"]
["","a"]

Monoid structures

Fold-like optics admit various monoid structures (e.g. see Optics.Fold). There is no Semigroup or Monoid instance for Optic, however, because there is not a unique choice of monoid to use, and the (<>) operator could not be used to combine optics of different kinds.

Indexed optics

See the "Indexed optics" section of the overview documentation in the Optics module of the main optics package for more details on indexed optics.

type IxList = [Type] Source #

A list of index types, used for indexed optics.

Since: 0.2

type NoIx = ('[] :: IxList) Source #

An alias for an empty index-list

type WithIx i = ('[i] :: IxList) Source #

Singleton index list

type family Append (xs :: [k]) (ys :: [k]) :: [k] where ... Source #

Append two type-level lists together.

Equations

Append '[] ys = ys 
Append xs '[] = xs 
Append (x ': xs) ys = x ': Append xs ys 

class NonEmptyIndices (is :: IxList) Source #

Check whether a list of indices is not empty and generate sensible error message if it's not.

Instances
(TypeError (Text "Indexed optic is expected") :: Constraint) => NonEmptyIndices ([] :: [Type]) Source # 
Instance details

Defined in Optics.Internal.Indexed

NonEmptyIndices (x ': xs) Source # 
Instance details

Defined in Optics.Internal.Indexed

class is ~ '[i] => HasSingleIndex (is :: IxList) (i :: Type) Source #

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.

Instances
((TypeError (Text "Indexed optic is expected") :: Constraint), ([] :: [Type]) ~ (i ': ([] :: [Type]))) => HasSingleIndex ([] :: [Type]) i Source # 
Instance details

Defined in Optics.Internal.Indexed

((TypeError (Text "Use icomposeN to flatten indices of type " :<>: ShowTypes is) :: Constraint), is ~ (i1 ': (i2 ': (i3 ': (i4 ': (i5 ': (i6 ': is')))))), is ~ (i ': ([] :: [Type]))) => HasSingleIndex (i1 ': (i2 ': (i3 ': (i4 ': (i5 ': (i6 ': is')))))) i Source # 
Instance details

Defined in Optics.Internal.Indexed

((TypeError (Text "Use icompose5 to flatten indices of type " :<>: ShowTypes is) :: Constraint), is ~ (i1 ': (i2 ': (i3 ': (i4 ': (i5 ': ([] :: [Type])))))), is ~ (i ': ([] :: [Type]))) => HasSingleIndex (i1 ': (i2 ': (i3 ': (i4 ': (i5 ': ([] :: [Type])))))) i Source # 
Instance details

Defined in Optics.Internal.Indexed

((TypeError (Text "Use icompose4 to combine indices of type " :<>: ShowTypes is) :: Constraint), is ~ (i1 ': (i2 ': (i3 ': (i4 ': ([] :: [Type]))))), is ~ (i ': ([] :: [Type]))) => HasSingleIndex (i1 ': (i2 ': (i3 ': (i4 ': ([] :: [Type]))))) i Source # 
Instance details

Defined in Optics.Internal.Indexed

((TypeError (Text "Use icompose3 to combine indices of type " :<>: ShowTypes is) :: Constraint), is ~ (i1 ': (i2 ': (i3 ': ([] :: [Type])))), is ~ (i ': ([] :: [Type]))) => HasSingleIndex (i1 ': (i2 ': (i3 ': ([] :: [Type])))) i Source # 
Instance details

Defined in Optics.Internal.Indexed

((TypeError (Text "Use (<%>) or icompose to combine indices of type " :<>: ShowTypes is) :: Constraint), is ~ (i1 ': (i2 ': ([] :: [Type]))), is ~ (i ': ([] :: [Type]))) => HasSingleIndex (i1 ': (i2 ': ([] :: [Type]))) i Source # 
Instance details

Defined in Optics.Internal.Indexed

HasSingleIndex (i ': ([] :: [Type])) i Source # 
Instance details

Defined in Optics.Internal.Indexed

class is ~ NoIx => AcceptsEmptyIndices (f :: Symbol) (is :: IxList) Source #

Show useful error message when a function expects optics without indices.

Instances
AcceptsEmptyIndices f ([] :: [Type]) Source # 
Instance details

Defined in Optics.Internal.Indexed

((TypeError ((Text "\8216" :<>: Text f) :<>: Text "\8217 accepts only optics with no indices") :: Constraint), (x ': xs) ~ NoIx) => AcceptsEmptyIndices f (x ': xs) Source # 
Instance details

Defined in Optics.Internal.Indexed

type family Curry (xs :: IxList) (y :: Type) :: Type where ... Source #

Curry a type-level list.

In pseudo (dependent-)Haskell:

Curry xs y = foldr (->) y xs

Equations

Curry '[] y = y 
Curry (x ': xs) y = x -> Curry xs y 

class CurryCompose xs Source #

Class that is inhabited by all type-level lists xs, providing the ability to compose a function under Curry xs.

Minimal complete definition

composeN

Instances
CurryCompose ([] :: [Type]) Source # 
Instance details

Defined in Optics.Internal.Optic.TypeLevel

Methods

composeN :: (i -> j) -> Curry [] i -> Curry [] j Source #

CurryCompose xs => CurryCompose (x ': xs) Source # 
Instance details

Defined in Optics.Internal.Optic.TypeLevel

Methods

composeN :: (i -> j) -> Curry (x ': xs) i -> Curry (x ': xs) j Source #

Base re-exports

(&) :: 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

(<&>) :: Functor f => f a -> (a -> b) -> f b infixl 1 #

Flipped version of <$>.

(<&>) = flip fmap

Examples

Expand

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

Since: base-4.11.0.0