fp-go-lens

fp-go Lenses for Structs

Overview

Lenses are functional optics that provide immutable access to nested data structures. A Lens[S, A] focuses on a field A within a structure S, providing Get (read) and Set (immutable update) operations.

import (
    L  "github.com/IBM/fp-go/v2/optics/lens"
    LO "github.com/IBM/fp-go/v2/optics/lens/option"
    F  "github.com/IBM/fp-go/v2/function"
    O  "github.com/IBM/fp-go/v2/option"
)

---

Code Generation (Recommended)

The fastest way to create lenses is via code generation. Annotate any struct with // fp-go:Lens and run go generate ./....

//go:generate go run github.com/IBM/fp-go/v2/main lens --dir . --filename gen_lens.go

// fp-go:Lens
type Person struct {
    Name  string
    Age   int
    Phone *string  // pointer → optional lens auto-generated
}

Running go generate ./... produces a gen_lens.go file with:

Each type has fields for every struct field, with both a required lens and an optional lens:

type PersonLenses struct {
    Name  L.Lens[Person, string]            // required lens
    NameO LO.LensO[Person, string]          // optional lens (LensO = Lens[S, Option[A]])
    Age   L.Lens[Person, int]
    AgeO  LO.LensO[Person, int]
    Phone L.Lens[Person, *string]
    PhoneO LO.LensO[Person, *string]        // pointer fields auto-get optional variant
}

Constructor functions:

lenses    := MakePersonLenses()             // PersonLenses
refLenses := MakePersonRefLenses()          // PersonRefLenses

// Usage
person  := Person{Name: "Alice", Age: 30}
updated := lenses.Name.Set("Bob")(person)   // Person{Name: "Bob", Age: 30}
name    := lenses.Name.Get(person)          // "Alice"

Pointer fields (*string, *SomeStruct) automatically generate optional lenses using LO.FromNillable.

Embedded structs and generic types are also supported — for embedded structs, lenses are generated for each promoted field.

---

Manual Lens Creation

Use manual creation when code generation is not suitable or for one-off lenses.

MakeLens — Value Types

Use MakeLens for structs passed by value. The setter receives a copy automatically.

type Person struct {
    Name string
    Age  int
}

nameLens := L.MakeLens(
    func(p Person) string          { return p.Name },
    func(p Person, name string) Person { p.Name = name; return p },
)

person  := Person{Name: "Alice", Age: 30}
updated := nameLens.Set("Bob")(person)   // Person{Name: "Bob", Age: 30}
name    := nameLens.Get(person)          // "Alice"

Method expressions also work (receiver becomes first argument):

func (p Person) GetName() string            { return p.Name }
func (p Person) SetName(name string) Person { p.Name = name; return p }

nameLens := L.MakeLens(Person.GetName, Person.SetName)

Setter signature: func(S, A) S — struct first, value second.

MakeLensRef — Pointer Types

Use MakeLensRef for structs passed by pointer. The framework handles copying automatically — your setter modifies the pointer directly.

type Address struct {
    Street string
    City   string
}

streetLens := L.MakeLensRef(
    func(a *Address) string                  { return a.Street },
    func(a *Address, s string) *Address      { a.Street = s; return a },
)

addr    := &Address{Street: "Main St", City: "Boston"}
updated := streetLens.Set("Oak Ave")(addr)   // new *Address, original unchanged

Setter signature: func(*S, A) *S — pointer first, value second. No manual copy needed.

MakeLensStrict — Pointer Types with Comparable Fields (Optimization)

Use MakeLensStrict for pointer structs when the field type is comparable (string, int, pointers, etc.). If the new value equals the current value, the original pointer is returned unchanged (no allocation).

nameLens := L.MakeLensStrict(
    func(p *Person) string             { return p.Name },
    func(p *Person, name string) *Person { p.Name = name; return p },
)

// Setting the same value → returns original pointer (no copy)
same    := nameLens.Set("Alice")(person)  // same == person
// Setting a different value → creates a new copy
updated := nameLens.Set("Bob")(person)

For non-comparable types use MakeLensWithEq with a custom Eq[A].

MakeLensWithEq — Pointer Types with Custom Equality

Use MakeLensWithEq when the field type is not comparable (slices, maps, structs containing those). Provide an Eq[A] to determine equality; if values are equal, the original pointer is returned unchanged without copying.

import A "github.com/IBM/fp-go/v2/array"

// []string is not comparable, so MakeLensStrict cannot be used.
// array.StrictEquals[string]() compares slices element-by-element using slices.Equal.
tagsLens := L.MakeLensWithEq(
    A.StrictEquals[string](),
    func(p *Person) []string            { return p.Tags },
    func(p *Person, t []string) *Person { p.Tags = t; return p },
)

