The lense Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The lense Reference Manual

This is the lense Reference Manual, version 0.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 13:58:55 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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
Source

lense.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 lense.asd

Location

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

Systems

lense (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 lense/package.lisp

Parent

lense (system)

Location

package.lisp

Packages

lense


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 lense/macros.lisp

Dependency

package.lisp (file)

Parent

lense (system)

Location

macros.lisp

Exported Definitions

for (macro)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 lense/types.lisp

Dependency

macros.lisp (file)

Parent

lense (system)

Location

types.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 lense/protocol.lisp

Dependency

types.lisp (file)

Parent

lense (system)

Location

protocol.lisp

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.6 lense/implementation.lisp

Dependency

protocol.lisp (file)

Parent

lense (system)

Location

implementation.lisp

Exported Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.7 lense/documentation.lisp

Dependency

implementation.lisp (file)

Parent

lense (system)

Location

documentation.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 lense

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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
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
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
Direct methods

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
File, Lisp, lense.asd: The lense․asd file
File, Lisp, lense/documentation.lisp: The lense/documentation․lisp file
File, Lisp, lense/implementation.lisp: The lense/implementation․lisp file
File, Lisp, lense/macros.lisp: The lense/macros․lisp file
File, Lisp, lense/package.lisp: The lense/package․lisp file
File, Lisp, lense/protocol.lisp: The lense/protocol․lisp file
File, Lisp, lense/types.lisp: The lense/types․lisp file

L
lense.asd: The lense․asd file
lense/documentation.lisp: The lense/documentation․lisp file
lense/implementation.lisp: The lense/implementation․lisp file
lense/macros.lisp: The lense/macros․lisp file
lense/package.lisp: The lense/package․lisp file
lense/protocol.lisp: The lense/protocol․lisp file
lense/types.lisp: The lense/types․lisp file
Lisp File, lense.asd: The lense․asd file
Lisp File, lense/documentation.lisp: The lense/documentation․lisp file
Lisp File, lense/implementation.lisp: The lense/implementation․lisp file
Lisp File, lense/macros.lisp: The lense/macros․lisp file
Lisp File, lense/package.lisp: The lense/package․lisp file
Lisp File, lense/protocol.lisp: The lense/protocol․lisp file
Lisp File, lense/types.lisp: The lense/types․lisp file

Jump to:   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   F   G   I   M   R   T   W  
Index Entry  Section

(
(setf access): Exported functions

A
access: Exported functions

C
compose: Exported functions

F
for: Exported macros
Function, (setf access): Exported functions
Function, access: Exported functions
Function, compose: Exported functions

G
gather: Exported generic functions
gather: Exported generic functions
gather: Exported generic functions
Generic Function, gather: Exported generic functions
Generic Function, internal-lenses: Internal generic functions
Generic Function, read: Exported generic functions
Generic Function, read-callback: Internal generic functions
Generic Function, transform: Exported generic functions
Generic Function, write: Exported generic functions
Generic Function, write-callback: Internal generic functions

I
internal-lenses: Internal generic functions
internal-lenses: Internal generic functions

M
Macro, for: Exported macros
Method, gather: Exported generic functions
Method, gather: Exported generic functions
Method, internal-lenses: Internal generic functions
Method, read: Exported generic functions
Method, read: Exported generic functions
Method, read-callback: Internal generic functions
Method, transform: Exported generic functions
Method, transform: Exported generic functions
Method, write: Exported generic functions
Method, write: Exported generic functions
Method, write-callback: Internal generic functions

R
read: Exported generic functions
read: Exported generic functions
read: Exported generic functions
read-callback: Internal generic functions
read-callback: Internal generic functions

T
transform: Exported generic functions
transform: Exported generic functions
transform: Exported generic functions

W
write: Exported generic functions
write: Exported generic functions
write: Exported generic functions
write-callback: Internal generic functions
write-callback: Internal generic functions

Jump to:   (  
A   C   F   G   I   M   R   T   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %  
S  
Index Entry  Section

%
%internal-lenses: Exported classes
%read-callback: Exported classes
%write-callback: Exported classes

S
Slot, %internal-lenses: Exported classes
Slot, %read-callback: Exported classes
Slot, %write-callback: Exported classes

Jump to:   %  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   F   L   P   S  
Index Entry  Section

B
basic-lense: Exported classes

C
Class, basic-lense: Exported classes
Class, composed-lense: Exported classes
Class, fundamental-lense: Exported classes
composed-lense: Exported classes

F
fundamental-lense: Exported classes

L
lense: The lense system
lense: The lense package

P
Package, lense: The lense package

S
System, lense: The lense system

Jump to:   B   C   F   L   P   S