Optics

https://hackage.haskell.org/package/optics-0.4.2.1/docs/
Admin
Optics is a Haskell library providing a powerful and composable approach to working with immutable...
Tokens:8,162
Snippets:129
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Setup imports for optics examples

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Required imports for using optics and state operators in examples.

```haskell
>>> import Control.Monad.Reader
>>> import Control.Monad.State
>>> import Data.Functor.Identity
>>> import qualified Data.IntSet as IntSet
>>> import qualified Data.Map as Map
>>> import Optics.State.Operators
```

--------------------------------

### Indexed Fold Examples

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Demonstrates the difference between standard and indexed folding behavior.

```haskell
>>> toListOf ifolded "foo"
"foo"

>>> itoListOf ifolded "foo"
[(0,'f'),(1,'o'),(2,'o')]
```

--------------------------------

### Prism Usage Examples

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Demonstrates the use of prisms for projecting and constructing values within an Either type.

```haskell
@
        '_Left'  :: 'Prism'' ('Either' X Y) X
        '_Right' :: 'Prism'' ('Either' X Y) Y
'preview' '_Left'  :: 'Either' X Y -> 'Maybe' X
'review'  '_Right' :: Y -> 'Either' X Y
@
```

--------------------------------

### Define Lens Formation

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Formation section example defining the Lens type synonym.

```haskell
-- Type synonym for a type-modifying lens.
type Lens s t a b = Optic A_Lens NoIx s t a b
```

--------------------------------

### Define Lens in optics package

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Example of an opaque newtype representation for a Lens in the optics package.

```haskell
type Lens s t a b = Optic A_Lens NoIx s t a b
```

--------------------------------

### Define Lens in lens package

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Example of a transparent type synonym representation for a Lens in the lens package.

```haskell
type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t
```

--------------------------------

### Traversal Usage Examples

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Demonstrates the use of traversals for accessing and updating elements within a Maybe type.

```haskell
@
         'traversed' :: 'Traversal'' ('Maybe' X) X
'toListOf' 'traversed' :: 'Maybe' X -> [X]
'over'     'traversed' :: (X -> X) -> 'Maybe' X -> 'Maybe' X
@
```

--------------------------------

### Opaque Optic Representation

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Example of the opaque newtype representation used in the optics package.

```haskell
type 'Lens' s t a b = 'Optic' 'A_Lens' 'NoIx' s t a b
```

--------------------------------

### Defining Optic Aliases

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Example of defining aliases for optics without being affected by the monomorphism restriction.

```haskell
>>> let { myoptic = _1; p = ('x','y') } in (view myoptic p, set myoptic 'c' p)
('x',('c','y'))
```

--------------------------------

### Trigger composition error

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Example of an error message when composing incompatible optics.

```haskell
>>> **sets map % to not
**...
...A_Setter cannot be composed with A_Getter
...
```

--------------------------------

### Trigger domain-specific error

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Example of an error message when attempting to use a Getter as a Setter.

```haskell
>>> **set (to fst)
**...
...A_Getter cannot be used as A_Setter
...
```

--------------------------------

### Composition error example

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Shows the error message generated when attempting to compose incompatible optic kinds like Setter and Fold.

```haskell
>>> **:t mapped % folded
**...
...A_Setter cannot be composed with A_Fold
...
```

--------------------------------

### Define and use optic alias

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Example of defining an alias for an optic and using it for view and set operations.

```haskell
>>> **let { myoptic = _1; p = ('x','y') } in (view myoptic p, set myoptic 'c' p)
**('x',('c','y'))
```

--------------------------------

### Domain-Specific Error Messages

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Example of the descriptive error messages provided by the opaque design when using incompatible optics.

```haskell
>>> set (to fst)
    ...
    ...A_Getter cannot be used as A_Setter
```

```haskell
>>> sets map % to not
    ...
    ...A_Setter cannot be composed with A_Getter
```

--------------------------------

### Van Laarhoven Lens Representation

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Example of the transparent type synonym representation used in the lens package.

```haskell
type Lens s t a b = forall f. 'Functor' f => (a -> f b) -> s -> f t
```

--------------------------------

### Downgrade indexed optics to regular

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Demonstrates how indexed optics can be used as regular optics.

```haskell
>>> **toListOf ifolded "foo"
**"foo"
```

```haskell
>>> **itoListOf ifolded "foo"
**[(0,'f'),(1,'o'),(2,'o')]
```

--------------------------------

### Importing the Optics core library

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Minimal import for projects aiming to reduce dependency footprint by using optics-core.

```haskell
import Optics.Core
```

--------------------------------

### Importing the Optics library

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Standard import for the full optics library after adding it as a dependency in the .cabal file.

```haskell
import Optics
```

--------------------------------

### Use Prisms for sum types

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Demonstrates partial projection and construction for sum types using prisms.

```haskell
        _Left  :: Prism' (Either X Y) X
        _Right :: Prism' (Either X Y) Y
preview _Left  :: Either X Y -> Maybe X
review  _Right :: Y -> Either X Y
```

--------------------------------

### Reverse optics with Re

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Invert Isos or use lenses as reviews.

