Optics

https://github.com/well-typed/optics
Admin
Optics is a Haskell package family that provides abstractions for defining and using Lenses,...
Tokens:7,292
Snippets:30
Trust Score:7.9
Update:7 months ago
Show doc for...
Tokens:
Raw
### Prism: Pattern Matching and Construction with Sum Types in Haskell

Source: https://context7.com/well-typed/optics/llms.txt

Illustrates the use of Prisms in Haskell for working with sum types, enabling pattern matching (preview) and construction (review). This example covers built-in prisms for `Either`, custom prism creation for a `Shape` data type, and usage with operators like `#` and `^?`.

```haskell
import Optics
import Data.Either

-- Built-in prisms for Either
preview _Left (Left 'x')    -- Result: Just 'x'
preview _Left (Right 'y')   -- Result: Nothing
review _Right 'z'           -- Result: Right 'z'

-- Pattern matching with matching
matching _Left (Left 5)     -- Result: Right 5
matching _Left (Right "hi") -- Result: Left (Right "hi")

-- Build a prism from constructor and matcher
data Shape = Circle Double | Rectangle Double Double deriving Show

_Circle :: Prism' Shape Double
_Circle = prism Circle $ \case
  Circle r -> Right r
  other    -> Left other

_Rectangle :: Prism' Shape (Double, Double)
_Rectangle = prism (uncurry Rectangle) $ \case
  Rectangle w h -> Right (w, h)
  other         -> Left other

-- Using prisms
preview _Circle (Circle 5.0)          -- Result: Just 5.0
preview _Circle (Rectangle 3.0 4.0)   -- Result: Nothing
review _Circle 10.0                   -- Result: Circle 10.0

-- Modify if matches
over _Circle (*2) (Circle 5.0)        -- Result: Circle 10.0
over _Circle (*2) (Rectangle 3 4)     -- Result: Rectangle 3.0 4.0

-- Using operators
_Left # 42                            -- Result: Left 42
Left "hello" ^? _Left                 -- Result: Just "hello"

-- only and nearly for exact equality
only 5 # ()                           -- Result: 5
preview (only 5) 5                    -- Result: Just ()
preview (only 5) 6                    -- Result: Nothing

```

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

### Lens: Accessing and Modifying Single Fields in Haskell

Source: https://context7.com/well-typed/optics/llms.txt

Demonstrates how to define and use Lenses in Haskell for getting, setting, and modifying single fields within data structures. Lenses ensure consistent behavior by adhering to the GetPut, PutGet, and PutPut laws. This example shows manual lens creation and usage with operators like `view`, `set`, `over`, `^.`, `&`, `.~`, and `%.`.

```haskell
import Optics

-- Define a data type
data Human = Human { _name :: String, _location :: String } deriving Show

-- Create a lens manually from getter and setter
name :: Lens' Human String
name = lens _name (\s x -> s { _name = x })

-- Using the lens
human :: Human
human = Human "Bob" "London"

-- Get a value with view
view name human
-- Result: "Bob"

-- Set a value with set
set name "Robert" human
-- Result: Human {_name = "Robert", _location = "London"}

-- Modify with over
over name (++ " Smith") human
-- Result: Human {_name = "Bob Smith", _location = "London"}

-- Using operators
human ^. name           -- Get: "Bob"
human & name .~ "Alice" -- Set: Human {_name = "Alice", _location = "London"}
human & name %~ reverse -- Modify: Human {_name = "boB", _location = "London"}

-- Tuple lenses (_1, _2, etc.)
view _1 ('a', 'b')      -- Result: 'a'
set _2 'z' ('a', 'b')   -- Result: ('a', 'z')

-- Compose lenses with %
data Address = Address { _city :: String, _country :: String }
data Person = Person { _personName :: String, _address :: Address }

personCity :: Lens' Person String
personCity = lens _address (\p a -> p { _address = a }) % lens _city (\a c -> a { _city = c })

```

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

### Haskell Optic Get, Set, and Modify Operators

Source: https://context7.com/well-typed/optics/llms.txt

Illustrates the usage of common optic operators for retrieving values ('^.', '^?'), setting values ('.~'), modifying values ('%~'), and reviewing values ('#'). It also includes the '?' operator for optional setting.

