optics

package module

v0.12.1 Latest Latest Go to latest Published: May 9, 2024 License: MIT Imports: 5 Imported by: 9

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/fogfish/golem

Links

Open Source Insights

README ¶

Optics (`optics`)

Lenses resembles concept of getters and setters, which you can compose using functional concepts. In other words, "a lens is a first-class value that combines two operations: viewing (or getting) a subpart of a data structure, and updating (or setting) that part".

Lenses solves Golang challenge "abstraction over structure fields".

The lens is defined following approaches of Haskell library, and techniques references by [1]:

type Lens[S, A any] interface {
  Get(*S) A
  Put(*S, A) *S
}

The module implements Well behaving lenses so that it satisfies three laws:

GetPut If we get focused element A from S and immediately put A with no modifications back into S, we must get back exactly S.
PutGet If putting A inside S yields a new S, then the A obtained from S is exactly A.
PutPut A sequence of two puts is just the effect of the second, the first is completely overwritten. This law is applicable to every well behaving lenses.

Ω-lenses Lens fails if focus is not exists. Ω-lenses (Prism) are capable to recover a create a new container `Ss from nothing. The Ω-lenses are usable for practical application to construct nested data type but they are not well behaving. Ω-lenses (Prism) are not supported yet by the module.

The module unfolds product type (e.g. structs) into sequence of lenses, while preserving the original type witness.

type S struct { /* ... */ } ⇒ optics.Lens[S, A] × ... × Lens[S, X any]

The module is an enabler for building generic algorithms over equivalent types avoiding repetition.

Getting Started

// Given a product type S : A × ... × X
type S struct {
  A A
  ...
  X X
}

// build instance of lenses
var a, x = optics.ForProduct2[S, A, X]()

The lenses is type safe getters and setters derived from the product type. Absence of macros in Golang, does not allow us to make a compile type definition of lenses. It is a runtime instance but annotated with original type S, which makes it compile type safe. The lens optics.Lens[S, A] uniquely identify typed member of original product type. It usage in other context causes compile time error. The module provides helper function ForProduct1 ... ForProduct9 to automatically derive lense from the struct.

type T struct {
  A A
  B B
  C B
}

var (
  // build lense using only type hint A
  a = optics.ForProduct1[T, A]()
  // build lense using type and name hint "B" 
  b = optics.ForProduct1[T, B]("B")
)

Quick Example

The most simplest example that shows the applicability of optics abstraction is building generic algorithm that abstracts structure fields

// Declare type and its lenses (getters & setter)
type User struct {
  Name    string
  Updated time.Time
}

var userT = optics.ForProduct1[User, time.Time]()

type City struct {
  Name    string
  Updated time.Time
}

var cityT = optics.ForProduct1[City, time.Time]()

// Generic algorithm that modifies struct fields
func show[T any](updated optics.Lens[T, time.Time], v *T) {
  if t := updated.Get(v); t.IsZero() {
    updated.Put(v, time.Now())
  }

  b, _ := json.MarshalIndent(v, "", "  ")
  fmt.Println(string(b))
}

func main() {
  show(userT, &User{Name: "user"})
  show(cityT, &City{Name: "city"})
}

See runnable examples to play with the library

basic lense usage
abstract shape of types, see problem statement Abstract over Golang structure fields using optics for details.
abstract shape of types (advanced)

Changelog

optics/v0.10 and earlier uses reflect
optics/v0.11 and later uses unsafe pointers

References

Combinators for Bi-Directional Tree Transformations: A Linguistic Approach to the View Update Problem

Documentation ¶

Index ¶

func ForProduct2[T, A, B any](attr ...string) (Lens[T, A], Lens[T, B])
func ForProduct3[T, A, B, C any](attr ...string) (Lens[T, A], Lens[T, B], Lens[T, C])
func ForProduct4[T, A, B, C, D any](attr ...string) (Lens[T, A], Lens[T, B], Lens[T, C], Lens[T, D])
func ForProduct5[T, A, B, C, D, E any](attr ...string) (Lens[T, A], Lens[T, B], Lens[T, C], Lens[T, D], Lens[T, E])
func ForProduct6[T, A, B, C, D, E, F any](attr ...string) (Lens[T, A], Lens[T, B], Lens[T, C], Lens[T, D], Lens[T, E], Lens[T, F])
func ForProduct7[T, A, B, C, D, E, F, G any](attr ...string) (Lens[T, A], Lens[T, B], Lens[T, C], Lens[T, D], Lens[T, E], Lens[T, F], ...)
func ForProduct8[T, A, B, C, D, E, F, G, H any](attr ...string) (Lens[T, A], Lens[T, B], Lens[T, C], Lens[T, D], Lens[T, E], Lens[T, F], ...)
func ForProduct9[T, A, B, C, D, E, F, G, H, I any](attr ...string) (Lens[T, A], Lens[T, B], Lens[T, C], Lens[T, D], Lens[T, E], Lens[T, F], ...)
func ForSpectrum2[T, A, B any](attr ...string) (Reflector[A], Reflector[B])
func ForSpectrum3[T, A, B, C any](attr ...string) (Reflector[A], Reflector[B], Reflector[C])
func ForSpectrum4[T, A, B, C, D any](attr ...string) (Reflector[A], Reflector[B], Reflector[C], Reflector[D])
func ForSpectrum5[T, A, B, C, D, E any](attr ...string) (Reflector[A], Reflector[B], Reflector[C], Reflector[D], Reflector[E])
func ForSpectrum6[T, A, B, C, D, E, F any](attr ...string) (Reflector[A], Reflector[B], Reflector[C], Reflector[D], Reflector[E], ...)
func ForSpectrum7[T, A, B, C, D, E, F, G any](attr ...string) (Reflector[A], Reflector[B], Reflector[C], Reflector[D], Reflector[E], ...)
func ForSpectrum8[T, A, B, C, D, E, F, G, H any](attr ...string) (Reflector[A], Reflector[B], Reflector[C], Reflector[D], Reflector[E], ...)
func ForSpectrum9[T, A, B, C, D, E, F, G, H, I any](attr ...string) (Reflector[A], Reflector[B], Reflector[C], Reflector[D], Reflector[E], ...)
type Isomorphism
- func Iso[A, B any](a Shape[A], b Shape[B]) Isomorphism[A, B]
type Lens
- func ForProduct1[T, A any](attr ...string) Lens[T, A]
- func NewLens[S, A any](t hseq.Type[S]) Lens[S, A]
type Lens2
- func ForShape2[T, A, B any](attr ...string) Lens2[T, A, B]
type Lens3
- func ForShape3[T, A, B, C any](attr ...string) Lens3[T, A, B, C]
type Lens4
- func ForShape4[T, A, B, C, D any](attr ...string) Lens4[T, A, B, C, D]
type Lens5
- func ForShape5[T, A, B, C, D, E any](attr ...string) Lens5[T, A, B, C, D, E]
type Lens6
- func ForShape6[T, A, B, C, D, E, F any](attr ...string) Lens6[T, A, B, C, D, E, F]
type Lens7
- func ForShape7[T, A, B, C, D, E, F, G any](attr ...string) Lens7[T, A, B, C, D, E, F, G]
type Lens8
- func ForShape8[T, A, B, C, D, E, F, G, H any](attr ...string) Lens8[T, A, B, C, D, E, F, G, H]
type Lens9
- func ForShape9[T, A, B, C, D, E, F, G, H, I any](attr ...string) Lens9[T, A, B, C, D, E, F, G, H, I]
type Reflector
- func ForSpectrum1[T, A any](attr ...string) Reflector[A]
- func NewReflector[S, A any](t hseq.Type[S]) Reflector[A]
type Shape
- func ForShape[S any](attr ...string) Shape[S]
type Value

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func ForProduct2 ¶

func ForProduct2[T, A, B any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
)

ForProduct2 unfold 2 attribute of type T

func ForProduct3 ¶

func ForProduct3[T, A, B, C any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
	Lens[T, C],
)

ForProduct3 unfold 3 attribute of type T

func ForProduct4 ¶

func ForProduct4[T, A, B, C, D any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
	Lens[T, C],
	Lens[T, D],
)

ForProduct4 unfold 4 attribute of type T

func ForProduct5 ¶

func ForProduct5[T, A, B, C, D, E any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
	Lens[T, C],
	Lens[T, D],
	Lens[T, E],
)

ForProduct5 unfold 5 attribute of type T

func ForProduct6 ¶

func ForProduct6[T, A, B, C, D, E, F any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
	Lens[T, C],
	Lens[T, D],
	Lens[T, E],
	Lens[T, F],
)

ForProduct6 unfold 6 attribute of type T

func ForProduct7 ¶

func ForProduct7[T, A, B, C, D, E, F, G any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
	Lens[T, C],
	Lens[T, D],
	Lens[T, E],
	Lens[T, F],
	Lens[T, G],
)

ForProduct7 unfold 7 attribute of type T

func ForProduct8 ¶

func ForProduct8[T, A, B, C, D, E, F, G, H any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
	Lens[T, C],
	Lens[T, D],
	Lens[T, E],
	Lens[T, F],
	Lens[T, G],
	Lens[T, H],
)

ForProduct8 unfold 8 attribute of type T

func ForProduct9 ¶

func ForProduct9[T, A, B, C, D, E, F, G, H, I any](attr ...string) (
	Lens[T, A],
	Lens[T, B],
	Lens[T, C],
	Lens[T, D],
	Lens[T, E],
	Lens[T, F],
	Lens[T, G],
	Lens[T, H],
	Lens[T, I],
)

ForProduct9 unfold 9 attribute of type T

func ForSpectrum2 ¶ added in v0.11.2

func ForSpectrum2[T, A, B any](attr ...string) (
	Reflector[A],
	Reflector[B],
)

ForSpectrum2 unfold 2 attribute of type T

func ForSpectrum3 ¶ added in v0.11.2

func ForSpectrum3[T, A, B, C any](attr ...string) (
	Reflector[A],
	Reflector[B],
	Reflector[C],
)

ForSpectrum3 unfold 3 attribute of type T

func ForSpectrum4 ¶ added in v0.11.2

func ForSpectrum4[T, A, B, C, D any](attr ...string) (
	Reflector[A],
	Reflector[B],
	Reflector[C],
	Reflector[D],
)

ForSpectrum4 unfold 4 attribute of type T

func ForSpectrum5 ¶ added in v0.11.2

func ForSpectrum5[T, A, B, C, D, E any](attr ...string) (
	Reflector[A],
	Reflector[B],
	Reflector[C],
	Reflector[D],
	Reflector[E],
)

ForSpectrum5 unfold 5 attribute of type T

func ForSpectrum6 ¶ added in v0.11.2

func ForSpectrum6[T, A, B, C, D, E, F any](attr ...string) (
	Reflector[A],
	Reflector[B],
	Reflector[C],
	Reflector[D],
	Reflector[E],
	Reflector[F],
)

ForSpectrum6 unfold 6 attribute of type T

func ForSpectrum7 ¶ added in v0.11.2

func ForSpectrum7[T, A, B, C, D, E, F, G any](attr ...string) (
	Reflector[A],
	Reflector[B],
	Reflector[C],
	Reflector[D],
	Reflector[E],
	Reflector[F],
	Reflector[G],
)

ForSpectrum7 unfold 7 attribute of type T

func ForSpectrum8 ¶ added in v0.11.2

func ForSpectrum8[T, A, B, C, D, E, F, G, H any](attr ...string) (
	Reflector[A],
	Reflector[B],
	Reflector[C],
	Reflector[D],
	Reflector[E],
	Reflector[F],
	Reflector[G],
	Reflector[H],
)

ForSpectrum8 unfold 8 attribute of type T

func ForSpectrum9 ¶ added in v0.11.2

func ForSpectrum9[T, A, B, C, D, E, F, G, H, I any](attr ...string) (
	Reflector[A],
	Reflector[B],
	Reflector[C],
	Reflector[D],
	Reflector[E],
	Reflector[F],
	Reflector[G],
	Reflector[H],
	Reflector[I],
)

ForSpectrum9 unfold 9 attribute of type T

Types ¶

type Isomorphism ¶ added in v0.12.0

type Isomorphism[A, B any] interface {
	FromAtoB(*A, *B)
	FromBtoA(*B, *A)
}

An isomorphism is a structure-preserving mapping between two structures of the same shape that can be reversed by an inverse mapping.

func Iso ¶ added in v0.12.0

func Iso[A, B any](a Shape[A], b Shape[B]) Isomorphism[A, B]

Isomorphism from category A to B

type Lens ¶

type Lens[S, A any] interface {
	Get(*S) A
	Put(*S, A) *S
}

Lens resembles concept of getters and setters, which you can compose using functional concepts. In other words, this is combinator data transformation for pure functional data structure.

Lens allows to abstract a "shape" of the structure rather than type itself.

func ForProduct1 ¶

func ForProduct1[T, A any](attr ...string) Lens[T, A]

ForProduct1 unfold 1 attribute of type T

func NewLens ¶

func NewLens[S, A any](t hseq.Type[S]) Lens[S, A]

NewLens instantiates a typed Lens[S, A] for hseq.Type[S]

type Lens2 ¶ added in v0.11.0

type Lens2[S, A, B any] interface {
	Get(*S) (A, B)
	Put(*S, A, B) *S
}

Rank 2 Shape: Product Lens A × B

func ForShape2 ¶ added in v0.11.0

func ForShape2[T, A, B any](attr ...string) Lens2[T, A, B]

Rank 2 Shape: Product Lens A × B

type Lens3 ¶ added in v0.11.0

type Lens3[S, A, B, C any] interface {
	Get(*S) (A, B, C)
	Put(*S, A, B, C) *S
}

Rank 3 Shape: Product Lens A × B × C

func ForShape3 ¶ added in v0.11.0

func ForShape3[T, A, B, C any](attr ...string) Lens3[T, A, B, C]

Rank 3 Shape: Product Lens A × B × C

type Lens4 ¶ added in v0.11.0

type Lens4[S, A, B, C, D any] interface {
	Get(*S) (A, B, C, D)
	Put(*S, A, B, C, D) *S
}

Rank 4 Shape: Product Lens A × B × C × D

func ForShape4 ¶ added in v0.11.0

func ForShape4[T, A, B, C, D any](attr ...string) Lens4[T, A, B, C, D]

Rank 4 Shape: Product Lens A × B × C × D

type Lens5 ¶ added in v0.11.0

type Lens5[S, A, B, C, D, E any] interface {
	Get(*S) (A, B, C, D, E)
	Put(*S, A, B, C, D, E) *S
}

Rank 5 Shape: Product Lens A × B × C × D × E

func ForShape5 ¶ added in v0.11.0

func ForShape5[T, A, B, C, D, E any](attr ...string) Lens5[T, A, B, C, D, E]

Rank 5 Shape: Product Lens A × B × C × D × E

type Lens6 ¶ added in v0.11.0

type Lens6[S, A, B, C, D, E, F any] interface {
	Get(*S) (A, B, C, D, E, F)
	Put(*S, A, B, C, D, E, F) *S
}

Rank 6 Shape: Product Lens A × B × C × D × E × F

func ForShape6 ¶ added in v0.11.0

func ForShape6[T, A, B, C, D, E, F any](attr ...string) Lens6[T, A, B, C, D, E, F]