The fresnel Reference Manual

This is the fresnel Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jan 15 06:10:48 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 fresnel

Bidirectional translation with lenses

Author

GrammaTech

License

MIT

Dependencies
  • fare-quasiquote-extras (system).
  • trivial-package-local-nicknames (system).
  • fresnel/fresnel (system).
Source

fresnel.asd.


2.2 fresnel/fresnel

Author

GrammaTech

License

MIT

Dependencies
  • gt/full (system).
  • trivial-package-local-nicknames (system).
  • fresnel/lens (system).
Source

fresnel.asd.


2.3 fresnel/lens

Author

GrammaTech

License

MIT

Dependency

trivial-package-local-nicknames (system).

Source

fresnel.asd.


3 Files

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


3.1 Lisp


3.1.1 fresnel/fresnel.asd

Source

fresnel.asd.

Parent Component

fresnel (system).

ASDF Systems

3.1.2 fresnel/fresnel/file-type.lisp

Source

fresnel.asd.

Parent Component

fresnel/fresnel (system).

Packages

fresnel/fresnel.

Public Interface
Internals

build-read-print-lens (function).


3.1.3 fresnel/lens/file-type.lisp

Source

fresnel.asd.

Parent Component

fresnel/lens (system).

Packages
Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 fresnel/lens

Lenses for bidirectional transformations.

As defined by Foster et al., 2007; Foster et al., 2008; Bohannon et al., 2008; and Foster et al., 2009.

It is not recommended to :USE this package; use a package-local nickname:

(:local-nicknames (:l :fresnel/lens))

The convention is for lens constructors to be functions, even if they take no arguments (such as IDENTITY). This is to be consistent with other, parametric lens constructors. For example, CAR can be called with either zero or one argument rather than having a function that takes one argument and a non-function for the zero-argument case.

The DISCERN and MATCH macros, and the CHECK, NILABLE, PATTERN, and OR functions, deal with discerning lenses. A discerning lens is a quotient lens that partitions its set of concrete structures (and similarly, its set of abstract structures) into two subsets: a set of "well-formed" values and a set of "ill-formed" values. While the set of well-formed values can be equipped with any equivalence relation as usual, all ill-formed values are considered equivalent to each other.

For each of the three functions of a discerning lens, the following must be true iff the (first) argument to the function was ill-formed:

- The first of the VALUES returned by the function is ill-formed.

- The last of the VALUES returned by the function is NIL.

By these conventions, for instance, the IDENTITY lens is discerning with NIL as its only ill-formed value, but the CAR lens is not discerning. The DISCERN macro can be wrapped around a usage of a discerning lens in order to get both the primary return value and the well-formedness together, as a single value (a cons).

Source

file-type.lisp.

Public Interface

4.2 fresnel-user

Source

file-type.lisp.

Use List

gt/full.


4.3 fresnel/fresnel

Very high-level lenses; nothing language-specific.

Source

file-type.lisp.

Use List
  • gt/full.
  • trivial-package-local-nicknames.
Public Interface
Internals

build-read-print-lens (function).


4.4 fresnel/lens.impl

Internal package where lenses are actually
implemented. (Working in the lens package is inconvenient as it shadows many common functions).

Source

file-type.lisp.

Use List
  • gt/full.
  • trivial-package-local-nicknames.
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Macros

Macro: discern (form)

Return a cons cell of the primary value and well-formedness from FORM.

The FORM must evaluate to the result of calling one of the functions of a discerning lens. The car of the cons cell returned by this macro is the primary value returned by FORM, and the cdr is a boolean indicating whether that value is well-formed.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: discern-values (form)

Return two values: the primary value of FORM, and its well-formedness.

FORM must evaluate to the result of calling one of the functions of a discerning lens. The first value returned by this macro is the primary value returned by FORM, and the second is a boolean indicating whether that value is well-formed.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: lazy-list (&rest lenses)

Like ‘l:list’, but does not evaluate LENSES until the lens is called. Note LENSES may be evaluated more than once!

Package

fresnel/lens.

Source

file-type.lisp.

Macro: lazy-list* (&rest lenses)

Like ‘l:list*’, but does not evaluate LENSES until the lens is called. Note LENSES may be evaluated more than once!

Package

fresnel/lens.

Source

file-type.lisp.

Macro: map (&rest kvs)

Same as ‘fset:map’.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: match (bindings &body patterns)

Return a discerning lens using BINDINGS to translate between PATTERNS.

PATTERNS is a list where every two elements, a concrete form and an abstract form, defines one lens.

Each multiple of two patterns is compiled into a separate lens, and the lens are implicitly combined with ‘l:or’.

If there is only one pattern, it is repeated. (This is an abbreviation for when the concrete and abstract forms are the same.)