```haskell
>>> let _Identity = iso runIdentity Identity
>>> view (_1 % re _Identity) ('x', "yz")
Identity 'x'
```

```haskell
>>> review (re _1) ('x', "yz")
'x'
```

--------------------------------

### Importing Optics

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Basic import statements for using the optics library or its core components.

```haskell
import "Optics"
```

```haskell
import "Optics.Core"
```

--------------------------------

### Polymorphic View

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Demonstrate the use of view with polymorphic optic kinds.

```haskell
'view' :: 'Is' k 'A_Getter' => 'Optic'' k is s a -> s -> a
```

--------------------------------

### Compose lens with indexed traversal

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Demonstrates how composing a lens with an indexed traversal results in an indexed optic.

```haskell
>>> **let fst' = _1 :: Lens (a, c) (b, c) a b
**>>> **:t fst' % itraversed
**fst' % itraversed
  :: TraversableWithIndex i f =>
     Optic A_Traversal '[i] (f a, c) (f b, c) a b
```

--------------------------------

### Use Lenses for product types

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Shows how to access and update fields in a pair type using lenses.

```haskell
     _1 :: Lens' (X,Y) X
     _2 :: Lens' (X,Y) Y
view _1 :: (X,Y) -> X
set  _2 :: Y -> (X,Y) -> (X,Y)
```

--------------------------------

### Compare Setter and IxSetter signatures

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Shows the difference between standard and indexed setter type signatures.

```haskell
over  :: Setter     s t a b -> (a -> b)      -> s -> t
iover :: IxSetter i s t a b -> (i -> a -> b) -> s -> t
```

--------------------------------

### Construct a Lens

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Introduction form for creating a lens from a getter and a setter function.

```haskell
-- Build a lens from a getter and a setter.
lens :: (s -> a) -> (s -> b -> t) :: Lens s t a b
```

--------------------------------

### Compose indexed optics

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Shows how composing indexed optics concatenates their index lists.

```haskell
λ> :t (ifolded % ifolded)
(ifolded % ifolded)
  :: (FoldableWithIndex i1 f1, FoldableWithIndex i2 f2) =>
     Optic A_Fold '[i1, i2] (f1 (f2 b)) (f1 (f2 b)) b b
```

--------------------------------

### Type Inference with Opaque Optics

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Demonstration of how opaque abstractions preserve optic kinds during type inference.

```haskell
>>> :t traversed % to not
    traversed % to not
      :: Traversable t => Optic A_Fold '[] (t Bool) (t Bool) Bool Bool
```

--------------------------------

### Define an Iso for a newtype

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Demonstrates creating an isomorphism between a newtype and its underlying representation.

```haskell
newtype Age = Age Int
```

```haskell
       coerced :: Iso' Age Int
view   coerced :: Age -> Int
review coerced :: Int -> Age
```

--------------------------------

### Generalized viewing with gview

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

A polymorphic view function that adapts to the optic type and MonadReader context.

```haskell
>>> gview _1 ('x','y')
'x'
```

```haskell
>>> gview _Left (Left 'x')
Just 'x'
```

```haskell
>>> gview folded ["a", "b"]
"ab"
```

```haskell
>>> runReaderT (gview _1) ('x','y') :: IO Char
'x'
```

--------------------------------

### Store optics in a list

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Demonstrates storing optics in a data structure due to the rank-1 type design.

```haskell
>>> **:t [folded, backwards_ folded]
**[folded, backwards_ folded] :: Foldable f => [Fold (f a) a]
```

--------------------------------

### Polymorphic view function signature

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Demonstrates how the view function accepts various optic kinds by using the Is typeclass constraint.

```haskell
view :: Is k A_Getter => Optic' k is s a -> s -> a
```

--------------------------------

### Traverse or modify map keys with At

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Use ix for traversal and at for lens-based map manipulation.

```haskell
>>> preview (ix 1) ['a','b','c']
Just 'b'
```

```haskell
>>> set (at 0) (Just 'b') (Map.fromList [(0, 'a')])
fromList [(0,'b')]
```

```haskell
>>> IntSet.fromList [1,2,3,4] & contains 3 .~ False
fromList [1,2,4]
```

--------------------------------

### Check for empty containers with Empty

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

A prism to determine if a container is empty.

```haskell
>>> isn't _Empty [1,2,3]
True
```

--------------------------------

### Lens Type Definitions

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Shows the type synonym definitions for lenses using the Optic newtype and A_Lens tag.

```haskell
@
type 'Lens'  s t a b = 'Optic'  'A_Lens' 'NoIx' s t a b
type 'Lens'' s   a   = 'Optic'' 'A_Lens' 'NoIx' s   a
@
```

--------------------------------

### Use Traversals for multiple substructures

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Shows how to extract or modify multiple elements within a structure using traversals.

```haskell
         traversed :: Traversal' (Maybe X) X
toListOf traversed :: Maybe X -> [X]
over     traversed :: (X -> X) -> Maybe X -> Maybe X
```

--------------------------------

### Index Retention Operators

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Demonstrates operators for selecting specific indices during composition.

