Package sprouts

Interface Lens<A extends @Nullable Object,B extends @Nullable Object>

Type Parameters:
A - The parent type with the field of type B to be focused on.
B - The type of the field to be focused on in the parent type A.
public interface Lens<A extends @Nullable Object,B extends @Nullable Object>
The Lens interface defines an access and update operation on an individual part of a nested and immutable data structure. A lens can also be composed with other lenses to focus on more deeply nested parts. This design concept is part of the functional programming paradigm, and it emulates mutable properties (getter and setter) in an immutable world using a getter and more importantly a wither methods (a function that returns a new structure with target field being updated).

So a Lenses encapsulate two essential operations:

  • getter: Extracts a specific field from a parent type.
  • wither: Produces a new instance of the parent with an updated field, preserving immutability.

Usage Example:


 record Person(String name, Address address) {}
 record Address(String street, String city) {}

 Lens<Person, Address> addressLens = Lens.of(
     Person::address,
     (person, newAddress) -> new Person(person.name(), newAddress)
 );

 Lens<Address, String> streetLens = Lens.of(
     Address::street,
     (address, newStreet) -> new Address(newStreet, address.city())
 );

 Lens<Person, String> personStreetLens = addressLens.to(streetLens);

 Person person = new Person("Alice", new Address("1st Ave", "Wonderland"));
 String street = personStreetLens.getter(person); // "1st Ave"
 Person updatedPerson = personStreetLens.wither(person, "2nd Ave");

Composability:

You may compose lenses using the to(Lens) method, which composes them into a new lens, enabling seamless traversal and modification of deeply nested structures.

Factory Method:

The of(Function, BiFunction) static method is provided to easily create lenses from lambda expressions.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <A, B> Lens<Tuple<A>,Tuple<B>>
    across(Class<B> type, Function<A,B> getter, BiFunction<A,B,A> wither)
    Creates a lens that operates across all elements of a Tuple, allowing bulk transformations of homogeneous data structures.
    B
    getter(A parentValue)
    Extracts the field of type B from the parent type A and returns it or throws an exception if an error occurs while extracting the field.
    static <A, B> Lens<A,B>
    of(Function<A,B> getter, BiFunction<A,B,A> wither)
    Creates a new lens from the given getter and wither functions, where the first function serves as an implementation of getter(Object) and the second function serves as an implementation of wither(Object, Object).
    default <C> Lens<A,C>
    to(Function<B,C> getter, BiFunction<B,C,B> wither)
    Combines this lens with a pair of getter and wither functions, to create a new lens that focuses on a more deeply nested field.
    default <C> Lens<A,C>
    to(Lens<B,C> other)
    Composes this lens with another lens, creating a new lens that focuses on a more deeply nested field.
    A
    wither(A parentValue, B newValue)
    Produces a new instance of the parent type A with one of its fields of type B updated with a new value.

  • Method Details

    • of

      static <A, B> Lens<A,B> of(Function<A,B> getter, BiFunction<A,B,A> wither)
      Creates a new lens from the given getter and wither functions, where the first function serves as an implementation of getter(Object) and the second function serves as an implementation of wither(Object, Object).
      Type Parameters:
      A - The parent type with the field of type B to be focused on.
      B - The type of the field to be focused on in the parent type A.
      Parameters:
      getter - The function that extracts the field of type B from the parent type A.
      wither - The function that produces a new instance of the parent type A with the field updated.
      Returns:
      A new lens instance.
      Throws:
      NullPointerException - If either of the given functions is null.

    • across

      static <A, B> Lens<Tuple<A>,Tuple<B>> across(Class<B> type, Function<A,B> getter, BiFunction<A,B,A> wither)
      Creates a lens that operates across all elements of a Tuple, allowing bulk transformations of homogeneous data structures. This is particularly useful for scenarios like multi-selection where you want to apply the same lens operation to multiple values simultaneously.

      The returned lens will:

      • Use the provided getter to extract a property of type B from each element of type A in the tuple.
      • Use the provided wither to update that property B across all elements A in the tuple.
      Example Usage: 
      
 record Person(String name, int age) {
     public Person withAge(int newAge) {
         return new Person(name, newAge);
     }
 }

 // Create tuple lens version
 Lens<Tuple<Person>, Tuple<Integer>> bulkAgeLens = Lens.across(
     Integer.class,Person::age, Person::withAge
 );

 Tuple<Person> people = Tuple.of(
     new Person("Alice", 30),
     new Person("Bob", 25),
     new Person("Charlie", 35)
 );

 // Get all ages
 Tuple<Integer> ages = bulkAgeLens.getter(people); // (30, 25, 35)

 // Set all ages to 40
 Tuple<Person> updatedPeople = bulkAgeLens.wither(people,
     Tuple.of(40, 40, 40));
      You may then use such a lens to zoom into a tuple-based property to get a tuple-based lens property: 
      
 Var<Tuple<Person>> people = getPeople();
 Var<Tuple<Integer> ages =
                    people.zoomTo(
                        Lens.across(
                           Integer.class,
                           Person::age,
                           Person::withAge
                        ));
      Type Parameters:
      A - The element type contained in the source tuple
      B - The type of property being focused on in each element
      Parameters:
      type - The class object for type B, used for tuple type safety
      getter - Function to extract property B from a single A
      wither - Function to update property B in a single A
      Returns:
      A lens that operates on tuples of A to get/set tuples of B
      Throws:
      NullPointerException - if either getter or wither is null
      IllegalArgumentException - during wither operation if input tuples have different sizes

    • getter

      B getter(A parentValue) throws Exception
      Extracts the field of type B from the parent type A and returns it or throws an exception if an error occurs while extracting the field.
      Parameters:
      parentValue - The parent object to extract the field from.
      Returns:
      The field of type B from the parent object.
      Throws:
      Exception - If an error occurs while extracting the field.

    • wither

      A wither(A parentValue, B newValue) throws Exception
      Produces a new instance of the parent type A with one of its fields of type B updated with a new value. The parent object is not modified, and a new instance is returned.
      Parameters:
      parentValue - The parent object to update the field in.
      newValue - The new value to update the field with.
      Returns:
      A new instance of the parent type A with the field updated.
      Throws:
      Exception - If an error occurs while updating the field.

    • to

      default <C> Lens<A,C> to(Lens<B,C> other)
      Composes this lens with another lens, creating a new lens that focuses on a more deeply nested field. This lens focuses on a field of type B in the parent type A, and the other lens focuses on a field of type C in the parent type B. The composed lens will focus on a field of type C in the parent type A, effectively traversing two levels of nesting and side-stepping the intermediate parent type B.
      Type Parameters:
      C - The type of the field to be focused on in the parent type B.
      Parameters:
      other - The other lens to compose with this lens.
      Returns:
      A new lens that focuses on a more deeply nested field.
      Throws:
      NullPointerException - If the given lens is null.

    • to

      default <C> Lens<A,C> to(Function<B,C> getter, BiFunction<B,C,B> wither)
      Combines this lens with a pair of getter and wither functions, to create a new lens that focuses on a more deeply nested field. This lens focuses on a field of type B in the parent type A, and the two supplied lambdas focus on a field of type C in the parent type B. The composed lens will focus on a field of type C in the parent type A, effectively traversing two levels of nesting and side-stepping the intermediate parent type B.
      Type Parameters:
      C - The type of the field to be focused on in the parent type B.
      Parameters:
      getter - The function that extracts the field of type C from the parent type B.
      wither - The function that produces a new instance of the parent type B with the field updated.
      Returns:
      A new lens that focuses on a more deeply nested field.
      Throws:
      NullPointerException - If either of the given functions is null.