The serapeum Reference Manual

Source

Methods

Method: add-hook ((hook hook-any) (handler handler-any) &key append) ¶

Add HANDLER to HOOK. Return HOOK. HOOK must be of type HOOK-ANY HANDLER must be of type HANDLER-ANY.

Source: hooks.lisp.

Method: add-hook ((hook hook-number->number) (handler handler-number->number) &key append) ¶

Add HANDLER to HOOK. Return HOOK.
HOOK must be of type HOOK-NUMBER->NUMBER HANDLER must be of type HANDLER-NUMBER->NUMBER.

Source: hooks.lisp.

Method: add-hook ((hook hook-string->string) (handler handler-string->string) &key append) ¶

Add HANDLER to HOOK. Return HOOK.
HOOK must be of type HOOK-STRING->STRING HANDLER must be of type HANDLER-STRING->STRING.

Source: hooks.lisp.

Method: add-hook ((hook hook-void) (handler handler-void) &key append) ¶

Add HANDLER to HOOK. Return HOOK. HOOK must be of type HOOK-VOID HANDLER must be of type HANDLER-VOID.

Source: hooks.lisp.

Method: add-hook ((hook symbol) fn &key append) ¶

Generic Reader: combination (object) ¶

Generic Writer: (setf combination) (object) ¶

Package

Methods

Reader Method: combination ((hook hook)) ¶

Writer Method: (setf combination) ((hook hook)) ¶

This can be used to reverse the execution order, return a single value, etc.

Source: hooks.lisp.
Target Slot: combination.

Generic Function: combine-composed-hook (hook &rest args) ¶

Package

Methods

Method: combine-composed-hook ((hook hook) &rest args) ¶

Return the result of the composition of the HOOK handlers on ARGS, from oldest to youngest.
Without handler, return ARGS as values.
This is an acceptable ‘combination’ for ‘hook’.

Source: hooks.lisp.

Generic Function: combine-hook-until-failure (hook &rest args) ¶

Package

Methods

Method: combine-hook-until-failure ((hook hook) &rest args) ¶

Return the list of values until the first nil result.
Handlers after the failing one are not run.

You need to check if the hook has handlers to know if a NIL return value is due to the first handler failing or an empty hook.

This is an acceptable ‘combination’ for ‘hook’.

Source: hooks.lisp.

Generic Function: combine-hook-until-success (hook &rest args) ¶

Package

Methods

Method: combine-hook-until-success ((hook hook) &rest args) ¶

Return the value of the first non-nil result.
Handlers after the successful one are not run.

You need to check if the hook has handlers to know if a NIL return value is due to all handlers failing or an empty hook.

This is an acceptable ‘combination’ for ‘hook’.

Source: hooks.lisp.

Generic Function: default-combine-hook (hook &rest args) ¶

Package

Methods

Method: default-combine-hook ((hook hook) &rest args) ¶

Return the list of the results of the HOOK handlers applied from youngest to oldest to ARGS.
Return ’() when there is no handler.
This is an acceptable ‘combination’ for ‘hook’.

Source: hooks.lisp.

Generic Reader: description (object) ¶

Generic Writer: (setf description) (object) ¶

Package

Methods

Reader Method: description ((handler handler)) ¶

Writer Method: (setf description) ((handler handler)) ¶

Description of the handler. This is purely informative.

Source: hooks.lisp.
Target Slot: description.

Generic Function: disable-hook (hook &rest handlers) ¶

Package

Methods

Method: disable-hook ((hook hook) &rest handlers) ¶

Prepend HANDLERS to the list of disabled handlers. Without HANDLERS, disable all of them.

Source: hooks.lisp.

Generic Reader: disabled-handlers (object) ¶

Generic Writer: (setf disabled-handlers) (object) ¶

Package

Methods

Reader Method: disabled-handlers ((hook hook)) ¶

Writer Method: (setf disabled-handlers) ((hook hook)) ¶