```haskell
>>> itoListOf (ifolded <% ifolded) [['a','b'], ['c', 'd']]
[(0,'a'),(0,'b'),(1,'c'),(1,'d')]

>>> itoListOf (ifolded %> ifolded) [['a','b'], ['c', 'd']]
[(0,'a'),(1,'b'),(0,'c'),(1,'d')]

>>> itoListOf (ifolded <%> ifolded) [['a','b'], ['c', 'd']]
[((0,0),'a'),((0,1),'b'),((1,0),'c'),((1,1),'d')]
```

--------------------------------

### Check optic type inference

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Demonstrates how the optic kind is preserved in the inferred type.

```haskell
>>> **:t traversed % to not
**traversed % to not
  :: Traversable t => Optic A_Fold '[] (t Bool) (t Bool) Bool Bool
```

--------------------------------

### Compose indexed optics with index retention

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Operators for selecting specific indices during composition.

```haskell
>>> **itoListOf (ifolded <% ifolded) [['a','b'], ['c', 'd']]
**[(0,'a'),(0,'b'),(1,'c'),(1,'d')]
```

```haskell
>>> **itoListOf (ifolded %> ifolded) [['a','b'], ['c', 'd']]
**[(0,'a'),(1,'b'),(0,'c'),(1,'d')]
```

```haskell
>>> **itoListOf (ifolded <%> ifolded) [['a','b'], ['c', 'd']]
**[((0,0),'a'),((0,1),'b'),((1,0),'c'),((1,1),'d')]
```

--------------------------------

### Zoom into state with Zoom

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Change the state supplied by monad transformers.

```haskell
>>> flip execState ('a','b') $ zoom _1 $ equality .= 'c'
('c','b')
```

--------------------------------

### Flatten indices with icompose

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Use icompose to combine multiple indices into a single index.

```haskell
λ> :t icompose (,) (ifolded % ifolded)
icompose (,) (ifolded % ifolded)
  :: (FoldableWithIndex i1 f1, FoldableWithIndex i2 f2) =>
     Optic A_Fold (WithIx (i1, i2)) (f1 (f2 b)) (f1 (f2 b)) b b
```

```haskell
>>> **itoListOf (icompose (,) (ifolded % ifolded)) [['a','b'], ['c', 'd']]
**[((0,0),'a'),((0,1),'b'),((1,0),'c'),((1,1),'d')]
```

--------------------------------

### Traverse container elements with Each

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

An IxTraversal for operating on each element of a container.

```haskell
>>> over each (*10) (1,2,3)
(10,20,30)
```

--------------------------------

### Define Lens Type Synonyms

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Type synonyms for type-modifying and type-preserving lenses using the Optic wrapper.

```haskell
type Lens  s t a b = Optic  A_Lens NoIx s t a b
type Lens' s   a   = Optic' A_Lens NoIx s   a
```

--------------------------------

### Match sequence ends with Cons and Snoc

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Prisms for matching the beginning or end of sequential structures.

```haskell
>>> preview _Cons "abc"
Just ('a',"bc")
```

```haskell
>>> preview _Snoc "abc"
Just ("ab",'c')
```

--------------------------------

### Lens Computation Rules

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Computation rules defining the expected behavior of view and set operations on a lens.

```haskell
view (lens f g)   s ≡ f s
set  (lens f g) a s ≡ g s a
```

--------------------------------

### TraversableWithIndex class definition

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

The type class definition for indexed traversals.

```haskell
class (FoldableWithIndex i t, Traversable t)
  => TraversableWithIndex i t | t -> i where
    itraverse :: Applicative f => (i -> a -> f b) -> t a -> f (t b)
```

--------------------------------

### Eliminate a Lens

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/src/Optics.html

Destruct a lens into its getter and setter components.

```haskell
-- A 'Lens' is a 'Setter' and a 'Getter', therefore you can specialise types to obtain
'view' :: 'Lens' s t a b -> s -> a
'set'  :: 'Lens' s t a b -> b -> s -> t
```

--------------------------------

### Erase indices with noIx

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Explicitly remove indices from an optic using the noIx combinator.

```haskell
>>> **:t (ifolded % simple)
**(ifolded % simple)
  :: FoldableWithIndex i f => Optic A_Fold '[i] (f b) (f b) b b
```

```haskell
>>> **:t noIx (ifolded % simple)
**noIx (ifolded % simple)
  :: FoldableWithIndex i f => Optic A_Fold NoIx (f b) (f b) b b
```

```haskell
λ> :t noIx (ifolded % ifolded)
noIx (ifolded % ifolded)
  :: (FoldableWithIndex i1 f1, FoldableWithIndex i2 f2) =>
     Optic A_Fold NoIx (f1 (f2 b)) (f1 (f2 b)) b b
```

--------------------------------

### Eliminate a Lens

Source: https://hackage.haskell.org/package/optics-0.4.2.1/docs/Optics.html

Elimination forms for accessing or modifying data through a lens.

```haskell
-- A Lens is a Setter and a Getter, therefore you can specialise types to obtain
view :: Lens s t a b -> s -> a
set  :: Lens s t a b -> b -> s -> t
```
Tokens:
Raw