Skill v1.0.1

currentAutomated scan100/100

ibm/fp-go/fp-go-lens

+1 new

──Details

PublishedOctober 1, 2026 at 03:06 PM

Content Hashsha256:cc032027d6e956bb...

Git SHAcc63bd344c0e

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 16.8 KB)

SKILL.md16.8 KBactive

SKILL.md · 493 lines · 16.8 KB

version: "1.0.1" name: fp-go-lens description: >- Use this skill when working with lenses and optics in Go using the fp-go library (github.com/IBM/fp-go/v2/optics/lens). Trigger on mentions of lenses, optics, MakeLens, MakeLensRef, MakeLensStrict, lens composition, immutable updates to nested structs, accessing nested data structures, Compose, ComposeRef, ComposeOption, FromNillable, FromNillableRef, Modify, getter/setter patterns, or functional updates to Go structs. Also trigger when the user needs to update deeply nested fields immutably or work with optional fields in struct hierarchies. Also trigger for // fp-go:Lens annotation or go generate for lens code generation.

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"
)

Before You Generate

fp-go is low-frequency in training data, so signatures are easy to misremember. For any combinator not shown below, look it up via the fp-go MCP server's search_examples / get_example tools (see the fp-go-mcp skill) instead of guessing. After writing code, run go build ./... and go vet ./... and fix any type-parameter or argument-order errors before presenting it.

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 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:

Generated type	Description
`PersonLenses`	Lenses for `Person` (value type)
`PersonRefLenses`	Lenses for `*Person` (pointer type)
`PersonPrisms`	Prisms for `Person`
`PersonRefPrisms`	Prisms for `*Person`

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

Constructor	Source type	Copy responsibility	Best for
`MakeLens`	`S` (value)	Automatic (value copy)	Structs by value
`MakeLensRef`	`*S` (pointer)	Automatic (framework)	Structs by pointer
`MakeLensStrict`	`*S` (pointer)	Automatic + equality skip	Comparable fields, performance-sensitive
`MakeLensWithEq`	`*S` (pointer)	Automatic + custom Eq	Non-comparable fields with equality

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):

Function	`ab` type	Use when
`LO.ComposeOption`	`Lens[A, B]` — required field	The inner field always exists once A is present
`LO.Compose`	`LensO[A, B]` — optional field	The inner field is itself optional

// 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)

Context Values as a Lens

lenses.AtContext[V](key) is a LensO[context.Context, V] onto a typed context.Context value. Get returns Some(v) if the key holds a V, otherwise None (never panics); Set(Some(v)) derives a child context via context.WithValue, Set(None) returns the context unchanged.

import LS "github.com/IBM/fp-go/v2/optics/lenses"
 
type ctxKey string
const userKey ctxKey = "user"
 
userL := LS.AtContext[string](userKey)
ctx2  := userL.Set(O.Some("Alice"))(ctx)
user  := userL.Get(ctx2)               // Some("Alice")

Inside context/* pipelines prefer the monadic operators AskValue[V](key) / WithValue[A](key, v); use the lens when you need optics composition over the context.

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"}}
}