Monocle Documentation

Monocle is split into several modules to allow for selective dependency inclusion:

• core: Contains the primary optics (e.g., Lens, Prism, Traversal) and type class definitions (e.g., Index, Each, Plated), along with instances for standard library and cats data types.
• macro: Provides macros to simplify the generation of optics.
• laws: Contains laws for the optics and type classes.
• refined: Provides optics and type class instances for use with refined refinement types.
• generic (deprecated): Optics and type class instances for HList and Coproduct from shapeless.
• state (deprecated): Provides conversion between optics and State or Reader.
• unsafe (deprecated): Provides optics that do not fully satisfy laws but offer high convenience.
• tests: Contains tests to verify that optics and type class instances satisfy their laws.
• bench: Contains JMH benchmarks for measuring optics performance.
• docs: Source for the Monocle documentation website.

An Iso is an optic that provides a lossless, symmetric transformation between two types S and A. It is defined by two total functions:

1. get: S => A
2. reverseGet (also accessible via apply): A => S

Because the transformation is symmetric, you can use .reverse to flip the direction of the Iso.

Common use cases include:

• Converting between a case class and its tuple representation.
• Converting between different collection types (e.g., List[A] and Vector[A]).
• Lifting functions from one type to another (e.g., using a String as a List[Char]).

import monocle.Iso

// Manual creation between Person and (String, Int)
val personToTuple = Iso[Person, (String, Int)](p => (p.name, p.age)){case (name, age) => Person(name, age)}

personToTuple.get(Person("Zoe", 25))
personToTuple(("Zoe", 25)) // Using apply as reverseGet

// Reversing an Iso
def listToVector[A] = Iso[List[A], Vector[A]](_.toVector)(_.toList)
def vectorToList[A] = listToVector[A].reverse

// Lifting functions
val stringToList = Iso[String, List[Char]](_.toList)(_.mkString(""))
stringToList.modify(_.tail)("Hello")

An Optional[S, A] is an optic used to zoom into a Product (such as a case class, Tuple, HList, or Map) where the target element A may or may not exist within the source S.

Unlike a Lens, which assumes the target is always present, an Optional handles the possibility of absence using Option semantics. To create an Optional, you must provide two functions:

1. getOption: S => Option[A]: How to retrieve the target element if it exists.
2. replace: A => S => S: How to replace the target element within the source structure.

Common use cases include accessing the head of a List or a specific key in a Map that might be missing.

import monocle.Optional

// Example: An Optional that focuses on the head of a List[Int]
val head = Optional[List[Int], Int] {
  case Nil => None
  case x :: xs => Some(x)
}{
   a => {
     case Nil => Nil
     case x :: xs => a :: xs
   }
}

A Lens[S, A] is an optic used to zoom into a Product (like a case class, Tuple, HList, or Map) to focus on an element of type A within a structure of type S.

To manually create a Lens, you provide a get function and a replace function:

val streetNumber = Lens[Address, Int](_.streetNumber)(n => a => a.copy(streetNumber = n))

Once created, you can use the following methods:

• get(s: S): A: Retrieves the focused value.
• replace(a: A)(s: S): S: Replaces the focused value with a new one.
• modify(f: A => A)(s: S): S: Updates the focused value using a function (equivalent to get followed by replace).
• modifyF(f: A => F[A])(s: S): F[S]: Updates the focused value within a context F (requires a Functor instance for F). This is useful for asynchronous updates (e.g., using Future).
• andThen(other: Lens[A, B]): Lens[S, B]: Composes the current lens with another to zoom deeper into the structure.

val address = Address(10, "High Street")

streetNumber.get(address)
streetNumber.replace(5)(address)
streetNumber.modify(_ + 1)(address)

Lenses can be composed to navigate through nested data structures or to chain modifications.

Using andThen for deep zooming

Use andThen to combine a lens that focuses on a field with a lens that focuses on a field within that field:

val addressLens = GenLens[Person](_.address)
val streetLens = GenLens[Address](_.streetName)

addressLens.andThen(streetLens).get(john)

Using compose for function composition

You can compose the modification logic of multiple lenses using compose:

import monocle.macros.syntax.lens._

// Using syntax for a more fluent API
john.lens(_.name).replace("Mike").lens(_.age).modify(_ + 1)

Composing Lens with Prism for Optional fields

If you need to update a Product type inside a Sum type (e.g., an Option), compose a Prism with a Lens using the some method:

import monocle.macros.GenLens

case class B(c: Int)
case class A(b: Option[B])

val c = GenLens[B](_.c)
val b = GenLens[A](_.b)

b.some.andThen(c).getOption(A(Some(B(1))))

address.andThen(streetNumber).get(john)
address.andThen(streetNumber).replace(2)(john)

In Monocle, both at and index are used to define indexed optics, but they differ in their strength and capabilities:

• index (an Optional): Can only update or access values that already exist at a specific key or position. It cannot insert new elements or delete existing ones. Because it is "weaker," it can be implemented for more data structures (e.g., List or Vector have Index but not At, because you cannot insert at an arbitrary index in a sequence).
• at (a Lens): A "stronger" optic that allows for full CRUD-like operations on a key. It can update existing values, insert new elements (by replacing a missing key with Some(value)), and delete elements (by replacing an existing key with None).

import monocle.Iso

val m = Map("one" -> 1, "two" -> 2)
val root = Iso.id[Map[String, Int]]

// index: updates existing, no-op if missing
root.index("two").replace(0)(m)   // update value at index "two"
root.index("three").replace(3)(m) // noop because m doesn't have a value at "three"

// at: insert, delete, or upsert
root.at("three").replace(Some(3))(m)  // insert element at "three"
root.at("two").replace(None)(m)       // delete element at "two"
root.at("two").replace(Some(0))(m)    // upsert element at "two"