If any pattern is of the form ‘($ PAT)’, then PAT is macroexpanded and the expansion is treated as the real pattern.

The BINDINGS are similar to those of a LET: each one is a list whose first element is a symbol and whose second element is a form that evaluates to a discerning lens. There may also be a third element, which is used a default in the ‘create’ direction.

The concrete form is a Trivia pattern (using the symbols from BINDINGS) that would evaluate to some concrete structure when given appropriate values for each of the symbols in BINDINGS.

Likewise the abstract form is a Trivia pattern, using the symbols from BINDINGS, that would evaluate to some abstract structure when given appropriate values.

Note that the symbols used by the concrete form/pattern and the symbols used by the abstract form/pattern do not need to be the same; the only requirement is that they both be subsets of the variables bound in BINDINGS.

If the concrete form/pattern omits variables, they are always defaulted with the provided defaults.

If the abstract pattern omits variables, the way the concrete form evaluates differs between ‘create’ and ‘put’.

If the concrete form is being evaluated in the ‘create’ direction, then missing symbols are filled in from provided defaults in the bindings of the ‘l:match’ form.

If the concrete form is being evaluated in the ‘put’ direction, then missing symbols are filled in from the provided member of the concrete domain (by matching it against the concrete pattern with ‘get’).

The GET direction first attempts to find values for the symbols in BINDINGS that would make the concrete pattern match the input. If no such values can be found, NIL is returned. Otherwise, those values are each sent through their respective lenses defined by BINDINGS, and if each of those lenses produced well-formed values, their outputs are used to construct the final output via the abstract form. The CREATE direction is analogous.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: match-constructors (bindings &body patterns)
Package

fresnel/lens.

Source

file-type.lisp.

Macro: match-list (&body bindings)

Like ‘l:match’ for translating from list to list.
If each list has the same length, and that length is the same as the length of the bindings, there is no need to spell it out.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: match-list* (&body bindings)

Like ‘l:match-list’, but the last binding is applied to the tail, instead of per-element.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: seq (&rest items)

Same as ‘fset:seq’.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: with-component-lenses ((&rest bindings) fn &body body)

A helper macro for ‘l:match’.

The BINDINGS are similar to those of a LET: each one is a list whose first element is a symbol and whose second element is a form that evaluates to a discerning lens.

FN should be one of ‘l:get’, ‘l:create’, or ‘l:put’. (If you are using ‘l:put’ directly you many want to establish component-wise defaults using ‘l:with-defaults’).

Within BODY, the variables in BINDINGS are rebound to the result of calling the requested lens on the existing value of that binding, using FN.

If any lens is ill-formed (returns nil as its last value) then BODY is not evaluated and the entire form returns nil.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: with-create-lenses ((&rest bindings) &body body)

Same as ‘l:with-component-lenses’ with ‘l:create’ as its function.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: with-get-lenses ((&rest bindings) &body body)

Same as ‘l:with-component-lenses’ with ‘l:get’ as its function.

Package

fresnel/lens.

Source

file-type.lisp.

Macro: with-put-lenses ((&rest bindings) &body body)

Same as ‘l:with-component-lenses’ with ‘l:put’ as its function.

Package

fresnel/lens.

Source

file-type.lisp.


5.1.2 Ordinary functions

Function: acond (c1 a1 l1 l2)

Return a lens that applies L1 or L2 depending on whether C1 or A1 hold.

The domains of L1 and L2 must be disjoint, as must be the codomains of L1 and L2. In the forward direction, applies the C1 predicate, then uses L1 if true or L2 if false. In the reverse direction, applies the A1 predicate, then uses L1 if true or L2 if false. Uses CREATE instead of PUT if C1 and A1 disagree in the reverse direction.

Same as "acond" from Foster et al., 2007.

Package

fresnel/lens.

Source

file-type.lisp.

Function: after (&rest lenses)

Right quotient each lens in LENSES with the next lens. That is, all but the first lens should be canonizers.

Package

fresnel/lens.

Source

file-type.lisp.

Function: alist-lens (alist &rest args &key &allow-other-keys)

Wrap an association list as a bijective lens.
GET on the lens becomes assoc, and CREATE on the lens becomes rassoc.

Package

fresnel/fresnel.

Source

file-type.lisp.

Function: alist-mapping (l &key test)

Lens that maps L over the values of an alist. TEST is the equality predicate on keys.

Package

fresnel/lens.

Source

file-type.lisp.

Function: backward (l a &optional c)
Package

fresnel/lens.

Source

file-type.lisp.

Function: before (&rest lenses)

Left quotient each lens in LENSES with the previous lens. That is, all but the last lens should be canonizers.

Package

fresnel/lens.

Source

file-type.lisp.

Function: bij (get &optional create)

Return a bijective lens from the given GET function and its inverse, CREATE.