```haskell
-- Get operators
('x', 'y') ^. _1                       -- Result: 'x'
Left 5 ^? _Left                        -- Result: Just 5
[1, 2, 3] ^.. traversed                -- Result: [1, 2, 3]

-- Set operators
('a', 'b') & _1 .~ 'z'                 -- Result: ('z', 'b')
('a', 'b') & _1 %~ succ                -- Result: ('b', 'b')

-- Review operator
_Left # 42                             -- Result: Left 42

-- Maybe set operator
Nothing & equality ?~ 'x'              -- Result: Just 'x'
Map.empty & at 1 ?~ "hello"            -- Result: fromList [(1,"hello")]

-- Strict operators
('a', 'b') & _1 !~ 'z'                 -- Strict set
('a', 'b') & _1 %!~ succ               -- Strict modify
```

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

### Define Indexed Instances with indexed-traversable and Optics

Source: https://github.com/well-typed/optics/blob/master/migration-guide-0.4.md

This snippet demonstrates how to define FunctorWithIndex, FoldableWithIndex, and TraversableWithIndex instances for a custom container 'MySeq' using the 'indexed-traversable' package. It also includes conditional compilation for optics-core versions older than 0.4 to maintain compatibility.

```haskell
-- from indexed-traversable
import Data.Functor.WithIndex

-- from optics-core
import qualified Optics.Core as O

-- your (indexed) container
data MySeq a = ...

-- indexed-traversable instance
instance FunctorWithIndex     Int MySeq where imap = ...
instance FoldableWithIndex    Int MySeq where ifoldMap = ...
instance TraversableWithIndex Int MySeq where itraverse = ...

-- optics-core <0.4 instance, note the !
#if !MIN_VERSION_optics_core(0,4,0)
instance O.FunctorWithIndex     Int MySeq where imap = imap
instance O.FoldableWithIndex    Int MySeq where ifoldMap = ifoldMap
instance O.TraversableWithIndex Int MySeq where itraverse = itraverse
#endif
```

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

### Iso: Bidirectional Type Conversion in Haskell

Source: https://context7.com/well-typed/optics/llms.txt

Demonstrates creating and using Isos for structurally equivalent types. Covers building Isos from inverse functions, using them bidirectionally, and applying built-in Isos like `coerced`, `curried`, `uncurried`, `flipped`, `swapped`, `involuted`, and `non` for various scenarios including newtype wrappers and default value handling.

```haskell
import Optics
import Data.Functor.Identity

-- Build an iso from two inverse functions
_Identity :: Iso' (Identity a) a
_Identity = iso runIdentity Identity

-- Use in both directions
view _Identity (Identity 'x')    -- Result: 'x'
review _Identity 'y'             -- Result: Identity 'y'

-- coerced for newtype wrappers
newtype Age = Age Int deriving Show

view coerced (Age 25) :: Int     -- Result: 25
review coerced 30 :: Age         -- Result: Age 30

-- Useful built-in isos
view curried fst 1 2             -- Result: 1  (curry uncurried function)
view uncurried (+) (1, 2)        -- Result: 3  (uncurry curried function)
view flipped (,) 'a' 'b'         -- Result: ('b', 'a')
view swapped (1, 2)              -- Result: (2, 1)

-- involuted for self-inverse functions
"evil" ^. involuted reverse      -- Result: "live"

-- non for treating Nothing as a default value
import qualified Data.Map as Map

-- Treat missing keys as 0
Map.empty ^. at "count" % non 0                    -- Result: 0
Map.fromList [("count", 5)] ^. at "count" % non 0  -- Result: 5

-- Set to Nothing if value equals default
Map.fromList [("x", 0)] & at "x" % non 0 .~ 0      -- Result: fromList []
Map.fromList [("x", 5)] & at "x" % non 0 %~ (+1)   -- Result: fromList [("x",6)]
```

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

### Haskell Optic Composition with % Operator

Source: https://context7.com/well-typed/optics/llms.txt

Demonstrates how the '%' operator composes different optic types like Lens and Prism to create new optics such as AffineTraversal. It showcases type inference for composed optics.

```haskell
import Optics
import qualified Data.Map as Map

-- Composition with %
_1 % _2 :: Lens' ((a, b), c) b

-- Lens % Prism = AffineTraversal
_1 % _Left :: AffineTraversal' (Either a b, c) a
```

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

