The clobber Reference Manual

Table of Contents

The clobber Reference Manual

This is the clobber Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:27:22 2021 GMT+0.

1 Introduction

Clobber is an alternative to so called "object prevalence", and in
particular to cl-prevalence.

Clobber is both simpler, more flexible, and more robust than systems
based on object prevalence.  

It is simpler because we do not take any snapshots at all.  Other
systems typically use a combination of transaction logs and snapshots.
Clobber uses only a transaction log which is always read into an empty
system.

It is more flexible because the system itself does not define the
format of a transaction.  Client code can save transactions as Lisp
lists, as instances of standard-object, or anything else that can be
serialized.  It is also more flexible because transactions can contain
any object that can be serialized, including model objects.  With this
method, client code does not need to manipulate "manually created
pointers" such as social security numbers, account numbers, membership
numbers, etc. whenever it needs to execute a transaction.  Instead it
can use the model objects themselves such as people, accounts,
automobiles and whatnot.

It is more robust because serialization of instances of (subclasses
of) standard-object is not accomplished based on slots.  Slots are
considered implementation details.  In traditional systems, whenever
the model evolves, the serialization might no longer be valid.  In
contrast, Clobber serializes instances of standard-object as a list of
pairs, each one consisting of an initarg and a value.  These pairs can
be handled by client code in any way it sees fit.  They can be handled
by an :initarg, by initialize-instance, or they can be ignored.  The
downside of the Clobber method is that client code must specify these
pairs in the form of an initarg and the name of an accessor function
to be called to obtain the value used for the initarg.  This
inconvenience is however relatively minor, especially considering the
additional robustness it buys in terms of less sensitivity to changes
in the model classes. 

At the heart of Clobber is a mechanism for serializing objects that
preserves object identity, much like the reader macros #= and ##,
except that clobber detects sharing within the entire transaction log,
not only within a single transaction.  This mechanism is what makes it
possible for client code to put any old object in a transaction, while
making sure that sharing is preserved.

Clobber is in the public domain in countries where it is possible to
place works in the public domain explicitly.  In other countries, we
will distribute Clobber according to a license that lets the user do
whatever he or she pleases with the code. 

Send comments to robert.strandh@gmail.com

A manual might be written one day. 

2 Systems

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

2.1 clobber

Author

Robert Strandh <robert.strandh@gmail.com>

License

FreeBSD, see file LICENSE.text

Description

Library for transaction-oriented data bases.

Source

clobber.asd (file)

Components

• packages.lisp (file)
• clobber.lisp (file)
• demo.lisp (file)
• demo2.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 clobber.asd

Location

clobber.asd

Systems

clobber (system)

3.1.2 clobber/packages.lisp

Parent

clobber (system)

Location

packages.lisp

Packages

clobber

3.1.3 clobber/clobber.lisp

Dependency

packages.lisp (file)

Parent

clobber (system)

Location

clobber.lisp

Exported Definitions

• close-transaction-log (function)
• define-save-info (macro)
• log-transaction (function)
• open-transaction-log (function)

Internal Definitions

• %set-syntax-hash-bang (function)
• %set-syntax-hash-caret (function)
• %set-syntax-left-bracket (function)
• %set-syntax-right-bracket (function)
• load-transaction-log (function)
• log-stream (method)
• make-object-id-table (function)
• make-transaction-log (function)
• next-object-id (method)
• (setf next-object-id) (method)
• object-id-table (method)
• save-info (generic function)
• save-info (method)
• serialize (generic function)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• set-syntax (function)
• transaction-log (class)

3.1.4 clobber/demo.lisp

Dependency

clobber.lisp (file)

Parent

clobber (system)

Location

demo.lisp

Packages

clobber-demo

Internal Definitions

• *banks* (special variable)
• *transaction-log* (special variable)
• account (class)
• accounts (method)
• (setf accounts) (method)
• add-account (function)
• add-customer (function)
• balance (method)
• (setf balance) (method)
• bank (method)
• (setf bank) (method)
• bank (class)
• customers (method)
• (setf customers) (method)
• delete-bank (function)
• deposit (function)
• do-things-1 (function)
• execute (function)
• holder (method)
• name (method)
• new-bank (function)
• person (class)
• save-info (method)
• save-info (method)
• start (function)
• stop (function)
• transfer (function)
• withdraw (function)

3.1.5 clobber/demo2.lisp

Dependency

demo.lisp (file)

Parent

clobber (system)

Location

demo2.lisp

Packages

clobber-demo2

Internal Definitions