Similar to "bij" from Hoffmann et al., 2010, except that BIJ takes both directions of the bijection instead of just the forward direction.

Package

fresnel/lens.

Source

file-type.lisp.

Function: canonize (canonizer value)

Call the canonize function from CANONIZER on VALUE.

Package

fresnel/lens.

Source

file-type.lisp.

Function: canonize-after (fn)
Package

fresnel/lens.

Source

file-type.lisp.

Function: canonize-before (fn)
Package

fresnel/lens.

Source

file-type.lisp.

Function: canonizer (canonize &optional choose)

Build a canonizer from two functions, CANONIZE and CHOOSE. CANONIZE and CHOOSE are treated as discerning, with special behavior: if they fail then the original values are passed through unchanged. This makes writing canonizers easier, as you don’t have to remember to explicitly pass through irrelevant values.

Package

fresnel/lens.

Source

file-type.lisp.

Function: car (&optional d)

Return a lens to extract the car of a cons cell.

If D is given, uses it as a default cdr value for CREATE.

Similar to "hd" from Foster et al., 2007, except that CAR makes D optional and simply omits the "create" function if D is not provided.

Package

fresnel/lens.

Source

file-type.lisp.

Function: cdr (&optional d)

Return a lens to extract the cdr of a cons cell.

If D is given, uses it as a default car value for CREATE.

Similar to "tl" from Foster et al., 2007, except that CDR makes D optional and simply omits the "create" function if D is not provided.

Package

fresnel/lens.

Source

file-type.lisp.

Function: check (pred)

Return a discerning identity lens whose well-formed values all satisfy PRED.

Package

fresnel/lens.

Source

file-type.lisp.

Function: check-laws (lens c a &key test)

Check that LENS obeys the lens laws for C, a concrete value, and A, an abstract value, using TEST as the equivalence relation.

Returns four boolean values:
1. Whether all the laws were respected.
2. Whether GetPut was respected.
3. Whether PutGet was respected.
4. Whether CreateGet was respected.

Package

fresnel/lens.

Source

file-type.lisp.

Function: check-subtype (type)

Return a discering identity lens whose well-formed values are subtypes of TYPE.

Package

fresnel/lens.

Source

file-type.lisp.

Function: check-type (type)

Return a discering identity lens whose well-formed values are of TYPE.

Package

fresnel/lens.

Source

file-type.lisp.

Function: choose (canonizer value)

Call the choose function from CANONIZER on VALUE.

Package

fresnel/lens.

Source

file-type.lisp.

Function: combine (combiner lens)

Convert a bijection into a lens.

Return a lens that, in the PUT direction, uses COMBINER, a function, to augment the value constructed by LENS with the old value.

Converts a bijection into a lens by using COMBINER to "patch" the result of ‘create’ with the old concrete value.

Package

fresnel/lens.

Source

file-type.lisp.

Function: compose (&rest lenses)

Return a lens that abstracts through the LENSES in order.

Similar to the semicolon combinator from Foster et al., 2007, except that COMPOSE acts like ALEXANDRIA:COMPOSE in that (in the forward direction) lenses are applied from back to front rather than from front to back. That is, l;k is the same as (compose k l).

Allows the composition of zero lenses, equivalent to the identity
lens.

Package

fresnel/lens.

Source

file-type.lisp.

Function: compose* (&rest lenses)

Like ‘l:compose’, but discerning.

Package

fresnel/lens.

Source

file-type.lisp.

Function: cons (l1 l2)

Return a lens that applies L1 to the car, and L2 to cdr, of a cons cell.

Inspired by "xfork" from Foster et al., 2007.

Package

fresnel/lens.

Source

file-type.lisp.

Function: constantly (v &optional d)

Return a lens that always returns V.

If D is given, uses it as a default value for CREATE.

Similar to "const" from Foster et al., 2007, except that CONSTANTLY makes D optional and simply omits the "create" function if D is not provided.

Package

fresnel/lens.

Source

file-type.lisp.

Function: create (l a)

Return a concrete value from the abstract view A through the lens L.

Package

fresnel/lens.

Source

file-type.lisp.

Function: default (x)

As a function, identity.

As a Trivia pattern, matches anything.

Package

fresnel/lens.

Source

file-type.lisp.

Function: forward (l c &key fail-on-error)
Package

fresnel/lens.

Source

file-type.lisp.

Function: fset-mapping (l)

Lens that maps L over the values of an FSet map.

Package

fresnel/lens.

Source

file-type.lisp.

Function: gensym-lens ()

Lens to convert between a concrete string to an abstract gensym.

Package

fresnel/fresnel.

Source

file-type.lisp.

Function: gensym? (x)

Is X a symbol without a package?

Package

fresnel/fresnel.

Source

