Prism

A Prism is an optic used to select part of a Sum type (also known as Coproduct), e.g. sealed trait or Enum.

Prisms have two type parameters generally called S and A: Prism[S, A] where S represents the Sum and A a part of the Sum.

Let's take a simplified Json encoding:

sealed trait Json
case object JNull extends Json
case class JStr(v: String) extends Json
case class JNum(v: Double) extends Json
case class JObj(v: Map[String, Json]) extends Json

We can define a Prism which only selects Json elements built with a JStr constructor by supplying a pair of functions:

  • getOption: Json => Option[String]
  • reverseGet (aka apply): String => Json
import monocle.Prism

val jStr = Prism[Json, String]{
  case JStr(v) => Some(v)
  case _       => None
}(JStr)

It is common to create a Prism by pattern matching on constructor, so we also added partial which takes a PartialFunction:

val jStr = Prism.partial[Json, String]{case JStr(v) => v}(JStr)

We can use the supplied getOption and apply methods as constructor and pattern matcher for JStr:

jStr("hello")
// res0: Json = JStr(v = "hello")

jStr.getOption(JStr("Hello"))
// res1: Option[String] = Some(value = "Hello")
jStr.getOption(JNum(3.2))
// res2: Option[String] = None

A Prism can be used in a pattern matching position:

def isLongString(json: Json): Boolean = json match {
  case jStr(v) => v.length > 100
  case _       => false
}

We can also use replace and modify to update a Json only if it is a JStr:

jStr.replace("Bar")(JStr("Hello"))
// res3: Json = JStr(v = "Bar")
jStr.modify(_.reverse)(JStr("Hello"))
// res4: Json = JStr(v = "olleH")

If we supply another type of Json, replace and modify will be a no operation:

jStr.replace("Bar")(JNum(10))
// res5: Json = JNum(v = 10.0)
jStr.modify(_.reverse)(JNum(10))
// res6: Json = JNum(v = 10.0)

If we care about the success or failure of the update, we can use replaceOption or modifyOption:

jStr.modifyOption(_.reverse)(JStr("Hello"))
// res7: Option[Json] = Some(value = JStr(v = "olleH"))
jStr.modifyOption(_.reverse)(JNum(10))
// res8: Option[Json] = None

As all other optics Prisms compose together:

import monocle.std.double.doubleToInt // Prism[Double, Int] defined in Monocle

val jNum: Prism[Json, Double] = Prism.partial[Json, Double]{case JNum(v) => v}(JNum)

val jInt: Prism[Json, Int] = jNum.andThen(doubleToInt)

jInt(5)
// res9: Json = JNum(v = 5.0)

jInt.getOption(JNum(5.0))
// res10: Option[Int] = Some(value = 5)
jInt.getOption(JNum(5.2))
// res11: Option[Int] = None
jInt.getOption(JStr("Hello"))
// res12: Option[Int] = None

Prism Generation

Generating Prisms for subclasses is fairly common, so we added a macro to simplify the process. All macros are defined in a separate module (see modules).

import monocle.macros.GenPrism

val rawJNum: Prism[Json, JNum] = GenPrism[Json, JNum]

rawJNum.getOption(JNum(4.5))
// res13: Option[JNum] = Some(value = JNum(v = 4.5))
rawJNum.getOption(JStr("Hello"))
// res14: Option[JNum] = None

If you want to get a Prism[Json, Double] instead of a Prism[Json, JNum], you can compose GenPrism with GenIso (see Iso documentation):

import monocle.macros.GenIso

val jNum: Prism[Json, Double] = GenPrism[Json, JNum].andThen(GenIso[JNum, Double])

val jNull: Prism[Json, Unit] = GenPrism[Json, JNull.type].andThen(GenIso.unit[JNull.type])

A ticket currently exists to add a macro to merge these two steps together.

Prism Laws

A Prism must satisfy all properties defined in PrismLaws from the core module. You can check the validity of your own Prisms using PrismTests from the law module.

In particular, a Prism must verify that getOption and reverseGet allow a full round trip if the Prism matches i.e. if getOption returns a Some.

def partialRoundTripOneWay[S, A](p: Prism[S, A], s: S): Boolean =
  p.getOption(s) match {
    case None    => true // nothing to prove
    case Some(a) => p.reverseGet(a) == s
  }
  
def partialRoundTripOtherWay[S, A](p: Prism[S, A], a: A): Boolean =
  p.getOption(p.reverseGet(a)) == Some(a)
← LensOptional →