The lense Reference Manual

Table of Contents

The lense Reference Manual

This is the lense Reference Manual, version 0.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:36:10 2021 GMT+0.

1 Introduction

Lense

Racket style lenses for the Common Lisp. Portable, extendable, simple.

Quick explanation

Lenses objects acting as a first-class accessors build around SETFable places. They are composable by default, which greatly simplifies building nested representations.

Demonstration

This package exports just a few symbols. You can use READ, WRITE (or ACCESS if you prefer to do so) as well as TRANSFORM to interact with lenses. To create a new lense use FOR macro and COMPOSE function.

(defparameter *data* (list 1 2 3))
(defparameter *lense* (lense:for (elt :_ 0)))
(print (lense:read *lense* *data*)) ; => 1
(lense:write *lense* 10 *data*)
(print (lense:read *lense* *data*)) ; => 10
(defparameter *nested-data* (list *data*))
(defparameter *nested-lense* (lense:compose *lense* *lense*))
(print (lense:read *nested-lense* *nested-data*)) ; => 10
(lense:write *nested-lense* 1 *nested-data*)
(print (lense:read *nested-lense* *nested-data*)) ; => 1
(lense:transform *nested-lense* #'1+ *nested-data*)
(print (lense:read *nested-lense* *nested-data*)) ; => 2
(setf (lense:access *nested-lense* *nested-data*) 1)
(print (lense:access *nested-lense* *nested-data*)) ; => 1

Notes

Code generated by FOR macro will evaluate arguments for the place only once, regardless of any further calls to READ and WRITE. It will not perform full code walk in search of :_, it MUST occur on the first level. This will probabbly not change because any more complicated behavior would destroy equality between SETFable place and lense.

Extending

READ, WRITE, TRANSFORM are all generic functions. In addition to those, programmer may want to specialize GATHER function. ACCESS is just ordinary function that forwards all calls to READ nad WRITE generics and can be ignored.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 lense

Maintainer

Marek Kochanowicz

Author

Marek Kochanowicz

License

BSD-2

Description

Racket style lenses for the Common Lisp.

Version

0.0.0

Dependencies

• alexandria
• documentation-utils-extensions
• closer-mop

Source

lense.asd (file)

Components

• package.lisp (file)
• macros.lisp (file)
• types.lisp (file)
• protocol.lisp (file)
• implementation.lisp (file)
• documentation.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 lense.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/lense-20201220-git/lense.asd

Systems

lense (system)

3.1.2 lense/package.lisp

Parent

lense (system)

Location

package.lisp

Packages

lense

3.1.3 lense/macros.lisp

Dependency

package.lisp (file)

Parent

lense (system)

Location

macros.lisp

Exported Definitions

for (macro)

3.1.4 lense/types.lisp

Dependency

macros.lisp (file)

Parent

lense (system)

Location

types.lisp

Exported Definitions

• basic-lense (class)
• composed-lense (class)
• fundamental-lense (class)

Internal Definitions

• internal-lenses (method)
• read-callback (method)
• write-callback (method)

3.1.5 lense/protocol.lisp

Dependency

types.lisp (file)

Parent

lense (system)

Location

protocol.lisp

Exported Definitions

• access (function)
• (setf access) (function)
• compose (function)
• gather (generic function)
• read (generic function)
• transform (generic function)
• transform (method)
• write (generic function)

3.1.6 lense/implementation.lisp

Dependency

protocol.lisp (file)

Parent

lense (system)

Location

implementation.lisp

Exported Definitions

• gather (method)
• gather (method)
• read (method)
• read (method)
• transform (method)
• write (method)
• write (method)

3.1.7 lense/documentation.lisp

Dependency

implementation.lisp (file)

Parent

lense (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 lense

Source

package.lisp (file)

Use List

• alexandria
• common-lisp

Exported Definitions

• access (function)
• (setf access) (function)
• basic-lense (class)
• compose (function)
• composed-lense (class)
• for (macro)
• fundamental-lense (class)
• gather (generic function)
• gather (method)
• gather (method)
• read (generic function)
• read (method)
• read (method)
• transform (generic function)
• transform (method)
• transform (method)
• write (generic function)
• write (method)
• write (method)

Internal Definitions

• internal-lenses (generic function)
• internal-lenses (method)
• read-callback (generic function)
• read-callback (method)
• write-callback (generic function)
• write-callback (method)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Macros

Macro: for (SYMBOL &rest ARGUMENTS)

Description:
Macro. Expands to construction of BASIC-LENS for designated SETFable place.

Exceptional situations:
Use of this macro should include one symbol :_ in the arguments designating position in the lambda list where OBJECT should be placed. If there is either more than one such symbol in the ARGUMETS or there is none, the CL:PROGRAM-ERROR will be raised.

Package

lense

Source

macros.lisp (file)

5.1.2 Functions

Function: access LENSE OBJECT

Description:
SETFable alternative to the READ function.

See also:
–READ
–WRITE

Package

lense

Source

protocol.lisp (file)

Writer

(setf access) (function)

Function: (setf access) VALUE LENSE OBJECT

Package

lense

Source

protocol.lisp (file)

Reader

access (function)

Function: compose LENSE &rest MORE-LENSES

Description:
Stacks lenses on each other to build a COMPOSED-LENS.

Returns:
Instance of COMPOSED-LENSE.

Exceptional situations:
Every argument must be a lense supporting GATHER function.

Package

lense

Source

protocol.lisp (file)

5.1.3 Generic functions

Generic Function: gather LENSE &optional DESTINATION-VECTOR

Description:
This function gathers all elementary lenses from the input lense into the DESTINATION-VECTOR. This is required for the simplicity and efficiency of the COMPOSE function. Constructed COMPOSED-LENSE has flat internal lenses structure which eleminates pointless recursive calls that can potentially occur otherwise.

Returns:
DESTINATION-VECTOR

Exceptional situations:
Will signal CL:TYPE-ERROR (with interactive restart) if DESTINATION-VECTOR is not (AND (VECTOR T) (SATISFIES ADJUSTABLE-ARRAY-P))

Package

lense

Source

protocol.lisp (file)

Methods

Method: gather (LENSE composed-lense) &optional DESTINATION-VECTOR

Source

implementation.lisp (file)

Method: gather (LENSE fundamental-lense) &optional DESTINATION-VECTOR

Source

implementation.lisp (file)

Generic Function: read LENSE OBJECT

Arguments:
–LENSE, LENS used to read the OBJECT.
–OBJECT, OBJECT that is being read.

Description:
Read trough the lens. Use the LENS to retrieve value from the OBJECT.

Returns:
Value obtained.

See also:
–ACCESS
–WRITE

Notes:
Instead of calling this function, one may funcall LENSE object directly on data.

Package

lense

Source

protocol.lisp (file)

Methods

Method: read (LENSE composed-lense) OBJECT

Source

implementation.lisp (file)

Method: read (LENSE basic-lense) OBJECT

Source

implementation.lisp (file)

Generic Function: transform LENSE TRANSFORMATION OBJECT

Description:
READ value from the lens. FUNCALL passed transformation on the value. WRITE value back, using the same lense.

Exceptional situations:
–Will signal CL:TYPE-ERROR (with restart) if TRANSFORMATION is not a function.

Notes:
Specialization of this generic function for the COMPOSED-LENSE will not pipe object via the sublenses twice.

Package

lense

Source

protocol.lisp (file)

Methods

Method: transform (LENSE composed-lense) TRANSFORMATION OBJECT

Source

implementation.lisp (file)

Method: transform (LENSE fundamental-lense) TRANSFORMATION OBJECT

Generic Function: write LENSE VALUE OBJECT

Arguments:
–LENSE, LENS used to read the OBJECT.
–VALUE, VALUE deposited into the OBJECT.
–OBJECT, OBJECT that is being read.

Description:
Write trough the lens. Use the LENS to deposit value into the OBJECT.

See also:
–ACCESS
–READ

Package

lense

Source

protocol.lisp (file)

Methods

Method: write (LENSE composed-lense) VALUE OBJECT

Source

implementation.lisp (file)

Method: write (LENSE basic-lense) VALUE OBJECT

Source

implementation.lisp (file)

5.1.4 Classes

Class: basic-lense ()

Description:
Elementary lense, acts as a wrapper around an setfable place. Constructed by expansion of LENS:FOR macro.

Package

lense

Source

types.lisp (file)

Direct superclasses

fundamental-lense (class)

Direct methods

• write (method)
• read (method)
• write-callback (method)
• read-callback (method)

Direct slots

Slot: %read-callback

Initargs

:read-callback

Readers

read-callback (generic function)

Slot: %write-callback

Initargs

:write-callback

Readers

write-callback (generic function)

Class: composed-lense ()

Description:
COMPOSED-LENSE pipes all READ, WRITE and COMPOSE calls trough the lenses used to construct the result (from left to right, in the opposite order to the ALEXANDRIA:COMPOSE).

Package

lense

Source

types.lisp (file)

Direct superclasses

fundamental-lense (class)

Direct methods

• write (method)
• transform (method)
• read (method)
• gather (method)
• internal-lenses (method)

Direct slots

Slot: %internal-lenses

Initargs

:internal-lenses

Readers

internal-lenses (generic function)

Class: fundamental-lense ()

Description:
Fundamental class of all lenses. All subclasses of this class should support following generic functions: READ, WRITE. TRANSFORM and GATHER have potentially usefull default methods (TRANSFORM simply calls READ and WRITE in a succession which may or may not be efficient, GATHER simply puts the lense into the result vector).

Package

lense

Source

types.lisp (file)

Direct superclasses

funcallable-standard-object (class)

Direct subclasses

• basic-lense (class)
• composed-lense (class)

Direct methods

• gather (method)
• initialize-instance (method)
• transform (method)

5.2 Internal definitions

5.2.1 Generic functions

Generic Function: internal-lenses OBJECT

Package

lense

Methods

Method: internal-lenses (COMPOSED-LENSE composed-lense)

automatically generated reader method

Source

types.lisp (file)

Generic Function: read-callback OBJECT

Package

lense

Methods

Method: read-callback (BASIC-LENSE basic-lense)

automatically generated reader method

Source

types.lisp (file)

Generic Function: write-callback OBJECT

Package

lense

Methods

Method: write-callback (BASIC-LENSE basic-lense)

automatically generated reader method

Source

types.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types