For custom element equality (e.g. case-insensitive strings or struct slices), use EQ.FromEquals(func(a, b []T) bool { ... }) instead. For comparable types, EQ.FromStrictEquals[T]() is equivalent to using MakeLensStrict.

Comparison

---

Composing Lenses

Compose — Value Outer Structure

Compose[S](ab)(sa) combines a Lens[S, A] and a Lens[A, B] into a Lens[S, B].

type Street  struct { Name string }
type Address struct { Street Street }

addressLens := L.MakeLens(
    func(p Person) Address          { return p.Address },
    func(p Person, a Address) Person { p.Address = a; return p },
)
streetNameLens := L.MakeLens(
    func(a Address) string            { return a.Street.Name },
    func(a Address, n string) Address { a.Street.Name = n; return a },
)

// Compose: Person → Address → string
personStreetNameLens := F.Pipe1(addressLens, L.Compose[Person](streetNameLens))

updated := personStreetNameLens.Set("Oak Ave")(person)

ComposeRef — Pointer Outer Structure

ComposeRef[S](ab)(sa) is the pointer version — use when the outer lens is Lens[*S, A].

// Composes Lens[*Person, Address] with Lens[Address, string] → Lens[*Person, string]
personStreetNameLens := F.Pipe1(addressRefLens, L.ComposeRef[Person](streetNameLens))

---

Working with Optional Fields

Optional field lenses have type LensO[S, A] (alias for Lens[S, Option[A]]). Get returns Option[A]; Set takes Option[A].

All functions below are in the optics/lens/option package (imported as LO).

FromNillable — Pointer Field to Option

LO.FromNillable converts a Lens[S, *A] to a LensO[S, *A]. Get returns None when the pointer is nil.

type Company struct {
    Name    string
    Address *Address  // optional
}

addressPtrLens := L.MakeLens(
    func(c Company) *Address             { return c.Address },
    func(c Company, a *Address) Company  { c.Address = a; return c },
)

// LensO[Company, *Address]
optAddressLens := LO.FromNillable(addressPtrLens)

company := Company{Name: "Acme"}
result  := optAddressLens.Get(company)              // None[*Address]

withAddr := optAddressLens.Set(O.Some(&Address{City: "Boston"}))(company)
cleared  := optAddressLens.Set(O.None[*Address]())(withAddr)

For pointer outer structs use LO.FromNillableRef (Lens[*S, *A] → LensO[*S, *A]).

ComposeOption — Optional Container, Required Field

LO.ComposeOption[S, B](defaultA)(ab) composes a LensO[S, A] (optional container) with a Lens[A, B] (required field) into a LensO[S, B].

• Get: returns None[B] when A is absent
• Set(Some[B]): updates B in A, creating A from defaultA if absent
• Set(None[B]): removes A entirely

type Config struct { Database *Database }

dbLens := LO.FromNillable(L.MakeLens(
    func(c Config) *Database             { return c.Database },
    func(c Config, db *Database) Config  { c.Database = db; return c },
))

portLens := L.MakeLensRef(
    func(db *Database) int               { return db.Port },
    func(db *Database, p int) *Database  { db.Port = p; return db },
)

defaultDB := &Database{Host: "localhost", Port: 5432}
configPortLens := F.Pipe1(dbLens, LO.ComposeOption[Config, int](defaultDB)(portLens))

config  := Config{}
port    := configPortLens.Get(config)                         // None[int]
updated := configPortLens.Set(O.Some(3306))(config)           // Database created from defaultDB

Compose (option package) — Optional Container, Optional Field

LO.Compose[S, B](defaultA)(ab) is like ComposeOption but ab is a LensO[A, B] (the inner field is also optional).

// Both the Settings container and MaxRetries field are optional pointers
settingsLens := LO.FromNillable(settingsPtrLens)   // LensO[Config, *Settings]
retriesLens  := LO.FromNillable(retriesPtrLens)    // LensO[*Settings, *int]

defaultSettings := &Settings{}
configRetriesLens := F.Pipe1(settingsLens, LO.Compose[Config, *int](defaultSettings)(retriesLens))

Chaining Multiple Optional Levels

Use F.Pipe2 / F.Pipe3 to chain compose steps. Choose the compose function based on the type of the inner lens (ab):

// Person.Address (*Address, optional) → Address.Street (*Street, optional) → Street.Name (string, required)
defaultAddress := &Address{}
defaultStreet  := &Street{}

streetNameLens := L.MakeLensStrict(
    func(s *Street) string               { return s.Name },
    func(s *Street, n string) *Street    { s.Name = n; return s },
)
// LensO[*Address, *Street] — Street pointer is optional
addressStreetLens := LO.FromNillableRef(L.MakeLensRef(
    func(a *Address) *Street             { return a.Street },
    func(a *Address, s *Street) *Address { a.Street = s; return a },
))
// LensO[Person, *Address] — Address pointer is optional
personAddressLens := LO.FromNillable(L.MakeLens(
    func(p Person) *Address              { return p.Address },
    func(p Person, a *Address) Person    { p.Address = a; return p },
))

