The generalized-reference Reference Manual

Table of Contents

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

The generalized-reference Reference Manual

This is the generalized-reference Reference Manual, version 1.0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 04:51:16 2022 GMT+0.


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

1 Introduction

GENERALIZED-REFERENCE

Quicklisp MIT License

Generalized reference over structured data by pairwise reduction of arbitrary place identifiers for Common Lisp.

About

The interface is simple and minimalist by design, primarily intended for streamlined work with hierarchical data, such as that imported automatically from another language or format that may not follow Lisp style conventions and best-practices. Support is also included for the SERIES library because I happen to use it a lot.

Inspired by, and an alternative to, ACCESS and SERAPEUM's vref and href forms.

Usage

Reference a place by the sequence of place identifiers in desending order, using the ref function or the $ convenience macro. Referenced places are typically SETF-able where it makes sense for them to be so.

Support is included for the following types:

To extend for your custom data types, specialize the generic function %ref.

Examples

Download the software to a place ASDF can find it, such as #P"~/common-lisp".

Then in your favourite REPL:

(ql:quickload :generalized-reference)

(use-package :generalized-reference)

Association Lists

Association Lists allow lookups by quoted-symbol or name-string. Note that the name-string is case-sensitive.

Keyword-symbol lookup for Association Lists is not presently supported, but may be in a future update.