Those handlers are not run by ‘run-hook’.
This is useful it the user wishes to disable some or all handlers without removing them from the hook.

Source: hooks.lisp.
Target Slot: disabled-handlers.

Generic Function: enable-hook (hook &rest handlers) ¶

Package

Methods

Method: enable-hook ((hook hook) &rest handlers) ¶

Prepend HANDLERS to the list of HOOK’s handlers. Without HANDLERS, enable all of them.

Source: hooks.lisp.

Generic Reader: fn (object) ¶

Generic Writer: (setf fn) (object) ¶

Package

Methods

Reader Method: fn ((handler handler)) ¶

Writer Method: (setf fn) ((handler handler)) ¶

The handler function. It can be an anonymous function.

Source: hooks.lisp.
Target Slot: fn.

Generic Reader: handler-type (object) ¶

Generic Writer: (setf handler-type) (object) ¶

Package

Methods

Reader Method: handler-type ((handler handler)) ¶

Writer Method: (setf handler-type) ((handler handler)) ¶

The function type of FN. This is purely informative.

Source: hooks.lisp.
Target Slot: handler-type.

Generic Reader: handlers (object) ¶

Generic Writer: (setf handlers) (object) ¶

Package

Methods

Reader Method: handlers ((hook hook)) ¶

Writer Method: (setf handlers) ((hook hook)) ¶

Source: hooks.lisp.
Target Slot: handlers.

Generic Reader: inconsistent-graph-constraints (condition) ¶

The constraints of an ‘inconsistent-graph’ error. Cf. ‘toposort’.

Package

Methods

Reader Method: inconsistent-graph-constraints ((condition inconsistent-graph)) ¶

Source: sequences.lisp.
Target Slot: constraints.

Generic Function: monitor (object) ¶

Return a unique lock associated with OBJECT.

Package

Source

threads.lisp.

Methods

Reader Method: monitor ((synchronized synchronized)) ¶

automatically generated reader method

Target Slot: monitor.

Method: monitor (object) ¶

Method: monitor ((object mutex)) ¶

Generic Reader: name (object) ¶

Generic Writer: (setf name) (object) ¶

Package

Methods

Reader Method: name ((handler handler)) ¶

Writer Method: (setf name) ((handler handler)) ¶

Name of the handler.
If defaults to the function name if ‘fn’ is a named function.
This is useful so that the user can build handlers out of anonymous functions.

Source: hooks.lisp.
Target Slot: name.

Generic Reader: place (object) ¶

Generic Writer: (setf place) (object) ¶

Package

Methods

Reader Method: place ((handler handler)) ¶

Writer Method: (setf place) ((handler handler)) ¶

If the handler is meant to be a setter, PLACE describes what is set. PLACE can be a symbol or a pair (CLASS SLOT).
This can be left empty if the handler is not a setter.

Source: hooks.lisp.
Target Slot: place.

Generic Function: remove-hook (hook fn) ¶

Remove FN from the symbol value of HOOK.

Package

Source

Methods

Method: remove-hook ((hook hook) handler-or-name) ¶

Remove handler matching HANDLER-OR-NAME from the handlers or the disabled-handlers in HOOK.
HANDLER-OR-NAME is either a handler object or a symbol. Return HOOK’s handlers.

Source: hooks.lisp.

Method: remove-hook ((hook symbol) fn) ¶

Generic Function: run-hook (hook &rest args) ¶

Apply each function in HOOK to ARGS.

Package

Source

Methods

Method: run-hook ((hook hook) &rest args) ¶

Source: hooks.lisp.

Method: run-hook ((*hook* symbol) &rest args) ¶

Generic Function: run-hook-until-failure (hook &rest args) ¶

Like ‘run-hook-with-args’, but quit once a function returns nil.

Package

Source

Methods

Method: run-hook-until-failure ((*hook* symbol) &rest args) ¶

Generic Function: run-hook-until-success (hook &rest args) ¶

