The darts.lib.tools Reference Manual

Table of Contents

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

The darts.lib.tools Reference Manual

This is the darts.lib.tools Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Dec 02 10:06:08 2019 GMT+0.


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

1 Introduction

Darts Tools

This is a small library of more or less useful stuff. Most things in here used to be carried over from project to project via copy+paste.

Generic Property List Support

Sometimes it is handy, if an application can store additional data in objects managed by other (say: library) code. One way to achieve that is to add support for "property lists" to objects.

This library provides a generic mechanism for that. The basis are the following generic functions, which form the "core" of the property support:

Given an object of a type, which supports these functions, the following accessors and modifiers work out-of-the-box.

The property-value function is setf-able, provided, that a suitable method on update-property-list exists for the argument object:

Besides using setf, an application can modify object property lists by various other functions provided here.

DEFSTRUCT and CLOS Support

This library provides a simple mixin class, which can be added to an application's class hierarchy in order to gain automatic support for property lists.

Example:

(defclass node (property-support) ())

(defclass parent-node (node)
  ((children :initform nil)))
  
(defclass child-node (node)
  ((parent :initform nil)))
  
(defclass inner-node (parent-node child-node) 
  ())
  
(defvar *node* (make-instance 'inner-node 'property-list (list 'id 16 'display-name "Folder")))

