A Lens is a generalized getter and setter.

Lenses allow both the retrieval of values from fields in a record and the assignment of values to fields in a record. The power of a Lens comes from its ability to be composed with other lenses.

In the context of building applications with miso, the model is often a deeply nested product type. This makes it highly conducive to Lens operations (as defined below).

LensCore is an internal type used to reverse composition like VL libraries do.

A Prism is a first-class reference into a sum type constructor.

Prism values can be used with preview to try to extract a value, and with review to embed a value back into the sum type.

Smart constructor lens function. Used to easily construct a Lens

name :: 'Lens' Person String
name = 'lens' _name $ \p n -> p { _name = n }

Smart constructor for Prism.

& 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 $.

This is a version of flip id, where id is specialized from a -> a to (a -> b) -> (a -> b) which by the associativity of (->) is (a -> b) -> a -> b. flipping this yields a -> (a -> b) -> b which is the type signature of &

Examples

>>> 5 & (+1) & show
"6"

>>> sqrt $ [1 / n^2 | n <- [1..1000]] & sum & (*6)
3.1406380562059946

Since: base-4.8.0.0

Flipped version of <$>.

(<&>) = flip fmap

Examples

>>> Just 2 <&> (+1)
Just 3

>>> [1,2,3] <&> (+1)
[2,3,4]

>>> Right 3 <&> (+1)
Right 4

Since: base-4.11.0.0

Set a field on a record

newtype Person = Person { _name :: String }

name :: Lens Person String
name = lens _name $ \person n -> person { _name = n }

setName :: Person -> String -> Person
setName person newName = person & name .~ newName

Set an options field on a record

newtype Person = Person { _name :: Maybe String }

name :: Lens Person (Maybe String)
name = lens _name $ \person n -> person { _name = n }

setName :: Person -> String -> Person
setName person newName = person & name ?~ newName

Synonym for (.~)

Modify a field on a record by applying a function to it.

newtype Counter = Counter { _value :: Int }

value :: Lens Counter Int
value = lens _value $ \counter v -> counter { _value = v }

increment :: Counter -> Counter
increment counter = counter & value %~ (+1)

Synonym for (%~)

Read a field from a record using a Lens

newtype Person = Person { _name :: String }
  deriving (Show, Eq)

name :: Lens Person String
name = lens _name $ \person n -> person { _name = n }

getName :: Person -> String
getName = person ^. name

Increment a Num field => field on a record using a Lens

newtype Person = Person { _age :: Int }

age :: Lens Person Int
age = lens _age $ \person a -> person { _age = a }

birthday :: Person -> Person
birthday person = person & age +~ 1

Multiply a Numeric field on a record using a Lens

newtype Circle = Circle { _radius :: Int }

radius :: Lens Circle Int
radius = lens _radius $ \circle r -> circle { _radius = r }

expand :: Circle -> Circle
expand circle = circle & radius *~ 10

Divide a Fractional field on a record using a Lens

newtype Circle = Circle { _radius :: Int }

radius :: Lens Circle Int
radius = lens _radius $ \circle r -> circle { _radius = r }

shrink :: Circle -> Circle
shrink circle = circle & radius //~ 10

Increment a Numeric field on a record using a Lens

newtype Person = Person { _age :: Int }

age :: Lens Person Int
age = lens _age $ \person a -> person { _age = a }

timeTravel :: Person -> Person
timeTravel person = person & age -~ 1

Modify a record in MonadState monad at a field using a Lens

newtype Model = Model { _value :: Int }

data Action = AddOne | SubtractOne

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update AddOne = do
  value %= (+1)

Alters the Just value of a field in a record using a Lens inside a MonadState

newtype Model = Model { _value :: Maybe Int }
  deriving (Show, Eq)

data Action = IncrementIfJust

value :: Lens Model (Maybe Int)
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update IncrementIfJust = value %?= (+1)

Synonym for (%=)

Increments the value of a Numeric field of a record using a Lens inside a State Monad.

newtype Model = Model { _value :: Int }
  deriving (Show, Eq)

data Action = IncrementBy Int

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (IncrementBy x) = value += x

Multiplies the value of a Numeric field of a record using a Lens inside a State Monad.

newtype Model = Model { _value :: Int }
  deriving (Show, Eq)

data Action = MultiplyBy Int

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (MultiplyBy x) = value *= x

Divides the value of a Fractional field of a record using a Lens inside a State Monad.

newtype Model = Model { _value :: Double }
  deriving (Show, Eq)

data Action = DivideBy Double

value :: Lens Model Double
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (DivideBy x) = value //= x

Subtracts the value of a Numeric field of a record using a Lens inside of a State Monad.

newtype Model = Model { _value :: Double }
  deriving (Show, Eq)

data Action = SubtractBy Double

value :: Lens Model Double
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (SubtractBy x) = value -= x