Like ‘run-hook-with-args’, but quit once a function returns non-nil.

Package

Source

Methods

Method: run-hook-until-success ((*hook* symbol) &rest args) ¶

Generic Function: run-hook-with-args-until-failure (hook &rest args) ¶

Package

Methods

Method: run-hook-with-args-until-failure ((hook hook) &rest args) ¶

This is equivalent to setting the combination function to ‘combine-hook-until-failure’ and calling ‘run-hook’.

Source: hooks.lisp.

Generic Function: run-hook-with-args-until-success (hook &rest args) ¶

Package

Methods

Method: run-hook-with-args-until-success ((hook hook) &rest args) ¶

This is equivalent to setting the combination function to ‘combine-hook-until-success’ and calling ‘run-hook’.

Source: hooks.lisp.

Generic Reader: static-binding-flush-error-all-groups-p (condition) ¶

Package

Methods

Reader Method: static-binding-flush-error-all-groups-p ((condition static-binding-flush-error)) ¶

Source: static-let.lisp.
Target Slot: all-groups-p.

Generic Reader: static-binding-flush-error-group (condition) ¶

Package

Methods

Reader Method: static-binding-flush-error-group ((condition static-binding-flush-error)) ¶

Source: static-let.lisp.
Target Slot: group.

Generic Reader: value (object) ¶

Generic Writer: (setf value) (object) ¶

Package

Methods

Reader Method: value ((handler handler)) ¶

Writer Method: (setf value) ((handler handler)) ¶

If the handler is meant to be a setter, VALUE can be used to describe what FN is going to set to PLACE.
In particular, PLACE and VALUE can be used to compare handlers.
This can be left empty if the handler is not a setter.

Source: hooks.lisp.
Target Slot: value.

Next: Method combinations, Previous: Generic functions, Up: Public Interface [Contents][Index]

6.1.9 Standalone methods

Method: initialize-instance :around ((class topmost-object-class) &rest initargs &key direct-superclasses topmost-class) ¶

Source: mop.lisp.

Method: make-load-form ((queue queue) &optional env) ¶

Source: queue.lisp.

Method: make-load-form ((self box) &optional env) ¶

Source: box.lisp.

Method: make-load-form ((self %read-only-struct) &optional env) ¶

Source: defining-types.lisp.

Method: make-load-form ((self agroup) &optional env) ¶

Source: sequences.lisp.

Method: make-load-form ((self unbound) &optional env) ¶

Source: definitions.lisp.

Method: make-load-form ((self subenv) &optional env) ¶

Source: internal-definitions.lisp.

Method: make-load-form ((self bounds) &optional env) ¶

Source: vector=.lisp.

Method: print-object ((self topmost-object-class) stream) ¶

Source: mop.lisp.

Method: print-object ((queue queue) stream) ¶

Source: queue.lisp.

Method: print-object ((self box) stream) ¶

Source: box.lisp.

Method: print-object ((object agroup) stream) ¶

Source: sequences.lisp.

Method: print-object ((object subenv) stream) ¶

Source: internal-definitions.lisp.

Method: print-object ((object bounds) stream) ¶

Source: vector=.lisp.

Method: reinitialize-instance :around ((class topmost-object-class) &rest initargs &key direct-superclasses) ¶

Source: mop.lisp.

Method: validate-superclass ((class1 topmost-object-class) (class2 standard-class)) ¶

Package: sb-mop.
Source: mop.lisp.

Next: Conditions, Previous: Standalone methods, Up: Public Interface [Contents][Index]

6.1.10 Method combinations

Method Combination: standard/context () ¶

Package: serapeum.
Source: mop.lisp.

Next: Structures, Previous: Method combinations, Up: Public Interface [Contents][Index]

6.1.11 Conditions

Condition: case-failure ¶

A subtype of type-error specifically for case failures.

Package: serapeum.
Source: macro-tools.lisp.
Direct superclasses: type-error.