• *banks* (special variable)
• *comment* (special variable)
• *operator* (special variable)
• *transaction-log* (special variable)
• *transactions* (special variable)
• account (class)
• accounts (method)
• (setf accounts) (method)
• add-account (function)
• add-customer (function)
• arguments (method)
• balance (method)
• (setf balance) (method)
• bank (method)
• (setf bank) (method)
• bank (class)
• comment (method)
• creation-date (method)
• creator (method)
• customers (method)
• (setf customers) (method)
• delete-bank (function)
• deposit (function)
• do-things-1 (function)
• execute (function)
• function-name (method)
• holder (method)
• name (method)
• new-bank (function)
• person (class)
• save-info (method)
• save-info (method)
• save-info (method)
• start (function)
• stop (function)
• transaction (class)
• transfer (function)
• with-comment (macro)
• withdraw (function)

4 Packages

Packages are listed by definition order.

4.1 clobber

Source

packages.lisp (file)

Use List

common-lisp

Exported Definitions

• close-transaction-log (function)
• define-save-info (macro)
• log-transaction (function)
• open-transaction-log (function)

Internal Definitions

• %set-syntax-hash-bang (function)
• %set-syntax-hash-caret (function)
• %set-syntax-left-bracket (function)
• %set-syntax-right-bracket (function)
• load-transaction-log (function)
• log-stream (generic function)
• log-stream (method)
• make-object-id-table (function)
• make-transaction-log (function)
• next-object-id (generic function)
• next-object-id (method)
• (setf next-object-id) (method)
• (setf next-object-id) (generic function)
• object-id-table (generic function)
• object-id-table (method)
• save-info (generic function)
• save-info (method)
• save-info (method)
• save-info (method)
• save-info (method)
• save-info (method)
• save-info (method)
• serialize (generic function)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• set-syntax (function)
• transaction-log (class)

4.2 clobber-demo

Source

demo.lisp (file)

Use List

common-lisp

Internal Definitions

• *banks* (special variable)
• *transaction-log* (special variable)
• account (class)
• accounts (generic function)
• accounts (method)
• (setf accounts) (method)
• (setf accounts) (generic function)
• add-account (function)
• add-customer (function)
• balance (generic function)
• balance (method)
• (setf balance) (method)
• (setf balance) (generic function)
• bank (generic function)
• bank (method)
• (setf bank) (method)
• (setf bank) (generic function)
• bank (class)
• customers (generic function)
• customers (method)
• (setf customers) (method)
• (setf customers) (generic function)
• delete-bank (function)
• deposit (function)
• do-things-1 (function)
• execute (function)
• holder (generic function)
• holder (method)
• name (generic function)
• name (method)
• new-bank (function)
• person (class)
• start (function)
• stop (function)
• transfer (function)
• withdraw (function)

4.3 clobber-demo2

Source

demo2.lisp (file)

Use List

common-lisp

Internal Definitions