Sets the value of a field in a record using MonadState and a Lens

newtype Model = Model { _value :: Int }
  deriving (Show, Eq)

data Action = SetValue Int

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update' :: Action -> Effect parent Model Action
update' (SetValue v) = value .= v

Execute a monadic action in MonadState that returns a field. Sets the return value equal to the field in the record.

As a reasonable mnemonic, this lets you store the result of a monadic action in a Lens rather than in a local variable.

do foo <- bar
   ...

will store the result in a variable, while

do fooLens <~ bar
   ...

will store the result in field focused by the Lens.

Modify the field of a record in MonadState using a Lens, then return the newly modified field from the updated record.

import Miso.String (ms)

newtype Model = Model { _value :: Int }
  deriving (Show)

data Action = AddOne

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update AddOne = do
  result <- value <%= (+1)
  io_ $ consoleLog (ms result)

Assign the field of a record in MonadState to a value using a Lens Return the value after assignment.

import Miso.String (ms)

newtype Model = Model { _value :: Int }

data Action = Assign Int

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (Assign x) = do
  result <- value <.= x
  io_ $ consoleLog (ms result) -- x

Assign the field of a record in a MonadState to a value (wrapped in a Just) using a Lens. Return the value after assignment.

import Miso.String (ms)

newtype Model = Model { _value :: Maybe Int }

data Action = SetValue Int

value :: Lens Model (Maybe Int)
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (SetValue x) = do
  result <- value <?= x
  io_ $ consoleLog (ms result) -- Just 1

Assign the field of a record in a MonadState to a value using a Lens. Returns the previous value, before assignment.

import Miso.String (ms)

newtype Model = Model { _value :: Int }
  deriving (Show, Eq)

data Action = Assign Int
  deriving (Show, Eq)

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (Assign x) = do
  value .= x
  previousValue <- value <<.= 1
  io_ $ consoleLog $ ms previousValue -- prints value at x

Modifies the field of a record in MonadState using a Lens. Returns the previous value, before modification.

import Miso.String (ms)

newtype Model = Model { _value :: Int }
  deriving (Show, Eq)

data Action = Modify (Int -> Int)

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (Modify f) = do
  value .= 2
  result <- value <<%= f
  io_ $ consoleLog (ms result) -- prints previous value of 2

Synonym for (.=)

Retrieves the value of a field in a record using a Lens inside MonadState

import Miso.String (ms)

newtype Model = Model { _value :: Int }
  deriving (Show, Eq)

data Action = SetValue Int

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (SetValue x) = do
  value .= x
  result <- use value
  io_ $ consoleLog (ms result) -- prints the value of x

Retrieves the field associated with a record in MonadReader using a Lens.

import Miso.String (ms)

newtype Model = Model { _value :: Int }
  deriving (Show, Eq)

data Action = PrintInt

value :: Lens Model Int
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update PrintInt = do
  Model x <- view value
  io_ $ consoleLog (ms x) -- prints model value

Sets the value of a field in a record using a Lens inside a MonadState The value is wrapped in a Just before being assigned.

newtype Model = Model { _value :: Maybe Int }
  deriving (Show, Eq)

data Action = AssignValue Int

value :: Lens Model (Maybe Int)
value = lens _value $ \p x -> p { _value = x }

update :: Action -> Effect parent Model Action
update (AssignValue x) = value ?= x

Monoidally append a field in a record using a Lens

newtype List = List { _values :: [Int] }

values :: Lens List [Int]
values = lens _values $ \l vs -> l { _values = vs }

addElement :: List -> List
addElement list = list & values <>~ [2]

addElement (List [])
-- List [2]

Lens that operates on the first element of a tuple

update AddOne = do
  _1 += 1

Lens that operates on the second element of a tuple

update AddOne = do
  _2 += 1

Lens that operates on itself

update AddOne = do
  _id += 1

Lens that operates on itself

update AddOne = do
  this += 1

Try to extract a value from a sum type using a Prism inside MonadReader.

Try to extract a value from a sum type using a Prism inside MonadState.

Embed a value into a sum type using a Prism.

Prism that matches a Nothing value.

Prism for the Just constructor of Maybe.

Prism for the Left constructor of Either.

Prism for the Right constructor of Either.

Infix alias for preview. Try to extract a value using a Prism.

Right 42 ^? _Right == Just 42
Left  "x" ^? _Right == Nothing

Class for getting and setting values across various container types.

M.singleton 'a' "foo" & at 'a' .~ Just "bar"
-- fromList [('a',"bar")]

update (SetValue value)
  at 10 ?= value

Since: 1.9.0.0

Function composition generalized to Category

test :: Int -> Int
test = (+1) `compose` (+1)

van Laarhoven formulation, used for conversion w/ miso Lens.

Convert a Lens to a van Laarhoven Lens'

Convert a van Laarhoven Lens' to a Lens