(property-value *node* 'id) ;; => 16
(property-value *node* 'display-name) ;; => "Folder"

To add property lists to an application defined structure type, you have to

Example:

(defstruct (handle (:copier nil) 
                   (:constructor make-handle (value &optional plist-init 
                                              &aux (plist (copy-list plist-init)))))
  (value 0 :type fixnum :read-only t)
  (plist nil :type list))
  
(define-structure-property-list handle handle-plist)

Atomic Updates

The implementation in this library updates the property lists atomically.

Missing Support for SYMBOL-PLIST

This module does not map PROPERTY-LIST to SYMBOL-PLIST for symbols, though doing so seems be trivial. However, the way atomic property updates work in some implementations is not easily adaptable to what needs to be stored in a symbol's plist slot. Since I rarely use property lists of symbols (somewhat funny, as I use them for other stuff all the time), I decided to not open that can of worms right now.

Iteration Macros

Event Notification

This library provides a simple facility for event notifications. The feature is split into low-level support code, and a ready to use high level mixin-class.

High-Level API

Low-Level API

An "observer chain" (or "chain" for brevity here) is a list of lists

(observers1 observers2 ...)

where the elements of each sublist observersk are the actual observer objects. There are two points to this

The second use case requires cooperation of your application. Consider the following example:

(defvar *global-chain* (list nil))

(defclass session ()
  ((local-chain :initarg :local-chain)))
  
(defclass transaction ()
  ((local-chain :initarg :local-chain)))
  
(defun start-session ()
  (make-instance 'session :local-chain (cons nil *global-chain*)))
  
(defun begin-transaction (session)
  (make-instance 'transaction 
                  :local-chain (cons nil (slot-value session 'local-chain))))
                  
(defun commit-transaction (transaction &rest keys)
  ;; Do whatever needs to be done...
  (notify-observers-in-chain (slot-value transaction 'local-chain)
                             transaction `(commit :status :success ,@keys)))

In this scenario, when a transaction is committed, the event notification is automatically propagated across the "scopes" of the hierarchy:

This ordering is guaranteed by the implementation, though the order of invocation within each of these scopes is undefined.

Copyright

This library is licensend under the terms of the MIT license:

Copyright (c) 2019 Dirk Esser

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


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 darts.lib.tools

Maintainer

Dirk Esser

Author

Dirk Esser

License

MIT

Description

More or less useful utilities

Long Description
Version

0.1

Dependency

atomics

Source

darts.lib.tools.asd (file)

Component

src (module)


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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 darts.lib.tools/src

Parent

darts.lib.tools (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 darts.lib.tools.asd

Location

darts.lib.tools.asd

Systems

darts.lib.tools (system)

Packages

darts.asdf


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

4.1.2 darts.lib.tools/src/packages.lisp

Parent

src (module)

Location

src/packages.lisp

Packages

darts.lib.tools


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

4.1.3 darts.lib.tools/src/properties.lisp

Dependency

packages.lisp (file)

Parent

src (module)

Location

src/properties.lisp

Exported Definitions
Internal Definitions

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

4.1.4 darts.lib.tools/src/iteration.lisp

Dependency

packages.lisp (file)

Parent

src (module)

Location

src/iteration.lisp

Exported Definitions

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

4.1.5 darts.lib.tools/src/observable.lisp

Dependency

packages.lisp (file)

Parent

src (module)

Location

src/observable.lisp

Exported Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 darts.asdf

Source

darts.lib.tools.asd

Use List

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

5.2 darts.lib.tools

Source

packages.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Macros

Macro: define-structure-property-list STRUCTURE-TYPE ACCESSOR
Package

darts.lib.tools

Source

properties.lisp (file)

Macro: do-observers-in-chain (OBSERVER-VAR &rest AUX-BINDINGS) CHAIN-FORM &body BODY
Package

darts.lib.tools

Source

observable.lisp (file)

Macro: do-properties (KEY VALUE) OBJECT-FORM &body BODY
Package

darts.lib.tools

Source

properties.lisp (file)

Macro: label NAME (&rest BINDINGS) &body BODY
Package

darts.lib.tools

Source

iteration.lisp (file)

Macro: named-loop LOOP-NAME (&rest BINDINGS) &body BODY
Package

darts.lib.tools

Source

iteration.lisp (file)


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

6.1.2 Functions

Function: add-observer-to-chain OBSERVER CHAIN &key TEST KEY IDENTITY
Package

darts.lib.tools

Source

observable.lisp (file)

Function: ensure-property OBJECT INDICATOR CONSTRUCTOR
Package

darts.lib.tools

Source

properties.lisp (file)

Function: map-over-properties FUNCTION OBJECT

Applies ‘function’ to each property of ‘object’. The function receives the property indicator as first, and the associated values as second argument. The return value of the function is ignored. This function always returns ‘object’.

Package

darts.lib.tools

Source

properties.lisp (file)

Function: notify-observers-in-chain CHAIN OBJECT EVENT
Package

darts.lib.tools

Source

observable.lisp (file)

Function: property-value OBJECT INDICATOR &optional DEFAULT

Answers the value of the property named by ‘indicator’ of the given ‘object’. If no matching property is found, answers ‘default’ instead. This function returns as secondary value a boolean flag, which indicates, whether the property was found or not.

Package

darts.lib.tools

Source

properties.lisp (file)

Writer

(setf property-value) (function)

Function: (setf property-value) VALUE OBJECT INDICATOR &optional DEFAULT

Sets the value of the property named by ‘indicator’ of the given ‘object’ to ‘value’. The optional ‘default’ is ignored and taken only for compatibility with ‘object-property’.

Package

darts.lib.tools

Source

properties.lisp (file)

Reader

property-value (function)

Function: remove-observer-from-chain OBSERVER CHAIN &key TEST KEY
Package

darts.lib.tools

Source

observable.lisp (file)

Function: remove-properties OBJECT &optional WHICH
Package

darts.lib.tools

Source

properties.lisp (file)

Function: remove-properties-if PREDICATE OBJECT
Package

darts.lib.tools

Source

properties.lisp (file)

Function: remove-properties-if-not PREDICATE OBJECT
Package

darts.lib.tools

Source

properties.lisp (file)

Function: remove-property OBJECT INDICATOR
Package

darts.lib.tools

Source

properties.lisp (file)


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

6.1.3 Generic functions

Generic Function: add-observer OBSERVER OBJECT &key TEST KEY IDENTITY

Adds the given ‘observer‘ to the set of registered
event observers of ‘object‘, unless it is already present.

Package

darts.lib.tools

Source

observable.lisp (file)

Methods
Method: add-observer OBSERVER (OBJECT observable) &key TEST KEY IDENTITY
Generic Function: notify-observers OBJECT EVENT

Notifies all registered event observers of ‘object‘ about the occurence of ‘event‘.

Package

darts.lib.tools

Source

observable.lisp (file)

Methods
Method: notify-observers (OBJECT observable) EVENT
Generic Function: observe-event OBSERVER OBJECT EVENT

Invoked in order to notify ‘observer‘, that the event described by ‘event‘ has happened with respect to ‘object‘.

Package

darts.lib.tools

Source

observable.lisp (file)

Generic Function: parent-observer-chain OBJECT
Package

darts.lib.tools

Source

observable.lisp (file)

Methods
Method: parent-observer-chain OBJECT
Generic Function: property-list OBJECT

Answers the property list of ‘object’. The
result is a property list of th form

(indicator1 value1 indicator2 value2 ...)

i.e., a list, whose elements are pairs of keys and their associated values. The keys are always compared using ‘eql’. The caller must never modify the return value of this function.

Package

darts.lib.tools

Source

properties.lisp (file)

Methods
Method: property-list (OBJECT property-support)
Generic Function: remove-observer OBSERVER OBJECT &key TEST KEY

Removes the given ‘observer‘ from the set of registered event observers of ‘object‘

Package

darts.lib.tools

Source

observable.lisp (file)

Methods
Method: remove-observer OBSERVER (OBJECT observable) &key TEST KEY
Generic Function: update-property-list OBJECT MODIFIER

Modifies the property list of ‘object’ by applying
the function ‘modifier’ to the current property list, and storing the result as the new property list. On implementations, which support it, this should be an atomic update.

The ‘modifier’ function is not allowed to modify the list destructively.

The modifier function returns two values: the new property list as first, and some other value as second one. This function returns the value returned by the modifier as second result.

Package

darts.lib.tools

Source

properties.lisp (file)

Methods
Method: update-property-list (OBJECT property-support) MODIFIER

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

6.1.4 Classes

Class: observable ()
Package

darts.lib.tools

Source

observable.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: observer-list-chain
Class: property-support ()

Minimal mix-in class, which supports the object
annotation protocol. By mixing this class into a class hierarchy, all instances gain support for function ‘property’ and
all related functions. The property list is (re-) initializable; note, however, that the initarg is named ‘property-list’
as exported from this package, *not* by a keyword symbol.
The property lists of instances of this class are upated atomically.

Package

darts.lib.tools

Source

properties.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: property-list
Type

darts.lib.tools::plist-cell


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

6.2 Internal definitions


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

6.2.1 Macros

Macro: make-plist-cell &optional INITS
Package

darts.lib.tools

Source

properties.lisp (file)

Macro: plist-cell-read CELL-FORM
Package

darts.lib.tools

Source

properties.lisp (file)

Macro: plist-cell-update CELL-FORM MODIFIER-FORM
Package

darts.lib.tools

Source

properties.lisp (file)


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

6.2.2 Functions

Function: copy-with-tail LIST LIMIT TAIL
Package

darts.lib.tools

Source

properties.lisp (file)


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

6.2.3 Types

Type: plist-cell ()
Package

darts.lib.tools

Source

properties.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   D   F   L   M  
Index Entry  Section

D
darts.lib.tools.asd: The darts․lib․tools․asd file
darts.lib.tools/src: The darts․lib․tools/src module
darts.lib.tools/src/iteration.lisp: The darts․lib․tools/src/iteration․lisp file
darts.lib.tools/src/observable.lisp: The darts․lib․tools/src/observable․lisp file
darts.lib.tools/src/packages.lisp: The darts․lib․tools/src/packages․lisp file
darts.lib.tools/src/properties.lisp: The darts․lib․tools/src/properties․lisp file

F
File, Lisp, darts.lib.tools.asd: The darts․lib․tools․asd file
File, Lisp, darts.lib.tools/src/iteration.lisp: The darts․lib․tools/src/iteration․lisp file
File, Lisp, darts.lib.tools/src/observable.lisp: The darts․lib․tools/src/observable․lisp file
File, Lisp, darts.lib.tools/src/packages.lisp: The darts․lib․tools/src/packages․lisp file
File, Lisp, darts.lib.tools/src/properties.lisp: The darts․lib․tools/src/properties․lisp file

L
Lisp File, darts.lib.tools.asd: The darts․lib․tools․asd file
Lisp File, darts.lib.tools/src/iteration.lisp: The darts․lib․tools/src/iteration․lisp file
Lisp File, darts.lib.tools/src/observable.lisp: The darts․lib․tools/src/observable․lisp file
Lisp File, darts.lib.tools/src/packages.lisp: The darts․lib․tools/src/packages․lisp file
Lisp File, darts.lib.tools/src/properties.lisp: The darts․lib․tools/src/properties․lisp file

M
Module, darts.lib.tools/src: The darts․lib․tools/src module

Jump to:   D   F   L   M  

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

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   L   M   N   O   P   R   U  
Index Entry  Section

(
(setf property-value): Exported functions

A
add-observer: Exported generic functions
add-observer: Exported generic functions
add-observer-to-chain: Exported functions

C
copy-with-tail: Internal functions

D
define-structure-property-list: Exported macros
do-observers-in-chain: Exported macros
do-properties: Exported macros

E
ensure-property: Exported functions

F
Function, (setf property-value): Exported functions
Function, add-observer-to-chain: Exported functions
Function, copy-with-tail: Internal functions
Function, ensure-property: Exported functions
Function, map-over-properties: Exported functions
Function, notify-observers-in-chain: Exported functions
Function, property-value: Exported functions
Function, remove-observer-from-chain: Exported functions
Function, remove-properties: Exported functions
Function, remove-properties-if: Exported functions
Function, remove-properties-if-not: Exported functions
Function, remove-property: Exported functions

G
Generic Function, add-observer: Exported generic functions
Generic Function, notify-observers: Exported generic functions
Generic Function, observe-event: Exported generic functions
Generic Function, parent-observer-chain: Exported generic functions
Generic Function, property-list: Exported generic functions
Generic Function, remove-observer: Exported generic functions
Generic Function, update-property-list: Exported generic functions

L
label: Exported macros

M
Macro, define-structure-property-list: Exported macros
Macro, do-observers-in-chain: Exported macros
Macro, do-properties: Exported macros
Macro, label: Exported macros
Macro, make-plist-cell: Internal macros
Macro, named-loop: Exported macros
Macro, plist-cell-read: Internal macros
Macro, plist-cell-update: Internal macros
make-plist-cell: Internal macros
map-over-properties: Exported functions
Method, add-observer: Exported generic functions
Method, notify-observers: Exported generic functions
Method, parent-observer-chain: Exported generic functions
Method, property-list: Exported generic functions
Method, remove-observer: Exported generic functions
Method, update-property-list: Exported generic functions

N
named-loop: Exported macros
notify-observers: Exported generic functions
notify-observers: Exported generic functions
notify-observers-in-chain: Exported functions

O
observe-event: Exported generic functions

P
parent-observer-chain: Exported generic functions
parent-observer-chain: Exported generic functions
plist-cell-read: Internal macros
plist-cell-update: Internal macros
property-list: Exported generic functions
property-list: Exported generic functions
property-value: Exported functions

R
remove-observer: Exported generic functions
remove-observer: Exported generic functions
remove-observer-from-chain: Exported functions
remove-properties: Exported functions
remove-properties-if: Exported functions
remove-properties-if-not: Exported functions
remove-property: Exported functions

U
update-property-list: Exported generic functions
update-property-list: Exported generic functions

Jump to:   (  
A   C   D   E   F   G   L   M   N   O   P   R   U  

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

A.3 Variables

Jump to:   O   P   S  
Index Entry  Section

O
observer-list-chain: Exported classes

P
property-list: Exported classes

S
Slot, observer-list-chain: Exported classes
Slot, property-list: Exported classes

Jump to:   O   P   S  

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

A.4 Data types

Jump to:   C   D   O   P   S   T  
Index Entry  Section

C
Class, observable: Exported classes
Class, property-support: Exported classes

D
darts.asdf: The darts․asdf package
darts.lib.tools: The darts․lib․tools system
darts.lib.tools: The darts․lib․tools package

O
observable: Exported classes

P
Package, darts.asdf: The darts․asdf package
Package, darts.lib.tools: The darts․lib․tools package
plist-cell: Internal types
property-support: Exported classes

S
System, darts.lib.tools: The darts․lib․tools system

T
Type, plist-cell: Internal types

Jump to:   C   D   O   P   S   T