Condition: dispatch-case-error ¶

Package

dispatch-case-error-matched-types.

Source

dispatch-case.lisp.

Direct superclasses

type-error.

Direct methods

Direct Default Initargs

Initarg	Value
`:matched-types`	`nil`

Direct slots

Slot: matched-types-slot ¶

Package: serapeum/dispatch-case.
Initargs: :matched-types
Readers: dispatch-case-error-matched-types.
Writers: This slot is read-only.

Condition: econd-failure ¶

An ECOND failed.

Package

Source

control-flow.lisp.

Direct superclasses

error.

Direct Default Initargs

Initarg	Value
`:test-count`	`0`

Direct slots

Slot: test-count ¶

Initargs: :test-count

Condition: inconsistent-graph ¶

A graph that cannot be consistently sorted.

Package

inconsistent-graph-constraints.

Source

sequences.lisp.

Direct superclasses

error.

Direct methods

Direct slots

Slot: constraints ¶

The offending constraints

Initargs: :constraints
Readers: inconsistent-graph-constraints.
Writers: This slot is read-only.

Condition: letrec-restriction-violation ¶

Violation of the letrec restriction.

The "letrec restriction" means that the expressions being bound in a ‘letrec’ cannot refer to the value of other bindings in the same ‘letrec’.

For ‘fbindrec’, the restriction applies everywhere. For ‘fbindrec*’, it only applies to functions not yet bound.

Package

Source

fbind.lisp.

Direct superclasses

error.

Direct methods

(setf args-of).
args-of.

Direct slots

Slot: args ¶

Initargs: :args
Readers: args-of.
Writers: (setf args-of).

Condition: recursion-forbidden ¶

Package

Source

control-flow.lisp.

Direct superclasses

error.

Direct slots

Slot: form ¶

Initargs: :form

Condition: static-binding-active-error ¶

A subtype of error related to attempts to flush static bindings which are currently active.

Package

Source

static-let.lisp.

Direct superclasses

program-error.
static-binding-flush-error.

Direct Default Initargs

Initarg	Value
`:group`	`(required-argument group)`

Condition: static-binding-flush-error ¶

A subtype of error related to attempts to flush static bindings in a potentially unsafe way.

Package

static-binding-active-error.

Source

static-let.lisp.

Direct superclasses

error.

Direct subclasses

Direct methods

static-binding-flush-error-all-groups-p.
static-binding-flush-error-group.

Direct Default Initargs

Initarg	Value
`:all-groups-p`	`nil`
`:group`	`nil`

Direct slots

Slot: group ¶

Package: serapeum/static-let.
Initargs: :group
Readers: static-binding-flush-error-group.
Writers: This slot is read-only.

Slot: all-groups-p ¶

Package: serapeum/static-let.
Initargs: :all-groups-p
Readers: static-binding-flush-error-all-groups-p.
Writers: This slot is read-only.

Condition: static-load-time-value-error ¶

Package

Source

portability.lisp.

Direct superclasses

error.

Direct slots

Slot: form ¶

Initargs: :form

Slot: read-only-p ¶

Initargs: :read-only-p

Next: Classes, Previous: Conditions, Up: Public Interface [Contents][Index]

6.1.12 Structures

Structure: box ¶

A box is just a mutable cell.

You create a box using ‘box’ and get and set its value using the accessor ‘unbox’.

(def a-box (box t))
(unbox a-box) => t
(setf (unbox a-box) nil)
(unbox a-box) => nil

