Optic

zio.blocks.schema.Optic

sealed trait Optic[S, A]

An optic is a first-class path into a value of type S that focuses on parts of type A. It reads, replaces and modifies those parts without rebuilding the enclosing value by hand. It also carries the schemas of both ends (source and focus), so a failed access can say where and why it failed, and the path can be turned into a DynamicOptic or a SchemaExpr query.

Every optic is one of four kinds:

Lens: a part that is always there, such as a field of a case class;
Prism: one case of a sealed trait or enum;
Optional: a part that may be missing, such as a field inside one case, the element at an index or the value at a map key;
Traversal: zero or more parts, such as every element of a collection.

Get optics from the $ (or optic) macro of CompanionOptics, or from the optics member of DerivedOptics. Compose them with apply. Two lenses give a lens, two prisms give a prism, anything composed with a traversal gives a traversal, and every other pair gives an optional.

This trait has the operations that every kind supports: modify, modifyOption, modifyOrFail, check and toDynamic, plus operators such as ===, >, + and && that build a SchemaExpr. Reading and replacing depend on the kind: get and replace on Lens, getOption and replace on Prism and Optional, and fold on Traversal.

case class Author(name: String)
case class Book(title: String, author: Author)
object Book extends CompanionOptics[Book] {
 implicit val schema: Schema[Book] = Schema.derived
 val authorName: Lens[Book, String] = $(_.author.name)
}

val zionomicon = Book("Zionomicon", Author("John A. De Goes"))
Book.authorName.modify(zionomicon, _.toUpperCase) // Book(Zionomicon,Author(JOHN A. DE GOES))
Book.authorName.toDynamic.toString                 // .author.name

Type parameters

A: the type of the parts it focuses on
S: the type of the value the optic reads from and updates

Attributes

See also: Optics
Source: Optic.scala
Graph
Supertypes: class Object

trait Matchable

class Any
Known subtypes: trait Lens[S, A]

trait Optional[S, A]

trait Prism[S, A]

trait Traversal[S, A]
Self type: Optic[S, A]

Members list

Value members

Abstract methods

Composes this optic with a lens on its focus. The result focuses on the lens's focus B inside every part this optic focuses on. It is a Lens when this optic is a lens, a Traversal when this optic is a traversal, and an Optional otherwise.

case class Author(name: String)
object Author extends CompanionOptics[Author] {
 implicit val schema: Schema[Author] = Schema.derived
 val name: Lens[Author, String] = $(_.name)
}
case class Book(title: String, author: Author)
object Book extends CompanionOptics[Book] {
 implicit val schema: Schema[Book] = Schema.derived
 val author: Lens[Book, Author] = $(_.author)
}

val authorName: Lens[Book, String] = Book.author(Author.name)
authorName.get(Book("Zionomicon", Author("John A. De Goes"))) // "John A. De Goes"

Attributes

Source: Optic.scala

Composes this optic with a prism on its focus. The result is a Prism when this optic is a prism, a Traversal when this optic is a traversal, and an Optional otherwise.

Attributes

Source: Optic.scala

Composes this optic with an optional on its focus. The result is a Traversal when this optic is a traversal, and an Optional otherwise.

Attributes

Source: Optic.scala

Composes this optic with a traversal on its focus. The result is always a Traversal.

Attributes

Source: Optic.scala

Returns None when this optic reaches its focus in s, and otherwise an OpticCheck that says why not. The possible problems are another case of a variant, a wrapper whose unwrap throws a SchemaError (both errors), an index past the end, a missing map key, an empty collection, and, for searchFor, no match at all (all four warnings). Except for searchFor, which decodes every candidate with its schema, check never runs a wrapper's wrap, so it does not see failures that only replace or modify meet.

A Lens always returns None. A Prism and an Optional report the first problem on the path. A Traversal reports the problems in every branch it visits, even when it reaches other parts: atIndices(0, 2) on a one-element list reports index 2.

Attributes

Source: Optic.scala

The schema of the parts this optic focuses on. For a composed optic, it is the focus of the last step.

Attributes

Source: Optic.scala