### Haskell Chaining and Deep Access with Optics

Source: https://context7.com/well-typed/optics/llms.txt

Demonstrates chaining multiple optic modifications to deeply access and alter nested data structures. It shows how to combine operators for complex transformations.

```haskell
-- Chaining modifications
(1, (2, 3)) & _1 %~ (*10)
           & _2 % _1 %~ (*100)
           & _2 % _2 %~ (*1000)
-- Result: (10, (200, 3000))

-- Deep access in nested structures
data Config = Config { _settings :: Map.Map String Int }
-- config ^. settings % at "timeout" % non 30
```

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

### Template Haskell for Automatic Optics Generation

Source: https://context7.com/well-typed/optics/llms.txt

The `optics-th` package enables automatic generation of optics for data types using Template Haskell. This includes generating top-level lens functions, `OverloadedLabels` instances, and prisms for constructors.

```haskell
{-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE OverloadedLabels #-}

import Optics
import Optics.TH

-- Data type with underscore-prefixed fields
data Animal = Cat { _age :: Int, _name :: String }
            | Dog { _age :: Int }
            deriving Show

-- Generate top-level optics functions
makeLenses ''Animal
-- Creates:
--   age  :: Lens' Animal Int
--   name :: AffineTraversal' Animal String

-- Generate label instances for use with #field syntax
makeFieldLabels ''Animal
-- Creates instances for #age and #name labels

-- Using generated optics
cat :: Animal
cat = Cat 5 "Whiskers"

view age cat                    -- Result: 5
set age 6 cat                   -- Result: Cat {_age = 6, _name = "Whiskers"}

-- Using with OverloadedLabels (after makeFieldLabels)
-- view #age cat
-- set #name "Fluffy" cat

-- Generate prisms for constructors
makePrisms ''Animal
-- Creates:
--   _Cat :: Prism' Animal (Int, String)
--   _Dog :: Prism' Animal Int

preview _Cat cat                -- Result: Just (5, "Whiskers")
review _Dog 3                   -- Result: Dog {_age = 3}

-- Declare types and optics together
declareLenses [d|
  data Point = Point { pointX :: Double, pointY :: Double }
    deriving Show
  |]
-- Creates Point without record syntax plus pointX, pointY lenses

-- Custom naming rules
makeLensesWith (lensRules & lensField .~ mappingNamer (\s -> [s ++ "L"])) ''Animal
-- Creates ageL, nameL instead of age, name
```

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

### Indexed Optics for Position-Dependent Operations

Source: https://context7.com/well-typed/optics/llms.txt

Indexed optics provide an index (position or key) along with the element, enabling operations sensitive to location. Functions like `itraversed`, `iover`, and `ifolded` are demonstrated.

```haskell
import Optics

-- itraversed: indexed traversal
itoListOf itraversed "abc"                     -- Result: [(0,'a'), (1,'b'), (2,'c')]

-- iover: modify with index
iover itraversed (\i c -> (i, c)) "abc"        -- Result: [(0,'a'), (1,'b'), (2,'c')]

-- ifolded: indexed fold
itoListOf ifolded [10, 20, 30]                 -- Result: [(0,10), (1,20), (2,30)]

-- Indexed operations work with regular combinators too
toiListOf ifolded "foo"                         -- Result: "foo" (index ignored)

-- Composing indexed optics
-- <% keeps left index, %> keeps right index, <%> keeps both
itoListOf (ifolded <% ifolded) [['a', 'b'], ['c', 'd']]
-- Result: [(0,'a'), (0,'b'), (1,'c'), (1,'d')]

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

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

-- icompose: custom index combination
itoListOf (icompose (,) (ifolded % ifolded)) [['a', 'b'], ['c', 'd']]
-- Result: [((0,0),'a'), ((0,1),'b'), ((1,0),'c'), ((1,1),'d')]

-- noIx: explicitly erase indices
-- toListOf (noIx (ifolded % ifolded)) [[1,2],[3,4]]
```

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

### Map and Sequence Access with At and Ix

Source: https://context7.com/well-typed/optics/llms.txt

Provides optics for accessing elements in map-like and sequence-like containers by key or index. `ix` is an AffineTraversal for indexed access, while `at` is a Lens for map access, supporting insertion and deletion.