file-type.lisp.

Function: get (l c)

Return an abstract view of C through the lens L.

Not analogous to CL:GET.

Package

fresnel/lens.

Source

file-type.lisp.

Function: guard (pred lens)

Return a discerning lens whose well-formed concrete values all satisfy PRED.

Package

fresnel/lens.

Source

file-type.lisp.

Function: hash-table-alist (&key test)

Lens that translates between hash tables and alists.
In the PUT direction, the hash table test is taken from the old hash table; otherwise TEST is used.

Package

fresnel/lens.

Source

file-type.lisp.

Function: hash-table-mapping (l)

Lens that maps L over the values of a hash table. See ‘l:mapping’ for the details.

Package

fresnel/lens.

Source

file-type.lisp.

Function: identity ()

Return the identity lens.

Same as "id" from Foster et al., 2007.

Package

fresnel/lens.

Source

file-type.lisp.

Function: identity! ()

Like l:identity, but returns T as its second value. This allows it to work even on null values.

Package

fresnel/lens.

Source

file-type.lisp.

Function: keyword-lens ()

Lens to convert between a concrete string and an abstract keyword.

Package

fresnel/fresnel.

Source

file-type.lisp.

Function: lazy (f)

Return a lens that acts like the lens returned by F.

Doesn’t call F until necessary, but also doesn’t cache the result of F. To get caching, compose this function with something like SERAPEUM:ONCE.

Package

fresnel/lens.

Source

file-type.lisp.

Function: lens (get put &optional create)

Create a lens from GET, PUT, and CREATE functions.
If CREATE is not provided, it is treated as PUT with a concrete argument of nil.

Package

fresnel/lens.

Source

file-type.lisp.

Function: list (&rest lenses)

Return a lens that matches a sequence of lenses.
That is, it matches values that are sequences of the same length as LENSES, if every lens in LENSES matches the element at the same position in the value.

Package

fresnel/lens.

Source

file-type.lisp.

Function: list* (&rest lenses)

Like ‘l:list’, but the last lens matches a tail of unspecified length.

Package

fresnel/lens.

Source

file-type.lisp.

Function: lquot (canonizer lens)

Coarsen the (concrete) domain of QLENS using CANONIZER.
Return a new q-lens.

Composes the get function of QLENS with the canonizer of Q and composes the chooser of Q with the put/create function of QLENS.

When using ‘lquot’, only concrete values are changed. The canonizer is called directly on the concrete arguments to GET and PUT, while the chooser is called on the concrete result of CREATE and PUT (if they succeed).

Package

fresnel/lens.

Source

file-type.lisp.

Function: lquot* (&rest lenses)

Reduce lenses with ‘l:lquot’, from the end.

Package

fresnel/lens.

Source

file-type.lisp.

Function: make-lens (get &optional create put)
Package

fresnel/lens.

Source

file-type.lisp.

Function: mapcar (l)

Return a lens that applies L to every element of a list.

Similar to "list_map" from Foster et al., 2007.

This is a discerning lens: L is assumed to be discerning, and if it fails for any element, then the entire lens fails.

Package

fresnel/lens.

Source

file-type.lisp.

Function: mapping (lens &key maker getter setter walker)

Low-level lens that maps LENS over some kind of key-value mapping (table).

If you are writing lenses for translation, you probably want to use ‘alist-mapping’, ‘hash-table-mapping’, or ‘fset-mapping’. This function is lower-level, for supporting new tabular data structures in a consistent way.

In the GET direction, the new lens returns an abstract table where the keys are the same as the concrete table, but the values are the result of passing each value through LENS.

In the CREATE direction, the new lens returns a concrete table with the same keys (domain) as the abstract table, and values derived by passing the values through LENS.

In the PUT direction, the new lens also returns a concrete table with the same keys as the abstract table, but the values depend on which keys are also present in the concrete table. If the same key is present in both tables, then the new concrete value is computed using PUT with the abstract value and the old concrete value; otherwise CREATE is used.

Note that it is always the case (by design) that keys that are present in the concrete table but not the abstract table are lost.

Takes four callbacks:

1. MAKER is a function of one argument that creates a new, empty mapping that is "like" its argument (e.g. a hash table having
the same test.)

2. GETTER takes a table and a key and returns two values (like ‘gethash’, but the table comes before the key).

3. SETTER takes a table, a key, and a value, and returns a table updated with the new key and value. It is fine if the table is mutated, but the return value has to be the table.

4. WALKER takes a table and a binary function and maps it over the entries in the table (like ‘maphash’).

Package

fresnel/lens.

Source

file-type.lisp.

Function: nilable (l)

Return a discerning lens that acts like L but has no ill-formed values.

Package

fresnel/lens.

Source

file-type.lisp.

Function: of-type (type)

