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

Safe Haskell | None
Language | Haskell2010

Optics.Prism

Contents

- Formation
- Introduction
- Elimination
- Computation
- Well-formedness
- Additional introduction forms
- Additional elimination forms
- Combinators
- Subtyping

Description

A `Prism` generalises the notion of a constructor (just as a `Lens` generalises the notion of a field).

Synopsis

- type Prism s t a b = Optic A_Prism NoIx s t a b
- type Prism' s a = Optic' A_Prism NoIx s a
- prism :: (b -> t) -> (s -> Either t a) -> Prism s t a b
- prism' :: (b -> s) -> (s -> Maybe a) -> Prism s s a b
- only :: Eq a => a -> Prism' a ()
- nearly :: a -> (a -> Bool) -> Prism' a ()
- withPrism :: forall k (is :: IxList) s t a b r. Is k A_Prism => Optic k is s t a b -> ((b -> t) -> (s -> Either t a) -> r) -> r
- aside :: forall k (is :: IxList) s t a b e. Is k A_Prism => Optic k is s t a b -> Prism (e, s) (e, t) (e, a) (e, b)
- without :: forall k l (is :: IxList) s t a b u v c d. (Is k A_Prism, Is l A_Prism) => Optic k is s t a b -> Optic l is u v c d -> Prism (Either s u) (Either t v) (Either a c) (Either b d)
- below :: forall k f (is :: IxList) s a. (Is k A_Prism, Traversable f) => Optic' k is s a -> Prism' (f s) (f a)
- data A_Prism

# Formation

type Prism s t a b = Optic A_Prism NoIx s t a b Source #

Type synonym for a type-modifying prism.

type Prism' s a = Optic' A_Prism NoIx s a Source #

Type synonym for a type-preserving prism.

# Introduction

prism :: (b -> t) -> (s -> Either t a) -> Prism s t a b Source #

Build a prism from a constructor and a matcher, which must respect the well-formedness laws.

If you want to build a `Prism` from the van Laarhoven representation, use `prismVL` from the `optics-vl` package.

# Elimination

A `Prism` is in particular an `AffineFold`, an `AffineTraversal`, a `Review` and a `Setter`, therefore you can specialise types to obtain:

    preview  :: Prism' s a -> s -> Maybe a
    review   :: Prism' s a -> a -> s

    over     :: Prism s t a b -> (a -> b) -> s -> t
    set      :: Prism s t a b ->       b  -> s -> t
    matching :: Prism s t a b             -> s -> Either t a

If you want to `preview` a type-modifying `Prism` that is insufficiently polymorphic to be used as a type-preserving `Prism'`, use `getting`:

    preview . getting :: Prism s t a b -> s -> Maybe a

# Computation

    review   (prism f g) ≡ f
    matching (prism f g) ≡ g

# Well-formedness

    matching o (review o b) ≡ Right b
    matching o s ≡ Right a  =>  review o a ≡ s

# Additional introduction forms

See Data.Maybe.Optics and Data.Either.Optics for `Prism`s for the corresponding types, and `_Cons`, `_Snoc` and `_Empty` for `Prism`s for container types.

prism' :: (b -> s) -> (s -> Maybe a) -> Prism s s a b Source #

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

only :: Eq a => a -> Prism' a () Source #

This `Prism` compares for exact equality with a given value.

    >>> only 4 # ()
    4

    >>> 5 ^? only 4
    Nothing

nearly :: a -> (a -> Bool) -> Prism' a () Source #

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 [] null
    Nothing

    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.

# Additional elimination forms

withPrism :: forall k (is :: IxList) s t a b r. Is k A_Prism => Optic k is s t a b -> ((b -> t) -> (s -> Either t a) -> r) -> r Source #

Work with a `Prism` as a constructor and a matcher.

# Combinators

aside :: forall k (is :: IxList) s t a b e. Is k A_Prism => Optic k is s t a b -> Prism (e, s) (e, t) (e, a) (e, b) Source #

Use a `Prism` to work over part of a structure.

without :: forall k l (is :: IxList) s t a b u v c d. (Is k A_Prism, Is l A_Prism) => Optic k is s t a b -> Optic l is u v c d -> Prism (Either s u) (Either t v) (Either a c) (Either b d) Source #

Given a pair of prisms, project sums.

Viewing a `Prism` as a co-`Lens`, this combinator can be seen to be dual to `alongside`.

below :: forall k f (is :: IxList) s a. (Is k A_Prism, Traversable f) => Optic' k is s a -> Prism' (f s) (f a) Source #

Lift a `Prism` through a `Traversable` functor, giving a `Prism` that matches only if all the elements of the container match the `Prism`.

# Subtyping

data A_Prism Source #

Tag for a prism.

#### Instances

Instances details

ReversibleOptic A_Prism Source # |

Instance details

Defined in Optics.Re

Associated Types

type ReversedOptic A_Prism |
Instance details Defined in Optics.Re type ReversedOptic A_Prism = A_ReversedPrism

Methods

re :: forall (is :: IxList) s t a b. AcceptsEmptyIndices "re" is => Optic A_Prism is s t a b -> Optic (ReversedOptic A_Prism) is b a t s Source #