streetNameInPerson := F.Pipe2(
    personAddressLens,                                                      // LensO[Person, *Address]
    LO.Compose[Person, *Street](defaultAddress)(addressStreetLens),         // ab is LensO → LO.Compose
    LO.ComposeOption[Person, string](defaultStreet)(streetNameLens),        // ab is Lens  → LO.ComposeOption
)
// streetNameInPerson is LensO[Person, string]

---

Modifying Values

Modify applies a transformation function to the focused value:

type Counter struct { Value int }

valueLens := L.MakeLens(
    func(c Counter) int             { return c.Value },
    func(c Counter, v int) Counter  { c.Value = v; return c },
)

counter     := Counter{Value: 5}
incremented := valueLens.Modify(N.Add(1))(counter)
// incremented.Value == 6, counter.Value == 5 (unchanged)

Or using the package-level function in pipelines:

incremented := F.Pipe1(valueLens, L.Modify[Counter](N.Add(1)))(counter)

---

Import Reference

import (
    L  "github.com/IBM/fp-go/v2/optics/lens"            // MakeLens, MakeLensRef, MakeLensStrict, MakeLensWithEq, Compose, ComposeRef, Modify
    LO "github.com/IBM/fp-go/v2/optics/lens/option"     // LensO, FromNillable, FromNillableRef, ComposeOption, Compose
    F  "github.com/IBM/fp-go/v2/function"               // Pipe1, Pipe2, Pipe3, ...
    O  "github.com/IBM/fp-go/v2/option"                 // Some, None, Option
    EQ "github.com/IBM/fp-go/v2/eq"                     // FromStrictEquals, FromEquals (for MakeLensWithEq)
    A  "github.com/IBM/fp-go/v2/array"                  // StrictEquals, Eq (for MakeLensWithEq with slice fields)
    N  "github.com/IBM/fp-go/v2/number"                 // Add, Sub, Mul, ... (arithmetic on numeric fields)
)

---

Complete Manual Example

package main

import (
    F  "github.com/IBM/fp-go/v2/function"
    L  "github.com/IBM/fp-go/v2/optics/lens"
    LO "github.com/IBM/fp-go/v2/optics/lens/option"
    O  "github.com/IBM/fp-go/v2/option"
)

type Street struct {
    Name string
}

type Address struct {
    City   string
    Street *Street  // optional
}

type Person struct {
    Name    string
    Age     int
    Address *Address  // optional
}

func main() {
    // Leaf lens: *Street.Name (comparable → use Strict for optimization)
    streetNameLens := L.MakeLensStrict(
        func(s *Street) string              { return s.Name },
        func(s *Street, n string) *Street   { s.Name = n; return s },
    )

    // Mid lens: *Address.Street (pointer field → optional)
    addressStreetLens := LO.FromNillableRef(L.MakeLensRef(
        func(a *Address) *Street              { return a.Street },
        func(a *Address, s *Street) *Address  { a.Street = s; return a },
    ))

    // Root lens: Person.Address (pointer field → optional)
    personAddressLens := LO.FromNillable(L.MakeLens(
        func(p Person) *Address              { return p.Address },
        func(p Person, a *Address) Person    { p.Address = a; return p },
    ))

    // Compose all levels
    defaultAddress := &Address{City: "Unknown"}
    defaultStreet  := &Street{}

    streetNameInPerson := F.Pipe2(
        personAddressLens,
        LO.Compose[Person, *Street](defaultAddress)(addressStreetLens),
        LO.ComposeOption[Person, string](defaultStreet)(streetNameLens),
    )

    // Update deeply nested field immutably
    person := Person{
        Name: "Alice",
        Age:  30,
        Address: &Address{
            City:   "Boston",
            Street: &Street{Name: "Main St"},
        },
    }

    updated := streetNameInPerson.Set(O.Some("Oak Ave"))(person)
    // person.Address.Street.Name == "Main St" (original unchanged)
    // updated.Address.Street.Name == "Oak Ave"

    // Person with no address: default values are used
    noAddr   := Person{Name: "Bob"}
    withAddr := streetNameInPerson.Set(O.Some("Elm St"))(noAddr)
    // withAddr.Address == &Address{City: "Unknown", Street: &Street{Name: "Elm St"}}
}

---

Further Reading

• Introduction to optics: lenses and prisms
• Lens Laws — Property-based tests for lens correctness
• Code generation CLI — // fp-go:Lens annotation details