Return a discering identity lens whose well-formed values are of TYPE.

Package

fresnel/lens.

Source

file-type.lisp.

Function: opp (l)

Return a bijective lens that acts like L in reverse.

Completely discards all PUT behavior of L, making use only of GET and CREATE.

Similar to "op" from Hoffmann et al., 2010, except that OPP is not involutory because the lenses defined in this package are not symmetric.

Package

fresnel/lens.

Source

file-type.lisp.

Function: optional (x)

Return a lens that matches whatever X matches, or nil. X must not match nil itself.

Package

fresnel/lens.

Source

file-type.lisp.

Function: or (&rest lenses)

Return a lens that tries LENSES in order until one succeeds. A lens succeeds if the last value it returns is not ‘nil’.

Package

fresnel/lens.

Source

file-type.lisp.

Function: or! (&rest lenses)

Like ‘l:or’, but strict.
If more than one lens in LENSES matches, that’s an error.

Package

fresnel/lens.

Source

file-type.lisp.

Function: path (path)

Return a lens to access the subtree of an FSet structure at PATH.

Package

fresnel/lens.

Source

file-type.lisp.

Function: print-read-lens (type &rest args &key)

Like ‘read-print-lens’, but translates between concrete values and abstract strings.

Package

fresnel/fresnel.

Source

file-type.lisp.

Function: put (l a c)

Return an updated version of C using the abstract view A through the lens L.

Package

fresnel/lens.

Source

file-type.lisp.

Function: qlens (get put create)
Package

fresnel/lens.

Source

file-type.lisp.

Function: rguard (pred lens)

Return a discerning lens whose well-formed abstract values all satisfy PRED.

Package

fresnel/lens.

Source

file-type.lisp.

Function: rquot (canonizer lens)

Coarsen the (abstract) codomain of QLENS using CANONIZER.
Return a new q-lens.

Composes the choose function of CANONIZER with the get function of QLENS, and composes the put/create function of QLENS with the canonizer function of CANONIZER.

When using ‘rquot’, only abstract values are changed. The canonizer is called directly on the abstract arguments to PUT and CREATE, while the chooser is called on the abstract result of GET (if it succeeds).

Package

fresnel/lens.

Source

file-type.lisp.

Function: rquot* (&rest lenses)

Reduce lenses with ‘l:rquot’, from the end.

Package

fresnel/lens.

Source

file-type.lisp.

Function: satisfies (pred)
Package

fresnel/lens.

Source

file-type.lisp.

Function: some (l)

Like l:mapcar, but as soon as one result matches, use that.

Package

fresnel/lens.

Source

file-type.lisp.

Function: trace ()

Trace (successful) lens matching.

Package

fresnel/lens.

Source

file-type.lisp.

Function: untrace ()

Stop tracing lens matching.

Package

fresnel/lens.

Source

file-type.lisp.


5.1.3 Generic functions

Generic Function: read-print-lens (type &key format package)

Construct a lens to translate between concrete
strings and abstract values of type TYPE, using the appropriate Lisp reader/parser and printer.

Package

fresnel/fresnel.

Source

file-type.lisp.

Methods
Method: read-print-lens ((type (eql integer)) &key)
Method: read-print-lens ((type (eql number)) &key)
Method: read-print-lens ((type (eql float)) &key format)
Method: read-print-lens ((type (eql double-float)) &key)
Method: read-print-lens ((type (eql single-float)) &key)
Method: read-print-lens ((type (eql symbol)) &key package)

5.1.4 Standalone methods

Method: convert ((to-type (eql fresnel/lens:qlens)) (l lens) &key)
Package

fset.

Source

file-type.lisp.

Method: convert ((to-type (eql fresnel/lens:canonizer)) (l qlens) &key)
Package

fset.

Source

file-type.lisp.

Method: convert ((to-type (eql fresnel/lens:canonizer)) (l canonizer) &key)
Package

fset.

Source

file-type.lisp.

Method: initialize-instance :after ((l qlens) &key get put create)
Source

file-type.lisp.

Reader Method: lens-error-lens ((condition lens-error))
Package

keyword.

Source

file-type.lisp.

Target Slot

lens.

Method: print-object ((self lens) stream)
Source

file-type.lisp.

Method: print-object ((self bij) stream)
Source

file-type.lisp.


5.1.5 Classes

Class: bij

Every bijection is also a lens, using a put function that ignores its second arg.

Package

fresnel/lens.

Source

file-type.lisp.

Direct superclasses

lens.

Direct subclasses

canonizer.

Direct methods

print-object.

Class: canonizer

A canonizer is a kind of bijection.
A lens is "quotiented" with a canonizer, resulting in a quotient lens.

The canonize function of the canonizer is called on arguments to the lens; the choose function of the canonizer is called on the values the lens returns.

