Monocle: a small lens library

8.16.0.1

Monocle: a small lens library🔗ℹ

This package provides a lens implementation with minimal dependencies and a focus on ergonomics. For a more full-featured implementation see the lens package.

By convention, lens ids are prefixed by an & character.

1 Reference🔗ℹ

(require data/monocle)

package: monocle-lib

This module reprovides all the bindings defined in the modules documented below.

1.1 Operators🔗ℹ

(require data/monocle/lens)

package: monocle-lib

struct
(struct lens (getter setter)
    #:extra-constructor-name make-lens)
  getter : (procedure-arity-includes/c 1)
  setter : (procedure-arity-includes/c 2)

The structure for lenses. Instances of this structure are applicable; applying a lens to a value is equivalent to applying its getter to that value. Applying a lens to two values is equivalent to applying its setter to the two values.

procedure
(lens-set l s v) → any/c
  l : lens?
  s : any/c
  v : any/c

Replaces the focus of l in s with v.

Examples:

> (lens-set &car '(a . b) 'c)
'(c . b)
; A slightly faster version of:
> (&car '(a . b) 'c)
'(c . b)

procedure
(lens-update l s p) → any/c
  l : lens?
  s : any/c
  p : (-> any/c any/c)

Replaces the focus of l in s by applying p to the focused value.

Example:

> (lens-update &car '(1 . 2) add1)
'(2 . 2)

procedure
(lens-compose a b ...+) → lens?
a : lens?
b : lens?

Composes two or more lenses from right to left.

Examples:

> ((lens-compose &car &cdr) '(a b c))
'b
> ((lens-compose &car &cdr) '(a b c) 'd)
'(a d c)

procedure
(lens-thread a b ...+) → lens?
a : lens?
b : lens?

Composes two or more lenses from left to right.

Examples:

> ((lens-thread &cdr &car) '(a b c))
'b
> ((lens-thread &cdr &car) '(a b c) 'd)
'(a d c)

1.2 Lenses for Pairs🔗ℹ

(require data/monocle/pair)

package: monocle-lib

value
&car : lens?

A lens that focuses on the car of a pair.

value
&cdr : lens?

A lens that focuses on the cdr of a pair.

1.3 Lenses for Lists🔗ℹ

(require data/monocle/list)

package: monocle-lib

procedure
(&list-ref idx) → lens?
idx : exact-nonnegative-integer?

Returns a lens that focuses on the idxth element of a list.

procedure
(&findf pred) → lens?
pred : (-> any/c boolean?)

Returns a lens that focuses on the first element of a list that matches pred.

1.4 Lenses for Hashes🔗ℹ

(require data/monocle/hash)

package: monocle-lib

procedure
(&hash-ref k) → lens?
k : any/c

Returns a lens that focuses on the element at k of a hash.

procedure
(&hash-ref* k ...+) → lens?
k : any/c

Returns a lens by threading a series of &hash-ref lenses for every given k. Use this lens factory to access and update deeply-nested hashes.

Examples:

> ((&hash-ref* 'a 'b 'c)
   (hasheq 'a (hasheq 'b (hasheq 'c 42))))
42
> (lens-update
   (&hash-ref* 'a 'b 'c)
   (hasheq 'a (hasheq 'b (hasheq 'c 42)))
   add1)
'#hasheq((a . #hasheq((b . #hasheq((c . 43))))))

parameter
(current-hash-maker) → (-> hash?)
(current-hash-maker proc) → void?
proc : (-> hash?)
= hasheq

Holds the procedure that &opt-hash-ref uses to generate empty hash values.

Added in version 0.3 of package monocle-lib.

procedure
(&opt-hash-ref k) → lens?
k : any/c
procedure
(&opt-hash-ref* k ...+) → lens?
k : any/c

Like &hash-ref and &hash-ref*, respectively, but missing values are treated as #f on get and replaced with the result of applying the procedure contained by current-hash-maker on set.

Added in version 0.2 of package monocle-lib.

1.5 Lenses for Structs🔗ℹ

(require data/monocle/struct)

package: monocle-lib

syntax
(define-struct-lenses struct-id)

Defines a lens for every field belonging to struct-id by prepending the field’s accessor id with an & character.

Examples:

> (struct foo (x y) #:transparent)
> (define-struct-lenses foo)
> (&foo-x (foo 1 2))
1
> (&foo-x (foo 1 2) 3)
(foo 3 2)