Serapeum attempts to provide the guarantee that, on Lisps that support atomic operations (compare-and-swap), ‘unbox‘ on boxes should be updateable atomically. (See [atomics](https://github.com/Shinmera/atomics)).

At the moment, boxes are implemented as structures, but that may change. In particular, you should not depend on being able to recognize boxes using a type or predicate.

Package

Source

box.lisp.

Direct superclasses

structure-object.

Direct methods

make-load-form.
print-object.

Direct slots

Slot: unbox ¶

Readers: unbox.
Writers: (setf unbox).

Structure: queue ¶

Basic cons queues, with an implementation based on PAIP and the original Norvig & Waters paper, and an API mostly borrowed from Arc.

About Arc. For the most part, Arc-style identifiers are pessimal, neither quite opaque nor quite explicit, like riddles. But by using abbreviated names, we avoid the danger of clashing with special-purpose queue implementations.

Create a queue with ‘queue’, like ‘list’:

(queue 1 2 3) => #<QUEUE (1 2 3)>

Get the items with ‘qlist’:

(qlist (queue 1 2 3)) => ’(1 2 3)

Add items with ‘enq’:

(enq 3 (queue 1 2)) => #<QUEUE (1 2 3)>

Remove an item with ‘deq’:

(deq (queue 1 2 3)) => 3

Prepend an item with ‘undeq’:

(qlist (undeq 1 (queue 2 3))) => ’(1 2 3)

To (destructively) join a list to the end of the queue, use ‘qconc’:

(qconc (queue 1 2 3) ’(4 5 6)) => #<QUEUE (1 2 3 4 5 6)>

The rest of the API:

- ‘queuep’ Test for a queue
- ‘qlen’ Like ‘(length (qlist ...))’
- ‘clear-queue’ Clear the queue
- ‘front’ Like ‘(car (qlist ...))’
- ‘qback’ Get the last element of the queue
- ‘queue-empty-p’ Test if the queue is empty
- ‘qappend’ Non-destructively join a list to the end of the queue - ‘qconc’ Destructively join a list to the end of the queue
- ‘qprepend’ Non-destructively join a list to the front of the queue

Note that support for both ‘deq’ and ‘undeq’ means that a queue is also effectively a stack. (But not quite a double-ended queue: you can push to either end, and pop from the front, but you can’t pop from the end.)

The idea is that *collecting* is something we do often enough to justifying making *collectors* (queues) first-class.

Package

Source

queue.lisp.

Direct superclasses

structure-object.

Direct methods

make-load-form.
print-object.

Direct slots

Slot: cons ¶

Package: common-lisp.
Type: cons
Initform: (error "no cons!")
Readers: queue-cons.
Writers: This slot is read-only.

Next: Types, Previous: Structures, Up: Public Interface [Contents][Index]

6.1.13 Classes

Class: handler ¶

Handlers are wrappers around functions used in typed hooks.
They serve two purposes as opposed to regular functions:

- They can embed a NAME so that anonymous functions can be conveniently used in lambda.
- If the handler is meant to be a setter, the PLACE and VALUE slot can be used to identify and compare setters.

With this extra information, it’s possible to compare handlers and, in particular, avoid duplicates in hooks.

Package

Source

Direct subclasses

handler-any.
handler-number->number.
handler-string->string.
handler-void.

Direct methods

(setf description).
description.
equals.
(setf fn).
fn.
(setf handler-type).
handler-type.
(setf name).
name.
(setf place).
place.
(setf value).
value.

Direct slots

Slot: name ¶

Name of the handler.
If defaults to the function name if ‘fn’ is a named function.
This is useful so that the user can build handlers out of anonymous functions.

Type: symbol
Initargs: :name
Readers: name.
Writers: (setf name).

Slot: description ¶

Description of the handler. This is purely informative.

Type: string
Initform: ""
Initargs: :description
Readers: description.
Writers: (setf description).

Slot: fn ¶

The handler function. It can be an anonymous function.

Type: function
Initform: (alexandria:required-argument (quote serapeum/contrib/hooks:fn))
Initargs: :fn
Readers: fn.
Writers: (setf fn).

Slot: handler-type ¶

The function type of FN. This is purely informative.

Initargs: :handler-type
Readers: handler-type.
Writers: (setf handler-type).

Slot: place ¶

If the handler is meant to be a setter, PLACE describes what is set. PLACE can be a symbol or a pair (CLASS SLOT).
This can be left empty if the handler is not a setter.

Type: (or symbol list)
Initargs: :place
Readers: place.
Writers: (setf place).

Slot: value ¶

Initargs: :value
Readers: value.
Writers: (setf value).

Class: handler-any ¶

Package: serapeum/contrib/hooks.
Source: hooks.lisp.
Direct superclasses: handler.
Direct methods: add-hook.

Class: handler-number->number ¶

Package: serapeum/contrib/hooks.
Source: hooks.lisp.
Direct superclasses: handler.
Direct methods: add-hook.

Class: handler-string->string ¶

Package: serapeum/contrib/hooks.
Source: hooks.lisp.
Direct superclasses: handler.
Direct methods: add-hook.

Class: handler-void ¶

Package: serapeum/contrib/hooks.
Source: hooks.lisp.
Direct superclasses: handler.
Direct methods: add-hook.

Class: hook ¶

This hook class serves as support for typed-hook.

Typing in hook is crucial to guarantee that a hook is well formed, i.e. that it’s handlers accept the right argument types and return the right value types.

Because typing is too limited in Common Lisp, we leverage CLOS to generate subclasses of ‘hook’ and ‘handlers’ with typed helper functions.
The ‘add-hook’ will thus only accept handlers of the right types.
This implementation is good enough to catch typing errors at compile time.

Package

Source

Direct subclasses

hook-any.
hook-number->number.
hook-string->string.
hook-void.

Direct methods

(setf combination).
combination.
combine-composed-hook.
combine-hook-until-failure.
combine-hook-until-success.
default-combine-hook.
disable-hook.
(setf disabled-handlers).
disabled-handlers.
enable-hook.
handler-class.
(setf handlers).
handlers.
remove-hook.
run-hook.
run-hook-with-args-until-failure.
run-hook-with-args-until-success.

Direct slots

Slot: handler-class ¶

The class of the supported handlers.

Type: symbol
Initform: t
Readers: handler-class.
Writers: This slot is read-only.

Slot: handlers ¶

Type: list
Initform: (quote nil)
Initargs: :handlers
Readers: handlers.
Writers: (setf handlers).

Slot: disabled-handlers ¶

Those handlers are not run by ‘run-hook’.
This is useful it the user wishes to disable some or all handlers without removing them from the hook.

Type: list
Initform: (quote nil)
Initargs: :disabled-handlers
Readers: disabled-handlers.
Writers: (setf disabled-handlers).

Slot: combination ¶

This can be used to reverse the execution order, return a single value, etc.

Type: function
Initform: (function serapeum/contrib/hooks:default-combine-hook)
Initargs: :combination
Readers: combination.
Writers: (setf combination).

Class: hook-any ¶

Package

Source

Direct superclasses

Direct methods

Direct slots

Slot: handler-class ¶

Initform: (quote serapeum/contrib/hooks:handler-any)

Class: hook-number->number ¶

Package

Source

Direct superclasses

Direct methods

Direct slots

Slot: handler-class ¶

Initform: (quote serapeum/contrib/hooks:handler-number->number)

Class: hook-string->string ¶

Package

Source

Direct superclasses

Direct methods

Direct slots

Slot: handler-class ¶

Initform: (quote serapeum/contrib/hooks:handler-string->string)

Class: hook-void ¶

Package

Source

Direct superclasses

Direct methods

Direct slots

Slot: handler-class ¶

Initform: (quote serapeum/contrib/hooks:handler-void)

Class: synchronized ¶

Mixin for a class with its own monitor.

Package

Source

threads.lisp.

Direct methods

monitor.

Direct slots

Slot: monitor ¶

Initform: (bordeaux-threads:make-recursive-lock)
Readers: monitor.
Writers: This slot is read-only.

Class: topmost-object-class ¶

Package