Package

fresnel/lens.

Source

file-type.lisp.

Direct superclasses

bij.

Direct methods
Direct slots
Slot: get

Function that maps an element to its canonical representative.

Initargs

:canonize

Readers

canonize-fn.

Writers

This slot is read-only.

Slot: create

Function that maps a canonical representive to some element.

Initargs

:choose

Readers

choose-fn.

Writers

This slot is read-only.

Class: lens

A basic lens.

Lenses are a kind of bidirectional transformation.

Lenses generalize bijections by allowing the transformation in the forward direction (get) to be non-injective. (Put is still injective, however.)

Lenses must satisfy the following laws:

- GetPut: (put l (get l c) c) = c for all c from C
- PutGet: (get l (put l a c)) = a for all (a, c) from A × C
- CreateGet: (get l (create l a)) = a for all a from A

Of course, the CreateGet law need not hold for a lens that does not have a CREATE function.

Package

fresnel/lens.

Source

file-type.lisp.

Direct superclasses

qlens.

Direct subclasses

bij.

Direct methods
Class: qlens

Quotient lenses generalize lenses so that the lens laws are respected up to some equivalence relation.

Lenses may be "quotiented" arbitrarily with canonizers (a kind of bijective lens) on the left (concrete) or right (abstract) side. This allows a style where canonicalization is pervasive and interleaved rather than being done in one step at the edges.

Practically they treat certain data as ignorable.

Package

fresnel/lens.

Source

file-type.lisp.

Direct subclasses

lens.

Direct methods
Direct slots
Slot: get

A function from C to A.

Type

(function (t) t)

Readers

get-fn.

Writers

This slot is read-only.

Slot: put

A function from A × C to C.

Type

(function (t t) t)

Readers

put-fn.

Writers

This slot is read-only.

Slot: create

A function from A to C.

Need not be defined on every lens; if it is unbound, then the CREATE function simply throws an error.

Type

(function (t) t)

Readers

create-fn.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Constants

Constant: +storage-for-deflex-var-+unbound++

Distinguished value that makes a binding morally unbound.

Package

fresnel/lens.impl.

Source

file-type.lisp.


5.2.2 Special variables

Special Variable: *depth*

Depth of lens matching.

Package

fresnel/lens.impl.

Source

file-type.lisp.

Special Variable: *trace*

Are we tracing?

Package

fresnel/lens.impl.

Source

file-type.lisp.


5.2.3 Symbol macros

Symbol Macro: %concrete-defaults
Package

fresnel/lens.impl.

Source

file-type.lisp.

Symbol Macro: +identity-lens+
Package

fresnel/lens.impl.

Source

file-type.lisp.

Symbol Macro: +unbound+
Package

fresnel/lens.impl.

Source

file-type.lisp.


5.2.4 Macros

Macro: match-two (bindings &body c-form)

Actually construct a lens from a pair of concrete and abstract forms.

Package

fresnel/lens.impl.

Source

file-type.lisp.

Macro: with-morally-unbound-variables ((&rest vars) &body body)

Bind VARS around BODY in such a way that they are morally unbound.

Package

fresnel/lens.impl.

Source

file-type.lisp.


5.2.5 Ordinary functions

Function: build-read-print-lens (type parser unparser)

Construct a bijection between a concrete string and an abstract value of TYPE using a function PARSER and a function UNPARSER.

The lens only matches if the value returned by PARSER is of TYPE. Errors of type ‘parse-error’ from PARSER are also considered failures.

Package

fresnel/fresnel.

Source

file-type.lisp.

Function: discern-values* (fn)

Helper function for ‘discern-values’.

Package

fresnel/lens.impl.

Source

file-type.lisp.

Function: extract-defaults (bindings)
Package

fresnel/lens.impl.

Source

file-type.lisp.

Function: lensify (x)
Package

fresnel/lens.impl.

Source

file-type.lisp.

Function: lookup-default (col key default)

Like ‘fset:lookup’, but return DEFAULT if KEY was not present. The second value is T if the key was present, NIL otherwise.

Package

fresnel/lens.impl.

Source

file-type.lisp.

Function: maybe-trace (direction names lens-forms &rest results)

If tracing, print the results of successful lens matching.

Package

fresnel/lens.impl.

Source

file-type.lisp.

Function: morally-unbound? (sym env)

Return non-nil if SYM is (morally) unbound in ENV.

Package

fresnel/lens.impl.

Source

file-type.lisp.

Function: split-bindings (bindings)

Split a two-element list into a list of the first elements and a list of the second elements.

Package

fresnel/lens.impl.

Source

file-type.lisp.


5.2.6 Generic functions

Generic Reader: canonize-fn (object)
Package

fresnel/lens.impl.

