The generalized-reference Reference Manual

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

The generalized-reference Reference Manual

This is the generalized-reference Reference Manual, version 1.0.3, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:52:52 2022 GMT+0.

Table of Contents


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, the ACCESS library, 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

Platform Support

This library has been built and tested successfully on macOS using the following Lisp implementations:

And does not build due to dependency failure on:

License

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

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


2 Systems

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


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

2.1 generalized-reference

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

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

Version

1.0.3

Dependencies
  • closer-mop (system).
  • alexandria (system).
  • serapeum (system).
  • split-sequence (system).
  • trivial-types (system).
  • series (system).
Source

generalized-reference.asd.

Child Component

generalized-reference.lisp (file).


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


3.1.1 generalized-reference/generalized-reference.asd

Source

generalized-reference.asd.

Parent Component

generalized-reference (system).

ASDF Systems

generalized-reference.

Packages

generalized-reference/asdf.


3.1.2 generalized-reference/generalized-reference.lisp

Source

generalized-reference.asd.

Parent Component

generalized-reference (system).

Packages

generalized-reference.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 generalized-reference

Source

generalized-reference.lisp.

Nicknames
  • gref
  • genref
  • gen-ref
Use List
  • closer-common-lisp.
  • series.
  • split-sequence.
Public Interface
Internals

4.2 generalized-reference/asdf

Source

generalized-reference.asd.

Use List
  • asdf/interface.
  • common-lisp.
  • uiop/driver.

5 Definitions

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


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

5.1 Public Interface


5.1.1 Macros

Macro: $ (&rest references)

Convenience macro for generalized reference.

Package

generalized-reference.

Source

generalized-reference.lisp.


5.1.2 Ordinary 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.

Function: series-p (obj)
Package

generalized-reference.

Source

generalized-reference.lisp.


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.

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))

5.2 Internals


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

5.2.1 Generic functions

Generic Reader: pseudosymbol-function (object)
Package

generalized-reference.

Methods
Reader Method: pseudosymbol-function ((pseudosymbol pseudosymbol))

automatically generated reader method

Source

generalized-reference.lisp.

Target Slot

function-slot.

Generic Writer: (setf pseudosymbol-function) (object)
Package

generalized-reference.

Methods
Writer Method: (setf pseudosymbol-function) ((pseudosymbol pseudosymbol))

automatically generated writer method

Source

generalized-reference.lisp.

Target Slot

function-slot.

Generic Reader: pseudosymbol-name (object)
Package

generalized-reference.

Methods
Reader Method: pseudosymbol-name ((pseudosymbol pseudosymbol))

automatically generated reader method

Source

generalized-reference.lisp.

Target Slot

name.

Generic Writer: (setf pseudosymbol-name) (object)
Package

generalized-reference.

Methods
Writer Method: (setf pseudosymbol-name) ((pseudosymbol pseudosymbol))

automatically generated writer method

Source

generalized-reference.lisp.

Target Slot

name.

Generic Reader: pseudosymbol-package-name (object)
Package

generalized-reference.

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

automatically generated reader method

Source

generalized-reference.lisp.

Target Slot

pkg-name.

Generic Writer: (setf pseudosymbol-package-name) (object)
Package

generalized-reference.

Methods
Writer Method: (setf pseudosymbol-package-name) ((pseudosymbol pseudosymbol))

automatically generated writer method

Source

generalized-reference.lisp.

Target Slot

pkg-name.

Generic Reader: pseudosymbol-plist (object)
Package

generalized-reference.

Methods
Reader Method: pseudosymbol-plist ((pseudosymbol pseudosymbol))

automatically generated reader method

Source

generalized-reference.lisp.

Target Slot

plist.

Generic Writer: (setf pseudosymbol-plist) (object)
Package

generalized-reference.

Methods
Writer Method: (setf pseudosymbol-plist) ((pseudosymbol pseudosymbol))

automatically generated writer method

Source

generalized-reference.lisp.

Target Slot

plist.

Generic Reader: pseudosymbol-value (object)
Package

generalized-reference.

Methods
Reader Method: pseudosymbol-value ((pseudosymbol pseudosymbol))

automatically generated reader method

Source

generalized-reference.lisp.

Target Slot

value-slot.

Generic Writer: (setf pseudosymbol-value) (object)
Package

generalized-reference.

Methods
Writer Method: (setf pseudosymbol-value) ((pseudosymbol pseudosymbol))

automatically generated writer method

Source

generalized-reference.lisp.

Target Slot

value-slot.


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

5.2.2 Classes

Class: pseudosymbol
Package

generalized-reference.

Source

generalized-reference.lisp.

Direct methods
Direct slots
Slot: name
Type

alexandria:string-designator

Initargs

:name

Readers

pseudosymbol-name.

Writers

(setf pseudosymbol-name).

Slot: pkg-name
Type

(or alexandria:string-designator nil)

Initargs

:package-name

Readers

pseudosymbol-package-name.

Writers

(setf pseudosymbol-package-name).

Slot: value-slot
Initargs

:value

Readers

pseudosymbol-value.

Writers

(setf pseudosymbol-value).

Slot: function-slot
Initargs

:function

Readers

pseudosymbol-function.

Writers

(setf pseudosymbol-function).

Slot: plist
Type

trivial-types:property-list

Initargs

:plist

Readers

pseudosymbol-plist.

Writers

(setf pseudosymbol-plist).


Appendix A Indexes


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

A.1 Concepts


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

A.2 Functions

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

$
$: Public macros

%
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions
%ref: Public generic functions

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

F
Function, ref: Public ordinary functions
Function, series-p: Public ordinary functions

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

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

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

R
ref: Public ordinary functions

S
series-p: Public ordinary functions

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