Compose two isos.

Example

// Iso: List(a) <-> List(a) (reverse)
let reverse_iso = ocular.iso(
  get: list.reverse,
  reverse: list.reverse,
)

// Compose: double reverse = identity
let identity = reverse_iso |> compose.iso(reverse_iso)

Compose an iso with a lens. Result: Lens

Example

// Wrapper iso: String <-> WrappedString
let wrapper_iso = ocular.iso(
  get: fn(s: String) { WrappedString(s) },
  reverse: fn(w: WrappedString) { w.value },
)

// Compose: WrappedString -> String -> Int (length)
let wrapped_length = wrapper_iso |> compose.iso_lens(string_length_lens)

Compose an iso with an optional. Result: Optional

Example

// Convert Dict <-> List(Pair), then access by key
let dict_key_via_list = dict_list_iso |> compose.iso_opt(key_opt)

Compose an iso with a prism. Result: Prism

Example

// Convert String <-> WrappedString, then match Some(WrappedString)
let wrapped_some = wrapper_iso |> compose.iso_prism(ocular.some())

Compose two lenses.

Example

pub type Address { Address(street: String) }
pub type User { User(address: Address) }

let address_lens = ocular.lens(
  get: fn(u: User) { u.address },
  set: fn(v, u: User) { User(..u, address: v) },
)

let street_lens = ocular.lens(
  get: fn(a: Address) { a.street },
  set: fn(v, a: Address) { Address(..a, street: v) },
)

// Compose: User -> Address -> String
let user_street = address_lens |> compose.lens(street_lens)

let user = User(address: Address(street: "Main St"))
let street = ocular.get(user, user_street)  // "Main St"

Compose a lens with an iso. Result: Lens

Example

// User.name is a String, convert to WrappedString
let wrapped_name = user_name_lens |> compose.lens_iso(wrapper_iso)

Compose a lens with an optional. Result: Optional (since the path may not exist)

Example

pub type User { User(address: Option(Address)) }
pub type Address { Address(city: String) }

let address_opt = ocular.optional(
  get: fn(u: User) {
    case u.address {
      Some(a) -> Ok(a)
      None -> Error(Nil)
    }
  },
  set: fn(v, u: User) { User(..u, address: Some(v)) },
)

let city_lens = ocular.lens(
  get: fn(a: Address) { a.city },
  set: fn(v, a: Address) { Address(..a, city: v) },
)

// Compose: User -?-> Address -> String (Optional result)
let city_opt = address_opt |> compose.lens_opt(city_lens)

let user = User(address: Some(Address(city: "NYC")))
let city = ocular.get_opt(user, city_opt)  // Ok("NYC")

Compose an optional with a lens. Result: Optional (since the outer path may not exist)

Example

// User has optional address, address has required street
let street_lens = ocular.lens(
  get: fn(a: Address) { a.street },
  set: fn(v, a: Address) { Address(..a, street: v) },
)

// Compose: User -?-> Address -> String
let street_opt = address_opt |> compose.opt_lens(street_lens)

Compose two optionals (alias for optional).

Compose an optional with a prism. Result: Optional

Example

// Optional address, address is Shape (Circle or Rectangle)
let address_circle = address_opt |> compose.opt_prism(circle_prism)

Compose two optionals. Result: Optional (both paths must exist)

Example

// Level1 -?-> Level2 -?-> String
let level1_opt: Optional(Level1, Level2) = ...
let level2_opt: Optional(Level2, String) = ...

let deep_opt = level1_opt |> compose.optional(level2_opt)

// Only succeeds if both levels exist
let result = ocular.get_opt(level1, deep_opt)

Compose two prisms. Both prisms must match for the composition to succeed.

Example

pub type Shape {
  Circle(radius: Float)
  Rectangle(width: Float, height: Float)
}

pub type Container {
  Box(shape: Shape)
  Bag(items: List(String))
}

let box_prism = ocular.prism(
  get: fn(c: Container) {
    case c {
      Box(s) -> Ok(s)
      Bag(_) -> Error(Nil)
    }
  },
  set: fn(s, _c) { Box(s) },
  review: fn(s) { Box(s) },
)

let circle_prism = ocular.prism(
  get: fn(s: Shape) {
    case s {
      Circle(r) -> Ok(r)
      Rectangle(_, _) -> Error(Nil)
    }
  },
  set: fn(r, _s) { Circle(r) },
  review: fn(r) { Circle(r) },
}

// Compose: Container -> Shape -> Float (only for Box(Circle(_)))
let box_circle_radius = box_prism |> compose.prism(circle_prism)

let container = Box(Circle(5.0))
let radius = ocular.preview(container, box_circle_radius)  // Ok(5.0)

Compose a prism with an iso. Result: Prism

Example

// Match Some(Int), then convert Int <-> String
let some_string = ocular.some() |> compose.prism_iso(int_string_iso)

Compose a prism with a lens. Result: Optional (not Prism) because review cannot be implemented without a default value for the middle structure.

Example

// Option(Circle) with Circle having a radius field
let some_circle = ocular.some() |> compose.prism_lens(circle_radius_lens)

let maybe_circle = Some(Circle(5.0))
let radius = ocular.get_opt(maybe_circle, some_circle)  // Ok(5.0)

Compose a prism with an optional. Result: Optional

Example

// Shape is Circle or Rectangle, Circle has optional label
let circle_label = circle_prism |> compose.prism_opt(label_opt)