```haskell
import Optics
import qualified Data.Map as Map
import qualified Data.IntSet as IntSet

-- ix: AffineTraversal for accessing by index/key
preview (ix 1) ['a', 'b', 'c']                 -- Result: Just 'b'
preview (ix 10) ['a', 'b', 'c']                -- Result: Nothing
over (ix 2) (*10) [1, 2, 3, 4]                 -- Result: [1, 2, 30, 4]

-- ix on tuples
preview (ix 0) ('a', 'b', 'c')                 -- Result: Just 'a'
preview (ix 2) ('a', 'b', 'c')                 -- Result: Just 'c'

-- at: Lens for maps (can insert/delete)
let m = Map.fromList [(1, "one"), (2, "two")]

view (at 1) m                                  -- Result: Just "one"
view (at 3) m                                  -- Result: Nothing

-- Insert with at
set (at 3) (Just "three") m                    -- Result: fromList [(1,"one"),(2,"two"),(3,"three")]

-- Delete with at
set (at 1) Nothing m                           -- Result: fromList [(2,"two")]

-- Using ?~ operator for insertion
Map.empty & at 1 ?~ "hello"                    -- Result: fromList [(1,"hello")]

-- sans: delete helper
sans 1 m                                       -- Result: fromList [(2,"two")]

-- contains: for Set membership
IntSet.fromList [1, 2, 3, 4] ^. contains 3     -- Result: True
IntSet.fromList [1, 2, 3, 4] & contains 3 .~ False
-- Result: fromList [1, 2, 4]

-- Nested map access with non
Map.empty & at "outer" % non Map.empty % at "inner" ?~ "value"
-- Result: fromList [("outer", fromList [("inner", "value")])]
```

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

### Traversal: Accessing Multiple Elements in Haskell

Source: https://context7.com/well-typed/optics/llms.txt

Explains the use of Traversals for accessing zero or more elements within a structure, supporting effectful updates. Covers `traversed` for any Traversable, `each` for tuples, `both` for Bitraversables, `partsOf` to convert traversals to lenses, `backwards` for reverse traversal, `adjoin` for combining traversals, `singular` for the first element, and `failover` for handling missing targets.

```haskell
import Optics
import Data.List (sort)

-- traversed: traverse any Traversable
toLisOf traversed [1, 2, 3]                    -- Result: [1, 2, 3]
over traversed (*10) [1, 2, 3]                  -- Result: [10, 20, 30]

-- Effectful traversal
traverseOf traversed print [1, 2, 3]
-- Output: 1
--         2
--         3
-- Result: [(), (), ()]

-- each: traverse elements of tuples
over each (*10) (1, 2, 3)                       -- Result: (10, 20, 30)
toLisOf each ('a', 'b', 'c')                   -- Result: "abc"

-- both: traverse both elements of Bitraversable
over both length ("hello", "world")            -- Result: (5, 5)
(1, 2) & both %~ (*10)                         -- Result: (10, 20)

-- partsOf: convert traversal to lens over list
('a', 'b', 'c') & partsOf each .~ ['x', 'y', 'z']  -- Result: ('x', 'y', 'z')
('b', 'a', 'd', 'c') & partsOf each %~ sort        -- Result: ('a', 'b', 'c', 'd')

-- backwards: traverse in reverse order
toLisOf (backwards traversed) [1, 2, 3]       -- Result: [3, 2, 1]

-- adjoin: combine disjoint traversals
over (_1 % _Just `adjoin` _2 % _Right) not (Just True, Right False)
-- Result: (Just False, Right True)

-- singular: take first element only
"foo" & singular traversed .~ 'z'              -- Result: "zoo"

-- failover: returns Nothing if no targets
failover (ix 3) (*2) [1, 2]                    -- Result: Nothing
failover _Right (*2) (Right 4)                 -- Result: Just (Right 8)
```

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

### Getter - Function as Optic (Haskell)

Source: https://context7.com/well-typed/optics/llms.txt

A Getter wraps a function s -> a as an optic, enabling composition with other optics for read-only access. This snippet shows how to create getters using 'to' and compose them with other optics.