ArrowChoice arr => ArrowOptic A_Prism arr Source # |
Instance details Defined in Optics.Arrow Methods overA :: forall (is :: IxList) s t a b. Optic A_Prism is s t a b -> arr a b -> arr s t Source #
Is A_Prism A_Fold Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods implies :: forall (p :: Type -> Type -> Type -> Type) r. (Constraints A_Prism p => r) -> Constraints A_Fold p => r Source #
Is A_Prism A_Review Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods implies :: forall (p :: Type -> Type -> Type -> Type) r. (Constraints A_Prism p => r) -> Constraints A_Review p => r Source #
Is A_Prism A_Setter Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods implies :: forall (p :: Type -> Type -> Type -> Type) r. (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 Methods implies :: forall (p :: Type -> Type -> Type -> Type) r. (Constraints A_Prism p => r) -> Constraints A_Traversal p => r Source #
Is A_Prism An_AffineFold Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods implies :: forall (p :: Type -> Type -> Type -> Type) r. (Constraints A_Prism p => r) -> Constraints An_AffineFold p => r Source #
Is A_Prism An_AffineTraversal Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods implies :: forall (p :: Type -> Type -> Type -> Type) r. (Constraints A_Prism p => r) -> Constraints An_AffineTraversal p => r Source #
Is An_Iso A_Prism Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods implies :: forall (p :: Type -> Type -> Type -> Type) r. (Constraints An_Iso p => r) -> Constraints A_Prism p => r Source #
k ~ A_Fold => JoinKinds A_Fold A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Fold p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ An_AffineFold => JoinKinds A_Getter A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Getter p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ An_AffineTraversal => JoinKinds A_Lens A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Lens p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ A_Fold => JoinKinds A_Prism A_Fold k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_Fold p) => r) -> Constraints k p => r Source #
k ~ An_AffineFold => JoinKinds A_Prism A_Getter k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_Getter p) => r) -> Constraints k p => r Source #
k ~ An_AffineTraversal => JoinKinds A_Prism A_Lens k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_Lens p) => r) -> Constraints k p => r Source #
k ~ A_Prism => JoinKinds A_Prism A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ A_Review => JoinKinds A_Prism A_ReversedLens k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_ReversedLens p) => r) -> Constraints k p => r Source #
k ~ An_AffineFold => JoinKinds A_Prism A_ReversedPrism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_ReversedPrism p) => r) -> Constraints k p => r Source #
k ~ A_Review => JoinKinds A_Prism A_Review k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_Review p) => r) -> Constraints k p => r Source #
k ~ A_Setter => JoinKinds A_Prism A_Setter k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_Setter p) => r) -> Constraints k p => r Source #
k ~ A_Traversal => JoinKinds A_Prism A_Traversal k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints A_Traversal p) => r) -> Constraints k p => r Source #
k ~ An_AffineFold => JoinKinds A_Prism An_AffineFold k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints An_AffineFold p) => r) -> Constraints k p => r Source #
k ~ An_AffineTraversal => JoinKinds A_Prism An_AffineTraversal k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints An_AffineTraversal p) => r) -> Constraints k p => r Source #
k ~ A_Prism => JoinKinds A_Prism An_Iso k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Prism p, Constraints An_Iso p) => r) -> Constraints k p => r Source #
k ~ A_Review => JoinKinds A_ReversedLens A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_ReversedLens p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ An_AffineFold => JoinKinds A_ReversedPrism A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_ReversedPrism p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ A_Review => JoinKinds A_Review A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Review p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ A_Setter => JoinKinds A_Setter A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Setter p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ A_Traversal => JoinKinds A_Traversal A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints A_Traversal p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ An_AffineFold => JoinKinds An_AffineFold A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints An_AffineFold p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ An_AffineTraversal => JoinKinds An_AffineTraversal A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints An_AffineTraversal p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
k ~ A_Prism => JoinKinds An_Iso A_Prism k Source # |
Instance details Defined in Optics.Internal.Optic.Subtyping Methods joinKinds :: forall (p :: Type -> Type -> Type -> Type) r. ((Constraints An_Iso p, Constraints A_Prism p) => r) -> Constraints k p => r Source #
ToReadOnly A_Prism s t a b Source # |

Instance details

Defined in Optics.ReadOnly

Associated Types

type ReadOnlyOptic A_Prism |
Instance details Defined in Optics.ReadOnly type ReadOnlyOptic A_Prism = An_AffineFold

Methods

getting :: forall (is :: IxList). Optic A_Prism is s t a b -> Optic' (ReadOnlyOptic A_Prism) is s a Source #

(Functor f, f ~ g, s ~ t, a ~ b) => MappingOptic A_Prism f g s t a b Source # |

Instance details

Defined in Optics.Mapping

Associated Types

type MappedOptic A_Prism |
Instance details Defined in Optics.Mapping type MappedOptic A_Prism = A_Review

Methods

mapping :: forall (is :: IxList). AcceptsEmptyIndices "mapping" is => Optic A_Prism is s t a b -> Optic (MappedOptic A_Prism) is (f s) (g t) (f a) (g b) Source #

type MappedOptic A_Prism Source # |
Instance details Defined in Optics.Mapping type MappedOptic A_Prism = A_Review
type ReversedOptic A_Prism Source # |
Instance details Defined in Optics.Re type ReversedOptic A_Prism = A_ReversedPrism
type ReadOnlyOptic A_Prism Source # |
Instance details Defined in Optics.ReadOnly type ReadOnlyOptic A_Prism = An_AffineFold