License: Public Domain , Load it with Quicklisp: (ql:quickload "definitions-systems")
Library type: Data structure , Project complexity: Medium

definitions-systems provides a simple unified extensible way of processing named definitions.

Concepts

Concepts » Overview

(define-foo bar [definition...]) is one of the most pervasive design patterns in Common Lisp, especially when defining Domain-Specific Languages.

This library finally reifies the pattern once and for all, with tons of useful features you get for free and never need to implement, document or lack ever again.

Simply put, each system manages multiple named definitions, thanks to protocols.

Concepts » definitions-system designator

Most generic functions in the API that can accept a definitions-system (an instance of defsys:system) as one of its arguments can also accept a top-level definitions-system name instead (a non-nil symbol), in which case the generic function is called again with the so-named definitions system.

The definitions system is defsys:located in the root system.

This is implemented by appropriate trivial methods on defsys:locate, (setf defsys:locate), unbind, defsys:ensure, defsys:map and defsys:count.

(defsys:locate 'my-system-name 'my-definition-name)
==
(defsys:locate (defsys:locate (defsys:root-system) 'my-system-name) 'my-definition-name)

Dictionary

Dictionary » definitions-systems

Package definitions-systems

Description

Also nicknamed defsys, this package is mostly designed for explicit qualification of symbols, such as defsys:locate.
Two symbols that might be worth importing are define and locate, depending on usage.
Don't (:use)!

Dictionary » Systems

... » Systems » system

... » Systems » hash-table-mixin

Class defsys:hash-table-mixin

defsys:system

Description

This class provides implementations for all generic functions required by marker class defsys:system, backed by an internal eq hash-table. defsys:standard-system inherits from this class.

... » Systems » definition-order-mapping-mixin

... » Systems » standard-system

Dictionary » Systems » Definition checking

...2 » Definition checking » check-definition-mixin

...2 » Definition checking » base-definition-class-mixin

...2 » Definition checking » base-definition-class

Generic Function defsys:base-definition-class

system => class

Description

Returns the class that definitions of this system must be a generalized instance of. A method is defined for defsys:base-definition-class-mixin.

...2 » Definition checking » unsuitable-definition-error

Condition defsys:unsuitable-definition-error

error

Description

Slots:

((system :initarg :system
         :reader defsys:system
         :type defsys:system
         :documentation "Indicates to which system the definition was attempted to be added.")
 (definition :initarg :definition
             :reader defsys:definition
             :documentation "Indicates the definition that was found to be unsuitable for the system.")
 (details :initarg :details
          :reader defsys:details
          :initform nil
          :documentation "Provides further details on the problem that makes the definition
                          be unsuitable as a binding in system, usually in the form of a condition."))

The consequences are undefined if the :system or :definition initargs is unsupplied.

...2 » Definition checking » details

...2 » Definition checking » check-definition

Generic Function defsys:check-definition

system definition => definition

Arguments and Values

  • system -- A system.
  • definition -- A non-nil object, usually a definition.

Description

Returns definition if it appears to be a suitable definition in system system, else throws an error of type unsuitable-definition-error.

Methods

Method defsys:check-definition

(system defsys:system) definition => definition

Description

Returns definition.

Dictionary » Systems » Root systems

...2 » Root systems » root-system

Class defsys:root-system

defsys:system

Description

All root definitions-systems inherit from this class.

Function defsys:root-system

=> root-system

Arguments and Values

  • root-system -- The root system.

Description

Returns the root system.

The root system is the definitions-system whose definitions are the top-level definitions-systems.

...2 » Root systems » location-mixin

Class defsys:location-mixin

Description

Slots:

((location :initarg :location
           :reader defsys:location
           :initform nil
           :documentation "A value of nil means the location of this root system is not known, thus this system may not be externalizable."))

Method make-load-form

(mixin defsys:location-mixin) &optional environment => creation-form, initialization-form

Description

Returns (or (defsys:location mixin :errorp nil) (call-next-method)).

...2 » Root systems » location

Generic Function defsys:location

system &key errorp => location-or-nil

Arguments and Values

  • system -- A definitions-system.
  • errorp -- A generalized boolean. The default is true.
  • definition-or-nil -- A form or nil.

Description

Returns the location of this system (a form that, when evaluated, returns system), else returns nil if errorp is false or throws an error if errorp is true.

Methods

Around-Method location

system &key (errorp t) => location-or-nil

Description

Calls the next method and throws an error of type error if there is no location and errorp is true.

Method location

(system defsys:location-mixin) &key (errorp t) => location-or-nil

Description

Retrieves the location from the internal slot.

...2 » Root systems » standard-root-system

Dictionary » Definitions

... » Definitions » definition

Class defsys:definition

Description

Definitions usually inherit from this class.

... » Definitions » standard-definition

Dictionary » Definitions » Bindings tracking

...2 » Bindings tracking » name-mixin

Class defsys:name-mixin

Description

Slots:

((name :initarg :name
       :reader defsys:name
       :initform nil
       :documentation "A name of nil usually indicates an anonymous definition."))

Provides a print-object method that includes the name of the object in its output.

...2 » Bindings tracking » name

...2 » Bindings tracking » owner-mixin

Method make-load-form

(definition defsys:owner-mixin) &optional environment => creation-form, initialization-form

Description

If definition does not have an owner, then throw an error of type error.

Else, return a creation-form and initialization-form based on the results owner-locate and owner-init returned by (make-load-form owner environment).
creation-form is `(defsys:locate ,owner-locate (defsys:name definition)) and initialization-form is owner-init.

...2 » Bindings tracking » owner

Generic Function defsys:owner

object => owner

Description

Returns the owner of the object if it has one, else nil. A method is defined for defsys:owner-mixin.

...2 » Bindings tracking » primary-binding-mixin

...2 » Bindings tracking » alias-bindings-mixin

Class defsys:alias-bindings-mixin

defsys:definition

Description

Tracks the alias bindings of this definition, that is, the owner systems which have names pointing to this definition, excluding primary bindings.

...2 » Bindings tracking » map-aliasing-systems

Generic Function defsys:map-aliasing-systems

function definition => nil

Argument precedence order: definition function

Arguments and Values

  • function -- A function designator.
  • definition -- A definition.

Description

Calls function with 2 arguments, system and map-aliases, for each system that has aliases for definition.

map-aliases is a function of 1 argument, function, which will be called with 1 argument alias-name for each alias that the system has for definition.

Methods

Method map-aliasing-systems

function (definition defsys:alias-bindings-mixin) => nil

Description

Implements the specified behavior of the generic function.

Dictionary » Protocols

... » Protocols » locate

Generic Function defsys:locate

system definition-name &key => definition-or-nil

Arguments and Values

Description

Returns the definition named definition-name in system.

Methods

Around-Method locate

system definition-name &key (errorp t) => definition-or-nil

Description

Calls the next method and throws a defsys:not-found error if the definition was not found and errorp is true.

Method locate

(system-name symbol) definition-name &rest options => definition-or-nil

Description

Forwards appropriately.

Method locate

(system defsys:hash-table-mixin) definition-name &key => definition-or-nil

Description

Retrieves the definition (or lack thereof) using the internal hash-table.

... » Protocols » (setf locate)

Generic Function (setf defsys:locate)

new-definition system definition-name &key => new-definition

Arguments and Values

Description

Makes new-definition the definition associated with name definition-name in system.

Methods

Method (setf locate)

new-definition (system-name symbol) definition-name &rest options => new-definition

Description

Forwards appropriately.

Method (setf locate)

new-definition (system defsys:system) definition-name
&key ((defsys:locate locate-options)) ((defsys:replace-definition replace-options)) ((defsys:bind-definition bind-options))
=> new-definition

Description

First, let old-definition be the result of (apply #'defsys:locate system definition-name :errorp nil locate-options).

If old-definition is nil, then return (apply #'defsys:bind-definition system new-definition definition-name bind-options).

Else, if new-definition is old-definition, then return new-definition.

Else, return (apply #'defsys:replace-definition system old-definition new-definition definition-name replace-options),
except if bind-options was provided then append the result of (list 'defsys:bind-definition bind-options) to the end of replace-options.

After-Method (setf locate)

new-definition (system defsys:definition-order-mapping-mixin) definition-name &key

Description

Keeps track of the new-definition for definition-order mapping.

... » Protocols » not-found

Condition defsys:not-found

error

Description

Thrown when defsys:locate cannot find any definition named definition-name in the designated system and errorp is true (the default).

Slots:

((system :initarg :system
         :reader defsys:system
         :type defsys:system)
 (name :initarg :name
       :reader defsys:name))

... » Protocols » bind-definition

Generic Function defsys:bind-definition

system new-definition definition-name &key => new-definition

Arguments and Values

Description

Sets new-definition as the definition named definition-name in system.

The consequences are undefined if there is already a definition named definition-name in system.

Methods

Method defsys:bind-definition

(system defsys:hash-table-mixin) new-definition definition-name &key => new-definition

Description

Sets the definition using the internal hash-table.

... » Protocols » replace-definition

Generic Function defsys:replace-definition

system old-definition new-definition definition-name
&key ((defsys:unbind-definition unbind-options)) ((defsys:bind-definition bind-options))
=> new-definition

Arguments and Values

  • system -- A definitions-system designator.
  • old-definition -- A definition.
  • new-definition -- A definition.
  • definition-name -- A definition name.

Description

Sets new-definition as the definition named definition-name in system, thereby replacing old-definition.

The consequences are undefined if old-definition is not the definition named definition-name in system.

Methods

Method defsys:bind-definition

(system defsys:system) old-definition new-definition definition-name &key => new-definition

Description

Calls (apply #'defsys:unbind-definition system old-definition definition-name unbind-options),
then (apply #'defsys:bind-definition system new-definition definition-name bind-options).

... » Protocols » unbind

Generic Function defsys:unbind

system definition-name
&key ((defsys:locate locate-options)) ((defsys:unbind-definition unbind-options))
=> removedp

Arguments and Values

Description

Removes the definition named definition-name in system. Returns true if such a definition was present, else returns false.

Methods

Method unbind

(system defsys:system) definition-name => removedp

Description

If there is a definition named definition-name in system, then call (defsys:unbind-definition system definition definition-name) and return what it returns, else return false.

... » Protocols » unbind-definition

Generic Function defsys:unbind-definition

system definition definition-name => true

Arguments and Values

Description

Removes the definition definition named definition-name in system. Returns true.

The consequences are undefined if definition is not the definition named definition-name in system.

Methods

Method defsys:unbind-definition

(system defsys:hash-table-mixin) definition definition-name => true

Description

Removes the definition named definition-name from the internal hash-table.

After-Method defsys:unbind-definition

(system defsys:definition-order-mapping-mixin) definition definition-name

Description

Keeps track of the removal of definition for definition-order mapping.

... » Protocols » ensure

Generic Function defsys:ensure

system definition-name definition-class &rest initargs &key &allow-other-keys => definition

Arguments and Values

  • system -- A definitions-system designator.
  • definition-name -- A definition name.
  • definition-class -- A class designator.
  • definition -- An object.

Description

Creates or reinitializes the definition named definition-name in system.

Methods

Method ensure

(system-name symbol) definition-name definition-class &rest initargs => definition

Description

Forwards appropriately.

Method ensure

(system defsys:system) definition-name definition-class &rest initargs => definition

Description

If there is not already a definition named definition-name in system, then create such a definition by calling make-instance with definition-class, :name definition-name and initargs, and then associate this new definition with the system using (setf defsys:locate).

If there is already a definition named definition-name in system, then reinitialize that existing definition:

  • If existing is already of the class designated by definition-class, then call reinitialize-instance with existing and initargs.
  • Else, call change-class with existing, definition-class and initargs.

... » Protocols » default-system

Generic Function defsys:default-system

object => system

Arguments and Values

  • object -- An object.
  • system -- A system.

Description

Returns the default system associated with object.

Base defsys:definition classes should define an appropriate method.

Methods

Method default-system

(definition-class-name symbol) => system

Description

Returns (defsys:default-system (find-class definition-class-name)).

... » Protocols » expand

Generic Function defsys:expand

definition-prototype definition-name environment args &rest options => expansion

Arguments and Values

  • definition-prototype -- A (possibly uninitialized) defsys:definition.
  • definition-name -- A definition name.
  • environment -- The environment captured by defsys:define.
  • args -- A list. The body of the definition.
  • options -- A list.

Description

Called by defsys:define to determine its expansion.

Methods

Method expand

(prototype defsys:standard-system) name environment args &rest options => expansion

Description

Similar to the above method, but provides additional conveniences regarding systems, based on a convention.
The convention is that the name of your system is the same as that of your base definition class.

First, a new class named name is defined, inheriting from defsys:definition.

Then, the next method (above) is called to generate a call to defsys:ensure, except that :base-definition-class 'name will be appended at the end.

Lastly, a new method is defined on defsys:default-system, specializing on the new base definition class, which returns the newly defined system.

You should then create a new standard class for your definitions, inheriting from name (your base definition class) and defsys:standard-system.

... » Protocols » define

Macro defsys:define

(definition-class-name definition-name &body options) &body args &environment env

Arguments and Values

  • definition-class-name -- A symbol.
  • definition-name -- A definition name.
  • options -- A list.
  • args -- A list. The body of the definition.
  • env -- An environment.

Description

Calls defsys:expand and returns whatever it returns.

The first argument is (c2mop:class-prototype (c2mop:ensure-finalized (find-class definition-class-name))).

... » Protocols » map

Generic Function defsys:map

function system => nil

Argument precedence order: system function

Arguments and Values

Description

For each definition named name in system, function is called with arguments name and definition in an implementation-defined order.

The consequences are undefined if an attempt is made to add or remove any definition in system while such a mapping operation is in progress.

Methods

... » Protocols » count

Generic Function defsys:count

system &key => count

Arguments and Values

Description

Returns the number of definitions in system.

Methods

Method count

(system defsys:system) &key ((defsys:map map-options)) => count

Description

Returns the number of times that defsys:map calls its function argument given system. Slow, obviously. May signal a warning.