com.mojang.datafixers.optics

Interface Optic<Proof extends K1,S,T,A,B>

Type Parameters:

Proof - The Profunctor type this optic evaluates.

S - The input object type.

T - The output object type.

A - The input field type.

B - The output field type.

All Known Subinterfaces:

Adapter<S,T,A,B>, Affine<S,T,A,B>, Lens<S,T,A,B>, Prism<S,T,A,B>, Traversal<S,T,A,B>

All Known Implementing Classes:

Inj1, Inj2, InjTagged, ListTraversal, Optic.CompositionOptic, Proj1, Proj2

public interface Optic<Proof extends K1,S,T,A,B>

An optic is a generic tool used to inspect and modify part of a structure. Optics typically encapsulate a "getter" and a "setter" for some (possibly nested) field in an immutable data structure. The strength of optics lies in the fact that they are composable: they can be combined in order to "focus" on a specific sub-component of a structure, with complete disregard to the remainder of the structure.

An optic can be thought to take some transformation S -> T between object types and another (unrelated) transformation A -> B between field types, and produces a new transformation between object types such that the field A in S is transformed into B using the field function, while the rest of S is transformed using the original function.

The object type is also known as a source, and the field type is also known as a focus. The terms "object" and "field" are used throughout in this documentation in order to draw a parallel to the object-oriented paradigm. Note, however, that an optic need not act on a literal field of a conventional object. Also note that optics need not act on a single field, depending on the profunctor this optic takes its behavior from.

Type Shape:

%.Type.[%0,%1::%3,%2::%4]

See Also:

Profunctor, An Introduction to Optics: Lenses and Prisms

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Optic.CompositionOptic<Proof extends K1,S,T,A,B,A1,B1> An optic that represents the composition of two compatible optics.

Method Summary

Modifier and Type	Method and Description
default <Proof2 extends Proof,A1,B1> Optic<Proof2,S::A1,T::B1>	compose(Optic<? super Proof2,A::A1,B::B1> optic) Composes this optic with another optic that operates on the field types of this optic.
default <Proof2 extends K1,A1,B1> Optic<?,S::A1,T::B1>	composeUnchecked(Optic<?,A::A1,B::B1> optic) Composes this optic with another optic that operates on the field types of this optic without checking for type compatibility.
<P extends K2> (P<A,B>) -> P<S,T>	eval(? extends Proof<P> proof) Applies the given Profunctor to this optic to produce a function that converts a transformation between the field types into a transformation between the object types.
default <Proof2 extends K1> Optional<Optic<? super Proof2,S::A,T::B>>	upCast(Set<TypeToken<? extends K1>> proofBounds, TypeToken<Proof2> proof) Refines the profunctor type accepted by this optic to the given type, checking against the given bounds.

Method Detail

eval

<P extends K2> (P<A,B>) -> P<S,T> eval(? extends Proof<P> proof)

Applies the given Profunctor to this optic to produce a function that converts a transformation between the field types into a transformation between the object types.

Type Parameters:

P - The type associated with the profunctor.

Parameters:

proof - The profunctor associated with this optic.

Returns:

A function that ultimately transforms the input object into the output object, given a transformation from the input field to the output field.

compose

default <Proof2 extends Proof,A1,B1> Optic<Proof2,S::A1,T::B1> compose(Optic<? super Proof2,A::A1,B::B1> optic)

Composes this optic with another optic that operates on the field types of this optic. This allows, for example, to combine an optic for a field in some object with an optic for a subfield of that field.

Implementation Requirements:

The default implementation returns a Optic.CompositionOptic.

Type Parameters:

Proof2 - The profunctor type class of the given optic.

A1 - The subfield input type.

B1 - The subfield output type.

Parameters:

optic - The subfield optic.

Returns:

An optic operating on the original object, but for the subfields.

See Also:

Optic.CompositionOptic

composeUnchecked

default <Proof2 extends K1,A1,B1> Optic<?,S::A1,T::B1> composeUnchecked(Optic<?,A::A1,B::B1> optic)

Composes this optic with another optic that operates on the field types of this optic without checking for type compatibility. This allows, for example, to combine an optic for a field in some object with an optic for a subfield of that field.

Warning: This method is unsound. Care must be taken that the profunctor types for this optic and the given optic actually have a common descendant.

Implementation Requirements:

The default implementation returns a Optic.CompositionOptic.

Type Parameters:

Proof2 - The profunctor common descendant for this and the given optic.

A1 - The subfield input type.

B1 - The subfield output type.

Parameters:

optic - The subfield optic.

Returns:

An optic operating on the original object, but for the subfields.

See Also:

compose(Optic), Optic.CompositionOptic

upCast

default <Proof2 extends K1> Optional<Optic<? super Proof2,S::A,T::B>> upCast(Set<TypeToken<? extends K1>> proofBounds,
                                                                             TypeToken<Proof2> proof)

Refines the profunctor type accepted by this optic to the given type, checking against the given bounds.

Type Parameters:

Proof2 - The refined profunctor type.

Parameters:

proofBounds - The lower bounds of Proof2.

proof - The type tag for the refined profunctor type.

Returns:

This optic, refined to accept the given profunctor type, or an absent optional if the bounds could not be satisfied.