• *banks* (special variable)
• *comment* (special variable)
• *operator* (special variable)
• *transaction-log* (special variable)
• *transactions* (special variable)
• account (class)
• accounts (generic function)
• accounts (method)
• (setf accounts) (method)
• (setf accounts) (generic function)
• add-account (function)
• add-customer (function)
• arguments (generic function)
• arguments (method)
• balance (generic function)
• balance (method)
• (setf balance) (method)
• (setf balance) (generic function)
• bank (generic function)
• bank (method)
• (setf bank) (method)
• (setf bank) (generic function)
• bank (class)
• comment (generic function)
• comment (method)
• creation-date (generic function)
• creation-date (method)
• creator (generic function)
• creator (method)
• customers (generic function)
• customers (method)
• (setf customers) (method)
• (setf customers) (generic function)
• delete-bank (function)
• deposit (function)
• do-things-1 (function)
• execute (function)
• function-name (generic function)
• function-name (method)
• holder (generic function)
• holder (method)
• name (generic function)
• name (method)
• new-bank (function)
• person (class)
• start (function)
• stop (function)
• transaction (class)
• transfer (function)
• with-comment (macro)
• withdraw (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: define-save-info TYPE &body SAVE-INFO

Package

clobber

Source

clobber.lisp (file)

5.1.2 Functions

Function: close-transaction-log TRANSACTION-LOG

Package

clobber

Source

clobber.lisp (file)

Function: log-transaction TRANSACTION TRANSACTION-LOG

Package

clobber

Source

clobber.lisp (file)

Function: open-transaction-log FILENAME FUNCTION

Package

clobber

Source

clobber.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *banks*

Package

clobber-demo

Source

demo.lisp (file)

Special Variable: *banks*

Package

clobber-demo2

Source

demo2.lisp (file)

Special Variable: *comment*

Package

clobber-demo2

Source

demo2.lisp (file)

Special Variable: *operator*

Package

clobber-demo2

Source

demo2.lisp (file)

Special Variable: *transaction-log*

Package

clobber-demo

Source

demo.lisp (file)

Special Variable: *transaction-log*

Package

clobber-demo2

Source

demo2.lisp (file)

Special Variable: *transactions*

Package

clobber-demo2

Source

demo2.lisp (file)

5.2.2 Macros

Macro: with-comment COMMENT &body BODY

Package

clobber-demo2

Source

demo2.lisp (file)

5.2.3 Functions

Function: %set-syntax-hash-bang OBJECT-TABLE

Package

clobber

Source

clobber.lisp (file)

Function: %set-syntax-hash-caret OBJECT-TABLE

Package

clobber

Source

clobber.lisp (file)

Function: %set-syntax-left-bracket ()

Package

clobber

Source

clobber.lisp (file)

Function: %set-syntax-right-bracket ()

Package

clobber

Source

clobber.lisp (file)

Function: add-account ACCOUNT BANK

Package

clobber-demo

Source

demo.lisp (file)

Function: add-account ACCOUNT BANK

Package

clobber-demo2

Source

demo2.lisp (file)

Function: add-customer PERSON BANK

Package

clobber-demo

Source

demo.lisp (file)

Function: add-customer PERSON BANK

Package

clobber-demo2

Source

demo2.lisp (file)

Function: delete-bank BANK

Package

clobber-demo

Source

demo.lisp (file)

Function: delete-bank BANK

Package

clobber-demo2

Source

demo2.lisp (file)

Function: deposit AMOUNT ACCOUNT

Package

clobber-demo

Source

demo.lisp (file)

Function: deposit AMOUNT ACCOUNT

Package

clobber-demo2

Source

demo2.lisp (file)

Function: do-things-1 ()

Package

clobber-demo

Source

demo.lisp (file)

Function: do-things-1 ()

Package

clobber-demo2

Source

demo2.lisp (file)

Function: execute TRANSACTION-FUNCTION &rest ARGUMENTS

Package

clobber-demo

Source

demo.lisp (file)

Function: execute TRANSACTION-FUNCTION &rest ARGUMENTS

Package

clobber-demo2

Source

demo2.lisp (file)

Function: load-transaction-log FILENAME FUNCTION OBJECT-TABLE

Package

clobber

Source

clobber.lisp (file)

Function: make-object-id-table OBJECT-TABLE

Package

clobber

Source

clobber.lisp (file)

Function: make-transaction-log FILENAME OBJECT-TABLE

Package

clobber

Source

clobber.lisp (file)

Function: new-bank BANK

Package

clobber-demo

Source

demo.lisp (file)

Function: new-bank BANK

Package

clobber-demo2

Source

demo2.lisp (file)

Function: set-syntax READTABLE OBJECT-TABLE

Package

clobber

Source

clobber.lisp (file)

Function: start FILENAME

Package

clobber-demo

Source

demo.lisp (file)

Function: start FILENAME

Package

clobber-demo2

Source

demo2.lisp (file)

Function: stop ()

Package

clobber-demo

Source

demo.lisp (file)

Function: stop ()

Package

clobber-demo2

Source

demo2.lisp (file)

Function: transfer AMOUNT FROM-ACCOUNT TO-ACCOUNT

Package

clobber-demo

Source

demo.lisp (file)

Function: transfer AMOUNT FROM-ACCOUNT TO-ACCOUNT

Package

clobber-demo2

Source

demo2.lisp (file)

Function: withdraw AMOUNT ACCOUNT

Package

clobber-demo

Source

demo.lisp (file)

Function: withdraw AMOUNT ACCOUNT

Package

clobber-demo2

Source

demo2.lisp (file)

5.2.4 Generic functions

Generic Function: accounts OBJECT

Generic Function: (setf accounts) NEW-VALUE OBJECT

Package

clobber-demo

Methods

Method: accounts (BANK bank)

automatically generated reader method

Source

demo.lisp (file)

Method: (setf accounts) NEW-VALUE (BANK bank)

automatically generated writer method

Source

demo.lisp (file)

Generic Function: accounts OBJECT

Generic Function: (setf accounts) NEW-VALUE OBJECT

Package

clobber-demo2

Methods

Method: accounts (BANK bank)

automatically generated reader method

Source

demo2.lisp (file)

Method: (setf accounts) NEW-VALUE (BANK bank)

automatically generated writer method

Source

demo2.lisp (file)

Generic Function: arguments OBJECT

Package

clobber-demo2

Methods

Method: arguments (TRANSACTION transaction)

automatically generated reader method

Source

demo2.lisp (file)

Generic Function: balance OBJECT

Generic Function: (setf balance) NEW-VALUE OBJECT

Package

clobber-demo

Methods

Method: balance (ACCOUNT account)

automatically generated reader method

Source

demo.lisp (file)

Method: (setf balance) NEW-VALUE (ACCOUNT account)

automatically generated writer method

Source

demo.lisp (file)

Generic Function: balance OBJECT

Generic Function: (setf balance) NEW-VALUE OBJECT

Package

clobber-demo2

Methods

Method: balance (ACCOUNT account)

automatically generated reader method

Source

demo2.lisp (file)

Method: (setf balance) NEW-VALUE (ACCOUNT account)

automatically generated writer method

Source

demo2.lisp (file)

Generic Function: bank OBJECT

Generic Function: (setf bank) NEW-VALUE OBJECT

Package

clobber-demo

Methods

Method: bank (ACCOUNT account)

automatically generated reader method

Source

demo.lisp (file)

Method: (setf bank) NEW-VALUE (ACCOUNT account)

automatically generated writer method

Source

demo.lisp (file)

Generic Function: bank OBJECT

Generic Function: (setf bank) NEW-VALUE OBJECT

Package

clobber-demo2

Methods

Method: bank (ACCOUNT account)

automatically generated reader method

Source

demo2.lisp (file)

Method: (setf bank) NEW-VALUE (ACCOUNT account)

automatically generated writer method

Source

demo2.lisp (file)

Generic Function: comment OBJECT

Package

clobber-demo2

Methods

Method: comment (TRANSACTION transaction)

automatically generated reader method

Source

demo2.lisp (file)

Generic Function: creation-date OBJECT

Package

clobber-demo2

Methods

Method: creation-date (TRANSACTION transaction)

automatically generated reader method

Source

demo2.lisp (file)

Generic Function: creator OBJECT

Package

clobber-demo2

Methods

Method: creator (TRANSACTION transaction)

automatically generated reader method

Source

demo2.lisp (file)

Generic Function: customers OBJECT

Generic Function: (setf customers) NEW-VALUE OBJECT

Package

clobber-demo

Methods

Method: customers (BANK bank)

automatically generated reader method

Source

demo.lisp (file)

Method: (setf customers) NEW-VALUE (BANK bank)

automatically generated writer method

Source

demo.lisp (file)

Generic Function: customers OBJECT

Generic Function: (setf customers) NEW-VALUE OBJECT

Package

clobber-demo2

Methods

Method: customers (BANK bank)

automatically generated reader method

Source

demo2.lisp (file)

Method: (setf customers) NEW-VALUE (BANK bank)

automatically generated writer method

Source

demo2.lisp (file)

Generic Function: function-name OBJECT

Package

clobber-demo2

Methods

Method: function-name (TRANSACTION transaction)

automatically generated reader method

Source

demo2.lisp (file)

Generic Function: holder OBJECT

Package

clobber-demo

Methods

Method: holder (ACCOUNT account)

automatically generated reader method

Source

demo.lisp (file)

Generic Function: holder OBJECT

Package

clobber-demo2

Methods

Method: holder (ACCOUNT account)

automatically generated reader method

Source

demo2.lisp (file)

Generic Function: log-stream OBJECT

Package

clobber

Methods

Method: log-stream (TRANSACTION-LOG transaction-log)

automatically generated reader method

Source

clobber.lisp (file)

Generic Function: name OBJECT

Package

clobber-demo

Methods

Method: name (PERSON person)

automatically generated reader method

Source

demo.lisp (file)

Generic Function: name OBJECT

Package

clobber-demo2

Methods

Method: name (PERSON person)

automatically generated reader method

Source

demo2.lisp (file)

Generic Function: next-object-id OBJECT

Generic Function: (setf next-object-id) NEW-VALUE OBJECT

Package

clobber

Methods

Method: next-object-id (TRANSACTION-LOG transaction-log)

automatically generated reader method

Source

clobber.lisp (file)

Method: (setf next-object-id) NEW-VALUE (TRANSACTION-LOG transaction-log)

automatically generated writer method

Source

clobber.lisp (file)

Generic Function: object-id-table OBJECT

Package

clobber

Methods

Method: object-id-table (TRANSACTION-LOG transaction-log)

automatically generated reader method

Source

clobber.lisp (file)

Generic Function: save-info OBJECT

Package

clobber

Source

clobber.lisp (file)

Method Combination

append (short method combination)

Options: :most-specific-last

Methods

Method: save-info (OBJ transaction) append

Source

demo2.lisp (file)

Method: save-info (OBJ person) append

Source

demo2.lisp (file)

Method: save-info (OBJ account) append

Source

demo2.lisp (file)

Method: save-info (OBJ person) append

Source

demo.lisp (file)

Method: save-info (OBJ account) append

Source

demo.lisp (file)

Method: save-info (OBJECT standard-object) append

Generic Function: serialize OBJECT TRANSACTION-LOG

Package

clobber

Source

clobber.lisp (file)

Methods

Method: serialize (OBJECT standard-object) TRANSACTION-LOG

Method: serialize (OBJECT string) TRANSACTION-LOG

Method: serialize (OBJECT vector) TRANSACTION-LOG

Method: serialize (OBJECT cons) TRANSACTION-LOG

Method: serialize (OBJECT symbol) TRANSACTION-LOG

Method: serialize (OBJECT character) TRANSACTION-LOG

Method: serialize (OBJECT number) TRANSACTION-LOG

5.2.5 Classes

Class: account ()

Package

clobber-demo

Source

demo.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• save-info (method)
• holder (method)
• balance (method)
• balance (method)
• bank (method)
• bank (method)

Direct slots

Slot: %bank

Initargs

:bank

Readers

bank (generic function)

Writers

(setf bank) (generic function)

Slot: %balance

Initform

0

Readers

balance (generic function)

Writers

(setf balance) (generic function)

Slot: %holder

Initargs

:holder

Readers

holder (generic function)

Class: account ()

Package

clobber-demo2

Source

demo2.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• save-info (method)
• holder (method)
• balance (method)
• balance (method)
• bank (method)
• bank (method)

Direct slots

Slot: %bank

Initargs

:bank

Readers

bank (generic function)

Writers

(setf bank) (generic function)

Slot: %balance

Initform

0

Readers

balance (generic function)

Writers

(setf balance) (generic function)

Slot: %holder

Initargs

:holder

Readers

holder (generic function)

Class: bank ()

Package

clobber-demo

Source

demo.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• customers (method)
• customers (method)
• accounts (method)
• accounts (method)

Direct slots

Slot: %accounts

Initform

(quote nil)

Readers

accounts (generic function)

Writers

(setf accounts) (generic function)

Slot: %customers

Initform

(quote nil)

Readers

customers (generic function)

Writers

(setf customers) (generic function)

Class: bank ()

Package

clobber-demo2

Source

demo2.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• customers (method)
• customers (method)
• accounts (method)
• accounts (method)

Direct slots

Slot: %accounts

Initform

(quote nil)

Readers

accounts (generic function)

Writers

(setf accounts) (generic function)

Slot: %customers

Initform

(quote nil)

Readers

customers (generic function)

Writers

(setf customers) (generic function)

Class: person ()

Package

clobber-demo

Source

demo.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• save-info (method)
• name (method)

Direct slots

Slot: %name

Initargs

:name

Readers

name (generic function)

Class: person ()

Package

clobber-demo2

Source

demo2.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• save-info (method)
• name (method)

Direct slots

Slot: %name

Initargs

:name

Readers

name (generic function)

Class: transaction ()

Package

clobber-demo2

Source

demo2.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• save-info (method)
• comment (method)
• creation-date (method)
• creator (method)
• arguments (method)
• function-name (method)

Direct slots

Slot: %function-name

Initargs

:function-name

Readers

function-name (generic function)

Slot: %arguments

Initargs

:arguments

Readers

arguments (generic function)

Slot: %creator

Initargs

:creator

Initform

clobber-demo2::*operator*

Readers

creator (generic function)

Slot: %creation-date

Initargs

:creation-date

Initform

(get-universal-time)

Readers

creation-date (generic function)

Slot: %comment

Initargs

:comment

Initform

clobber-demo2::*comment*

Readers

comment (generic function)

Class: transaction-log ()

Package

clobber

Source

clobber.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• next-object-id (method)
• next-object-id (method)
• object-id-table (method)
• log-stream (method)

Direct slots

Slot: %log-streami

Initargs

:log-stream

Readers

log-stream (generic function)

Slot: %object-id-table

Initargs

:object-id-table

Readers

object-id-table (generic function)

Slot: %next-object-id

Initargs

:next-object-id

Readers

next-object-id (generic function)

Writers

(setf next-object-id) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types