Returns s with f applied to every part this optic focuses on. When there is nothing to focus on, the result equals s: a Prism on another case, an Optional on a missing index or key, a Traversal over an empty collection. It also equals s when a wrapped step on the path throws a SchemaError, including one that f throws below that step (a bug, see docs/dev/issues.md); other exceptions, from the path or from f, propagate. modifyOption and modifyOrFail say when nothing was modified.

case class Book(title: String, tags: List[String])
object Book extends CompanionOptics[Book] {
 implicit val schema: Schema[Book] = Schema.derived
 val tags: Traversal[Book, String] = $(_.tags.each)
}

Book.tags.modify(Book("Zionomicon", List("zio", "scala")), _.toUpperCase)
// Book(Zionomicon,List(ZIO, SCALA))

Attributes

Source: Optic.scala

Like modify, but returns None instead of an unchanged value when there is nothing to focus on, and when a wrapped step on the path throws a SchemaError, including one that f throws below that step (a bug, see docs/dev/issues.md). A Lens always returns Some.

Attributes

Source: Optic.scala

Like modify, but returns Left with an OpticCheck that says why nothing was modified, as check does, and a OpticCheck.WrappingError when a wrapped step on the path throws a SchemaError, including one that f throws below that step (a bug, see docs/dev/issues.md). A Lens always returns Right. A Traversal returns Right once it has modified at least one part, even when other parts are missing; check reports those.

Attributes

Source: Optic.scala

The schema of the value this optic starts from. For a composed optic, it is the source of the first step.

Attributes

Source: Optic.scala

Returns the path of this optic as a DynamicOptic, with one node per step. For example, $(_.format.when[Paperback].pages).toDynamic.toString is .format.pages.

Attributes

Source: Optic.scala

Concrete methods

Builds a SchemaExpr that is true where the focus of this optic differs from the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic differs from the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the remainder of this optic's numeric focus divided by the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the bitwise and of this optic's integral focus and the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the logical and of this optic's Boolean focus and the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the logical and of this optic's Boolean focus and the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's numeric focus times the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's numeric focus plus the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's numeric focus minus the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's numeric focus divided by the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is less than the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is less than the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's integral focus shifted left by the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is less than or equal to the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is less than or equal to the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic equals the literal that. Evaluate it on an S with SchemaExpr#eval.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic equals the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is greater than the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is greater than the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is greater than or equal to the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr that is true where the focus of this optic is greater than or equal to the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's integral focus shifted right by the literal that, keeping the sign.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's integral focus shifted right by the literal that, filling with zeros.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the bitwise exclusive or of this optic's integral focus and the literal that.

Attributes

Source: Optic.scala

Returns this optic with its focus type changed to B, which ev proves is the same type. The optic is cast, not copied.

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's String focus followed by the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the length of this optic's String focus.

Attributes

Source: Optic.scala

Composes this optic, whose focus is a List, with a traversal over every element of that list.

Attributes

Throws: java.lang.RuntimeException
("Expected List") if the focus schema is not a List sequence schema
Source: Optic.scala

Builds a SchemaExpr that is true where this optic's String focus matches the Java regular expression that as a whole (java.util.regex.Pattern.matches).

Attributes

Source: Optic.scala

Builds a SchemaExpr for this optic's numeric focus raised to the power of the literal that.

Attributes

Source: Optic.scala

Composes this optic, whose focus is a Set, with a traversal over every element of that set.

Attributes

Throws: java.lang.RuntimeException
("Expected Set") if the focus schema is not a Set sequence schema
Source: Optic.scala

Builds a SchemaExpr for the negation of this optic's Boolean focus.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the bitwise complement of this optic's integral focus.

Attributes

Source: Optic.scala

Composes this optic, whose focus is a Vector, with a traversal over every element of that vector.

Attributes

Throws: java.lang.RuntimeException
("Expected Vector") if the focus schema is not a Vector sequence schema
Source: Optic.scala

Builds a SchemaExpr for the bitwise or of this optic's integral focus and the literal that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the logical or of this optic's Boolean focus and the focus of that.

Attributes

Source: Optic.scala

Builds a SchemaExpr for the logical or of this optic's Boolean focus and the literal that.

Attributes

Source: Optic.scala

In this article