(defparameter *alist* '((a . 1) (b . 2) (c . 3)))

($ *alist* 'a)
=> 1

($ *alist* "A")
=> 1

($ *alist* :a)
=> NIL

($ *alist* "a")
=> NIL

Property Lists

Property Lists allow lookups by keyword-symbol, quoted-symbol, or name-string. Note that the name-string is case-sensitive.

(defparameter *plist* '(:a 1 :b 2 :c 3))

($ *plist* :a)
=> 1

($ *plist* 'a)
=> 1

($ *plist* "A")
=> 1

($ *plist* "a")
=> NIL

Hash Tables

Hash Tables currently support lookup by their internal hash-key. To allow lookup for string-based hash-keys, remember to set the equality test to equal when defining the hash table.

When a hash-key isn't found in a hash table, ref returns the keyword symbol :NOT-FOUND, while returning NIL means the hash-key is present in the table but has its value set to NIL.

Note: For this example we're also going to use the DICT constructor function from the Serapeum library, a dependency of generalized-reference already available in your Lisp Image. By default it uses equal comparison for hash-key lookups, which is exactly what we need.

(use-package :serapeum)

(defparameter *hash* (dict :a 1 :b 2 :c 3 "D" 4))

($ *hash* :a)
=> 1

($ *hash* "D")
=> 4

($ *hash* :d)
=> :NOT-FOUND

Vectors

Vectors allow lookup by index.

(defparameter *vector* (vector 1 2 3 4))

($ *vector* 0)
=> 1

Arrays

Arrays allow lookup by a list of indices.

(defparameter *array* (make-array '(2 2) :initial-contents '((1 2) (3 4))))

($ *array* '(0 0))
=> 1

($ *array* '(1 1))
=> 4

License

Copyright © 2022, "the Phoeron" Colin J.E. Lupton

Released under the MIT License. See generalized-reference/LICENSE.md for more information.


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 generalized-reference

Author

"the Phoeron" Colin J.E. Lupton

Contact

thephoeron@protonmail.com

Source Control

https://github.com/thephoeron/generalized-reference/

Bug Tracker

https://github.com/thephoeron/generalized-reference/issues/

License

MIT

Description

Generalized reference over structured data by pairwise reduction of arbitrary place identifiers for Common Lisp.

Version

1.0.2

Dependencies
Source

generalized-reference.asd (file)

Component

generalized-reference.lisp (file)


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 generalized-reference.asd

Location

generalized-reference.asd

Systems

generalized-reference (system)

Packages

generalized-reference/asdf


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

3.1.2 generalized-reference/generalized-reference.lisp

Parent

generalized-reference (system)

Location

generalized-reference.lisp

Packages

generalized-reference

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 generalized-reference/asdf

Source

generalized-reference.asd

Use List

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

4.2 generalized-reference

Source

generalized-reference.lisp (file)

Nicknames
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: $ &rest REFERENCES

Convenience macro for generalized reference.

Package

generalized-reference

Source

generalized-reference.lisp (file)


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

5.1.2 Functions

Function: ref &rest REFERENCES

The main interface for generalized reference by pairwise reduction over a parameter list of place identifiers.

Package

generalized-reference

Source

generalized-reference.lisp (file)

Function: series-p OBJ
Package

generalized-reference

Source

generalized-reference.lisp (file)


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

5.1.3 Generic functions

Generic Function: %ref ALICE RABBIT-HOLE

The generic function for reducing pairwise over arbitrary structures of data by place identifier.

Package

generalized-reference

Source

generalized-reference.lisp (file)

Methods
Method: %ref (STORE structure-object) (KEY function)
Method: %ref (STORE structure-object) (INDICES sequence)
Method: %ref (STORE structure-object) (INDEX integer)
Method: %ref (STORE structure-object) (SELECTION structure-object)
Method: %ref (STORE symbol) (PROP symbol)
Method: %ref (STORE array) (INDICES sequence)
Method: %ref (STORE vector) (INDEX integer)
Method: %ref (STORE list) (KEY string)
Method: %ref (STORE list) (KEY symbol)
Method: %ref (STORE hash-table) HASH-KEY
Method: %ref (STORE standard-object) (SLOT-NAME string)
Method: %ref (STORE standard-object) (SLOT-NAME symbol)
Method: %ref (PSYM pseudosymbol) (SYM-NAME string)
Method: %ref (PSYM pseudosymbol) (SYM symbol)
Method: %ref (PKG package) (SYM symbol)

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

5.2 Internal definitions


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

5.2.1 Generic functions

Generic Function: pseudosymbol-function OBJECT
Generic Function: (setf pseudosymbol-function) NEW-VALUE OBJECT
Package

generalized-reference

Methods
Method: pseudosymbol-function (PSEUDOSYMBOL pseudosymbol)

automatically generated reader method

Source

generalized-reference.lisp (file)

Method: (setf pseudosymbol-function) NEW-VALUE (PSEUDOSYMBOL pseudosymbol)

automatically generated writer method

Source

generalized-reference.lisp (file)

Generic Function: pseudosymbol-name OBJECT
Generic Function: (setf pseudosymbol-name) NEW-VALUE OBJECT
Package

generalized-reference

Methods
Method: pseudosymbol-name (PSEUDOSYMBOL pseudosymbol)

automatically generated reader method

Source

generalized-reference.lisp (file)

Method: (setf pseudosymbol-name) NEW-VALUE (PSEUDOSYMBOL pseudosymbol)

automatically generated writer method

Source

generalized-reference.lisp (file)

Generic Function: pseudosymbol-package-name OBJECT
Generic Function: (setf pseudosymbol-package-name) NEW-VALUE OBJECT
Package

generalized-reference

Methods
Method: pseudosymbol-package-name (PSEUDOSYMBOL pseudosymbol)

automatically generated reader method

Source

generalized-reference.lisp (file)

Method: (setf pseudosymbol-package-name) NEW-VALUE (PSEUDOSYMBOL pseudosymbol)

automatically generated writer method

Source

generalized-reference.lisp (file)

Generic Function: pseudosymbol-plist OBJECT
Generic Function: (setf pseudosymbol-plist) NEW-VALUE OBJECT
Package

generalized-reference

Methods
Method: pseudosymbol-plist (PSEUDOSYMBOL pseudosymbol)

automatically generated reader method

Source

generalized-reference.lisp (file)

Method: (setf pseudosymbol-plist) NEW-VALUE (PSEUDOSYMBOL pseudosymbol)

automatically generated writer method

Source

generalized-reference.lisp (file)

Generic Function: pseudosymbol-value OBJECT
Generic Function: (setf pseudosymbol-value) NEW-VALUE OBJECT
Package

generalized-reference

Methods
Method: pseudosymbol-value (PSEUDOSYMBOL pseudosymbol)

automatically generated reader method

Source

generalized-reference.lisp (file)

Method: (setf pseudosymbol-value) NEW-VALUE (PSEUDOSYMBOL pseudosymbol)

automatically generated writer method

Source

generalized-reference.lisp (file)


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

5.2.2 Classes

Class: pseudosymbol ()
Package

generalized-reference

Source

generalized-reference.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: name
Type

alexandria:string-designator

Initargs

:name

Readers

pseudosymbol-name (generic function)

Writers

(setf pseudosymbol-name) (generic function)

Slot: pkg-name
Type

(or alexandria:string-designator nil)

Initargs

:package-name

Readers

pseudosymbol-package-name (generic function)

Writers

(setf pseudosymbol-package-name) (generic function)

Slot: value-slot
Initargs

:value

Readers

pseudosymbol-value (generic function)

Writers

(setf pseudosymbol-value) (generic function)

Slot: function-slot
Initargs

:function

Readers

pseudosymbol-function (generic function)

Writers

(setf pseudosymbol-function) (generic function)

Slot: plist
Type

trivial-types:property-list

Initargs

:plist

Readers

pseudosymbol-plist (generic function)

Writers

(setf pseudosymbol-plist) (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   G   L  
Index Entry  Section

F
File, Lisp, generalized-reference.asd: The generalized-reference․asd file
File, Lisp, generalized-reference/generalized-reference.lisp: The generalized-reference/generalized-reference․lisp file

G
generalized-reference.asd: The generalized-reference․asd file
generalized-reference/generalized-reference.lisp: The generalized-reference/generalized-reference․lisp file

L
Lisp File, generalized-reference.asd: The generalized-reference․asd file
Lisp File, generalized-reference/generalized-reference.lisp: The generalized-reference/generalized-reference․lisp file

Jump to:   F   G   L  

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

A.2 Functions

Jump to:   $   %   (  
F   G   M   P   R   S  
Index Entry  Section

$
$: Exported macros

%
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions
%ref: Exported generic functions

(
(setf pseudosymbol-function): Internal generic functions
(setf pseudosymbol-function): Internal generic functions
(setf pseudosymbol-name): Internal generic functions
(setf pseudosymbol-name): Internal generic functions
(setf pseudosymbol-package-name): Internal generic functions
(setf pseudosymbol-package-name): Internal generic functions
(setf pseudosymbol-plist): Internal generic functions
(setf pseudosymbol-plist): Internal generic functions
(setf pseudosymbol-value): Internal generic functions
(setf pseudosymbol-value): Internal generic functions

F
Function, ref: Exported functions
Function, series-p: Exported functions

G
Generic Function, %ref: Exported generic functions
Generic Function, (setf pseudosymbol-function): Internal generic functions
Generic Function, (setf pseudosymbol-name): Internal generic functions
Generic Function, (setf pseudosymbol-package-name): Internal generic functions
Generic Function, (setf pseudosymbol-plist): Internal generic functions
Generic Function, (setf pseudosymbol-value): Internal generic functions
Generic Function, pseudosymbol-function: Internal generic functions
Generic Function, pseudosymbol-name: Internal generic functions
Generic Function, pseudosymbol-package-name: Internal generic functions
Generic Function, pseudosymbol-plist: Internal generic functions
Generic Function, pseudosymbol-value: Internal generic functions

M
Macro, $: Exported macros
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, %ref: Exported generic functions
Method, (setf pseudosymbol-function): Internal generic functions
Method, (setf pseudosymbol-name): Internal generic functions
Method, (setf pseudosymbol-package-name): Internal generic functions
Method, (setf pseudosymbol-plist): Internal generic functions
Method, (setf pseudosymbol-value): Internal generic functions
Method, pseudosymbol-function: Internal generic functions
Method, pseudosymbol-name: Internal generic functions
Method, pseudosymbol-package-name: Internal generic functions
Method, pseudosymbol-plist: Internal generic functions
Method, pseudosymbol-value: Internal generic functions

P
pseudosymbol-function: Internal generic functions
pseudosymbol-function: Internal generic functions
pseudosymbol-name: Internal generic functions
pseudosymbol-name: Internal generic functions
pseudosymbol-package-name: Internal generic functions
pseudosymbol-package-name: Internal generic functions
pseudosymbol-plist: Internal generic functions
pseudosymbol-plist: Internal generic functions
pseudosymbol-value: Internal generic functions
pseudosymbol-value: Internal generic functions

R
ref: Exported functions

S
series-p: Exported functions

Jump to:   $   %   (  
F   G   M   P   R   S  

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

A.3 Variables

Jump to:   F   N   P   S   V  
Index Entry  Section

F
function-slot: Internal classes

N
name: Internal classes

P
pkg-name: Internal classes
plist: Internal classes

S
Slot, function-slot: Internal classes
Slot, name: Internal classes
Slot, pkg-name: Internal classes
Slot, plist: Internal classes
Slot, value-slot: Internal classes

V
value-slot: Internal classes

Jump to:   F   N   P   S   V  

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

A.4 Data types

Jump to:   C   G   P   S  
Index Entry  Section

C
Class, pseudosymbol: Internal classes

G
generalized-reference: The generalized-reference system
generalized-reference: The generalized-reference package
generalized-reference/asdf: The generalized-reference/asdf package

P
Package, generalized-reference: The generalized-reference package
Package, generalized-reference/asdf: The generalized-reference/asdf package
pseudosymbol: Internal classes

S
System, generalized-reference: The generalized-reference system

Jump to:   C   G   P   S