Methods
Reader Method: canonize-fn ((canonizer canonizer))

Function that maps an element to its canonical representative.

Source

file-type.lisp.

Target Slot

get.

Generic Reader: choose-fn (object)
Package

fresnel/lens.impl.

Methods
Reader Method: choose-fn ((canonizer canonizer))

Function that maps a canonical representive to some element.

Source

file-type.lisp.

Target Slot

create.

Generic Reader: create-fn (object)
Package

fresnel/lens.impl.

Methods
Reader Method: create-fn ((qlens qlens))

A function from A to C.

Need not be defined on every lens; if it is unbound, then the CREATE function simply throws an error.

Source

file-type.lisp.

Target Slot

create.

Generic Reader: get-fn (object)
Package

fresnel/lens.impl.

Methods
Reader Method: get-fn ((qlens qlens))

A function from C to A.

Source

file-type.lisp.

Target Slot

get.

Generic Reader: put-fn (object)
Package

fresnel/lens.impl.

Methods
Reader Method: put-fn ((qlens qlens))

A function from A × C to C.

Source

file-type.lisp.

Target Slot

put.


5.2.7 Conditions

Condition: lens-error
Package

fresnel/lens.impl.

Source

file-type.lisp.

Direct superclasses

simple-error.

Direct methods

lens-error-lens.

Direct slots
Slot: lens
Initargs

:lens

Readers

lens-error-lens.

Writers

This slot is read-only.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   W  
Index Entry  Section

A
acond: Public ordinary functions
after: Public ordinary functions
alist-lens: Public ordinary functions
alist-mapping: Public ordinary functions

B
backward: Public ordinary functions
before: Public ordinary functions
bij: Public ordinary functions
build-read-print-lens: Private ordinary functions

C
canonize: Public ordinary functions
canonize-after: Public ordinary functions
canonize-before: Public ordinary functions
canonize-fn: Private generic functions
canonize-fn: Private generic functions
canonizer: Public ordinary functions
car: Public ordinary functions
cdr: Public ordinary functions
check: Public ordinary functions
check-laws: Public ordinary functions
check-subtype: Public ordinary functions
check-type: Public ordinary functions
choose: Public ordinary functions
choose-fn: Private generic functions
choose-fn: Private generic functions
combine: Public ordinary functions
compose: Public ordinary functions
compose*: Public ordinary functions
cons: Public ordinary functions
constantly: Public ordinary functions
convert: Public standalone methods
convert: Public standalone methods
convert: Public standalone methods
create: Public ordinary functions
create-fn: Private generic functions
create-fn: Private generic functions

D
default: Public ordinary functions
discern: Public macros
discern-values: Public macros
discern-values*: Private ordinary functions

E
extract-defaults: Private ordinary functions

F
forward: Public ordinary functions
fset-mapping: Public ordinary functions
Function, acond: Public ordinary functions
Function, after: Public ordinary functions
Function, alist-lens: Public ordinary functions
Function, alist-mapping: Public ordinary functions
Function, backward: Public ordinary functions
Function, before: Public ordinary functions
Function, bij: Public ordinary functions
Function, build-read-print-lens: Private ordinary functions
Function, canonize: Public ordinary functions
Function, canonize-after: Public ordinary functions
Function, canonize-before: Public ordinary functions
Function, canonizer: Public ordinary functions
Function, car: Public ordinary functions
Function, cdr: Public ordinary functions
Function, check: Public ordinary functions
Function, check-laws: Public ordinary functions
Function, check-subtype: Public ordinary functions
Function, check-type: Public ordinary functions
Function, choose: Public ordinary functions
Function, combine: Public ordinary functions
Function, compose: Public ordinary functions
Function, compose*: Public ordinary functions
Function, cons: Public ordinary functions
Function, constantly: Public ordinary functions
Function, create: Public ordinary functions
Function, default: Public ordinary functions
Function, discern-values*: Private ordinary functions
Function, extract-defaults: Private ordinary functions
Function, forward: Public ordinary functions
Function, fset-mapping: Public ordinary functions
Function, gensym-lens: Public ordinary functions
Function, gensym?: Public ordinary functions
Function, get: Public ordinary functions
Function, guard: Public ordinary functions
Function, hash-table-alist: Public ordinary functions
Function, hash-table-mapping: Public ordinary functions
Function, identity: Public ordinary functions
Function, identity!: Public ordinary functions
Function, keyword-lens: Public ordinary functions
Function, lazy: Public ordinary functions
Function, lens: Public ordinary functions
Function, lensify: Private ordinary functions
Function, list: Public ordinary functions
Function, list*: Public ordinary functions
Function, lookup-default: Private ordinary functions
Function, lquot: Public ordinary functions
Function, lquot*: Public ordinary functions
Function, make-lens: Public ordinary functions
Function, mapcar: Public ordinary functions
Function, mapping: Public ordinary functions
Function, maybe-trace: Private ordinary functions
Function, morally-unbound?: Private ordinary functions
Function, nilable: Public ordinary functions
Function, of-type: Public ordinary functions
Function, opp: Public ordinary functions
Function, optional: Public ordinary functions
Function, or: Public ordinary functions
Function, or!: Public ordinary functions
Function, path: Public ordinary functions
Function, print-read-lens: Public ordinary functions
Function, put: Public ordinary functions
Function, qlens: Public ordinary functions
Function, rguard: Public ordinary functions
Function, rquot: Public ordinary functions
Function, rquot*: Public ordinary functions
Function, satisfies: Public ordinary functions
Function, some: Public ordinary functions
Function, split-bindings: Private ordinary functions
Function, trace: Public ordinary functions
Function, untrace: Public ordinary functions