```haskell
import Optics

-- to: build getter from function
view (to length) "hello"                       -- Result: 5
view (to fst) (1, 2)                       -- Result: 1

-- Compose getters
data Person = Person { personAge :: Int, personName :: String }

ageLens :: Lens' Person Int
ageLens = lens personAge (p a -> p { personAge = a })

-- Compose lens with getter
view (ageLens % to show) (Person 25 "Alice")   -- Result: "25"
view (ageLens % to (*2)) (Person 25 "Alice")   -- Result: 50

-- views: apply function to viewed value
views _1 length ("hello", "world")             -- Result: 5

-- Getters from multiple sources
data Point = Point { _px :: Double, _py :: Double }

magnitude :: Getter Point Double
magnitude = to $ (Point x y) -> sqrt (x*x + y*y)

view magnitude (Point 3 4)                     -- Result: 5.0
```

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

### Fold - Extract Multiple Elements (Haskell)

Source: https://context7.com/well-typed/optics/llms.txt

A Fold is a read-only optic that extracts zero or more elements from a structure, similar to Foldable. It cannot modify elements. This snippet demonstrates various fold operations like toListOf, sumOf, anyOf, headOf, findOf, and foldMapOf.

```haskell
import Optics

-- folded: fold any Foldable
toiListOf folded [1, 2, 3]                      -- Result: [1, 2, 3]
lengthOf folded [1, 2, 3, 4, 5]                -- Result: 5

-- Fold operations
sumOf folded [1, 2, 3, 4]                      -- Result: 10
productOf folded [1, 2, 3, 4]                  -- Result: 24
maximumOf folded [3, 1, 4, 1, 5]               -- Result: Just 5
minimumOf folded [3, 1, 4, 1, 5]               -- Result: Just 1

-- Boolean folds
anyOf folded even [1, 2, 3]                    -- Result: True
allOf folded even [2, 4, 6]                    -- Result: True
has _Left (Left 'x')                           -- Result: True
hasn't _Left (Right 'y')                       -- Result: True

-- headOf and lastOf
headOf folded [1, 2, 3]                        -- Result: Just 1
lastOf folded [1, 2, 3]                        -- Result: Just 3

-- findOf: find first matching element
findOf folded even [1, 3, 4, 6]                -- Result: Just 4

-- foldMapOf: custom monoidal fold
foldMapOf folded show [1, 2, 3]                -- Result: "123"

-- folding: build fold from function returning Foldable
toiListOf (folding (drop 2)) [1, 2, 3, 4, 5]    -- Result: [3, 4, 5]

-- summing: combine two folds
toiListOf (_1 % ix 0 `summing` _2 % ix 1) ([1, 2], [4, 7, 1])
-- Result: [1, 7]

-- failing: fallback if first returns nothing
toiListOf (ix 1 `failing` ix 0) [4, 7]          -- Result: [7]
toiListOf (ix 1 `failing` ix 0) [4]             -- Result: [4]

-- Compose with other optics
toiListOf (_1 % folded % _Right) ([Right 'h', Left 5, Right 'i'], "bye")
-- Result: "hi"
```

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

### Setter - Modify Multiple Elements (Haskell)

Source: https://context7.com/well-typed/optics/llms.txt

A Setter provides the ability to modify all elements targeted by an optic without necessarily being able to read them. It's the write-only counterpart to Fold. This snippet demonstrates 'over', 'sets', and operator-based modifications.

```haskell
import Optics

-- mapped: create setter from Functor
over mapped (*2) [1, 2, 3]                     -- Result: [2, 4, 6]
over mapped (+1) (Just 5)                      -- Result: Just 6

-- sets: build setter from modification function
plusOne :: Setter' [Int] Int
plusOne = sets map

over plusOne (+1) [1, 2, 3]                    -- Result: [2, 3, 4]

-- Strict versions
set' _1 'x' ('a', 'b')                         -- Strict set
over' _1 succ (1, 2)                           -- Strict over

-- Using operators
[1, 2, 3] & mapped %~ (*2)                     -- Result: [2, 4, 6]
[1, 2, 3] & mapped .~ 0                        -- Result: [0, 0, 0]

-- Deep modification with composition
data Company = Company { employees :: [Person] }
data Person = Person { name :: String, salary :: Int }

-- Increase all salaries by 10%
-- company & employees % traversed % salaryLens %~ (\s -> s + s `div` 10)

-- transformOf: recursive transformation
-- rewriteOf: rewrite until fixed point
```
Tokens:
Raw