G
Generic Function, canonize-fn: Private generic functions
Generic Function, choose-fn: Private generic functions
Generic Function, create-fn: Private generic functions
Generic Function, get-fn: Private generic functions
Generic Function, put-fn: Private generic functions
Generic Function, read-print-lens: Public generic functions
gensym-lens: Public ordinary functions
gensym?: Public ordinary functions
get: Public ordinary functions
get-fn: Private generic functions
get-fn: Private generic functions
guard: Public ordinary functions

H
hash-table-alist: Public ordinary functions
hash-table-mapping: Public ordinary functions

I
identity: Public ordinary functions
identity!: Public ordinary functions
initialize-instance: Public standalone methods

K
keyword-lens: Public ordinary functions

L
lazy: Public ordinary functions
lazy-list: Public macros
lazy-list*: Public macros
lens: Public ordinary functions
lens-error-lens: Public standalone methods
lensify: Private ordinary functions
list: Public ordinary functions
list*: Public ordinary functions
lookup-default: Private ordinary functions
lquot: Public ordinary functions
lquot*: Public ordinary functions

M
Macro, discern: Public macros
Macro, discern-values: Public macros
Macro, lazy-list: Public macros
Macro, lazy-list*: Public macros
Macro, map: Public macros
Macro, match: Public macros
Macro, match-constructors: Public macros
Macro, match-list: Public macros
Macro, match-list*: Public macros
Macro, match-two: Private macros
Macro, seq: Public macros
Macro, with-component-lenses: Public macros
Macro, with-create-lenses: Public macros
Macro, with-get-lenses: Public macros
Macro, with-morally-unbound-variables: Private macros
Macro, with-put-lenses: Public macros
make-lens: Public ordinary functions
map: Public macros
mapcar: Public ordinary functions
mapping: Public ordinary functions
match: Public macros
match-constructors: Public macros
match-list: Public macros
match-list*: Public macros
match-two: Private macros
maybe-trace: Private ordinary functions
Method, canonize-fn: Private generic functions
Method, choose-fn: Private generic functions
Method, convert: Public standalone methods
Method, convert: Public standalone methods
Method, convert: Public standalone methods
Method, create-fn: Private generic functions
Method, get-fn: Private generic functions
Method, initialize-instance: Public standalone methods
Method, lens-error-lens: Public standalone methods
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, put-fn: Private generic functions
Method, read-print-lens: Public generic functions
Method, read-print-lens: Public generic functions
Method, read-print-lens: Public generic functions
Method, read-print-lens: Public generic functions
Method, read-print-lens: Public generic functions
Method, read-print-lens: Public generic functions
morally-unbound?: Private ordinary functions

N
nilable: Public ordinary functions

O
of-type: Public ordinary functions
opp: Public ordinary functions
optional: Public ordinary functions
or: Public ordinary functions
or!: Public ordinary functions

P
path: Public ordinary functions
print-object: Public standalone methods
print-object: Public standalone methods
print-read-lens: Public ordinary functions
put: Public ordinary functions
put-fn: Private generic functions
put-fn: Private generic functions

Q
qlens: Public ordinary functions

R
read-print-lens: Public generic functions
read-print-lens: Public generic functions
read-print-lens: Public generic functions
read-print-lens: Public generic functions
read-print-lens: Public generic functions
read-print-lens: Public generic functions
read-print-lens: Public generic functions
rguard: Public ordinary functions
rquot: Public ordinary functions
rquot*: Public ordinary functions

S
satisfies: Public ordinary functions
seq: Public macros
some: Public ordinary functions
split-bindings: Private ordinary functions

T
trace: Public ordinary functions

U
untrace: Public ordinary functions

W
with-component-lenses: Public macros
with-create-lenses: Public macros
with-get-lenses: Public macros
with-morally-unbound-variables: Private macros
with-put-lenses: Public macros