definitions-systems provides a simple unified extensible way of processing named definitions.
(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.
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)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)!
All definitions-systems inherit from this class. At least defsys:locate, (setf defsys:locate) and defsys:unbind must be supported. defsys:standard-system provides a ready-to-use implementation.
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.
This class provides a method on defsys:map that guarantees mapping in the same order that definitions were added to the defsys:system. defsys:standard-system inherits from this class.
After-methods are also defined on (setf defsys:locate) and defsys:unbind-definition to keep track of definition order.
defsys:base-definition-class-mixin defsys:standard-definition defsys:definition-order-mapping-mixin defsys:hash-table-mixin defsys:system
A ready-to-use implementation of defsys:system.
A method is defined for defsys:default-system.
This class provides a before-method on (setf defsys:locate) that calls (defsys:check-definition).
Slots:
((base-definition-class :initarg :base-definition-class
:reader defsys:base-definition-class
:type class
:canonicalize #'enhanced-find-class:find-class
:initform (find-class 'defsys:definition)))Provides a method on defsys:check-definition that ensures that the definition is a generalized instance of the system's defsys:base-definition-class.
system => class
Returns the class that definitions of this system must be a generalized instance of. A method is defined for defsys:base-definition-class-mixin.
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.
object => details
Returns the details (usually a condition) associated with the object. A method is defined for defsys:unsuitable-definition-error.
system definition => definition
definition.Returns definition if it appears to be a suitable definition in system system, else throws an error of type unsuitable-definition-error.
(system defsys:system) definition => definition
Returns definition.
(system defsys:base-definition-class-mixin) definition => definition
Returns definition if it is a subtype of (, else throws an error of type defsys:base-definition-class system)unsuitable-definition-error of which the details is a condition of type type-error.
All root definitions-systems inherit from this class.
=> root-system
Returns the root system.
The root system is the definitions-system whose definitions are the top-level definitions-systems.
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."))(mixin defsys:location-mixin) &optional environment => creation-form, initialization-form
Returns (or (.defsys:location mixin :errorp nil) (call-next-method))
system &key errorp => location-or-nil
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.
system &key (errorp t) => location-or-nil
Calls the next method and throws an error of type error if there is no location and errorp is true.
(system defsys:location-mixin) &key (errorp t) => location-or-nil
Retrieves the location from the internal slot.
defsys:location-mixin defsys:root-system defsys:standard-system
The standard root definitions-systems (as returned by function defsys:root-system) inherits from this class.
A method is defined for defsys:default-system.
Definitions usually inherit from this class.
defsys:primary-binding-mixin defsys:alias-bindings-mixin defsys:definition
A ready-to-use implementation of defsys:definition.
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.
object => name
Returns the name of the object. Methods are defined for defsys:name-mixin and defsys:not-found.
Slots:
((owner :reader defsys:owner
:type (or null defsys:system)
:initform nil))(definition defsys:owner-mixin) &optional environment => creation-form, initialization-form
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.
object => owner
Returns the owner of the object if it has one, else nil. A method is defined for defsys:owner-mixin.
defsys:owner-mixin defsys:name-mixin defsys:definition
Tracks the primary binding of this definition, that is, the owner system of which the name binding is this definition.
Tracks the alias bindings of this definition, that is, the owner systems which have names pointing to this definition, excluding primary bindings.
function definition => nil
Argument precedence order: definition function
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.
function (definition defsys:alias-bindings-mixin) => nil
Implements the specified behavior of the generic function.
system definition-name &key => definition-or-nil
Returns the definition named definition-name in system.
system definition-name &key (errorp t) => definition-or-nil
Calls the next method and throws a defsys:not-found error if the definition was not found and errorp is true.
(system-name symbol) definition-name &rest options => definition-or-nil
(system defsys:hash-table-mixin) definition-name &key => definition-or-nil
Retrieves the definition (or lack thereof) using the internal hash-table.
(system defsys:standard-root-system) definition-name &key (errorp t) => definition-or-nil
If definition-name is the symbol defsys:system, returns system, else calls the next method.
This method notably ensures that the symbol defsys:system can be used as a designator for the root definitions-system.
new-definition system definition-name &key => new-definition
Makes new-definition the definition associated with name definition-name in system.
new-definition (system-name symbol) definition-name &rest options => new-definition
(new-definition defsys:owner-mixin) (system defsys:system) definition-name &key
Assigns system as the new defsys:owner of new-definition if it does not already have one.
new-definition (system defsys:system) definition-name
&key ((defsys:locate locate-options)) ((defsys:replace-definition replace-options)) ((defsys:bind-definition bind-options))
=> new-definition
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.
new-definition (system defsys:definition-order-mapping-mixin) definition-name &key
Keeps track of the new-definition for definition-order mapping.
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))system new-definition definition-name &key => new-definition
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.
(system defsys:hash-table-mixin) new-definition definition-name &key => new-definition
Sets the definition using the internal hash-table.
(system defsys:check-definition-mixin) new-definition definition-name &key
Calls (.defsys:check-definition system new-definition definition-name)
system old-definition new-definition definition-name
&key ((defsys:unbind-definition unbind-options)) ((defsys:bind-definition bind-options))
=> new-definition
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.
(system defsys:system) old-definition new-definition definition-name &key => new-definition
Calls (apply #'defsys:unbind-definition system old-definition definition-name unbind-options),
then (apply #'defsys:bind-definition system new-definition definition-name bind-options).
system definition-name
&key ((defsys:locate locate-options)) ((defsys:unbind-definition unbind-options))
=> removedp
Removes the definition named definition-name in system. Returns true if such a definition was present, else returns false.
(system-name symbol) definition-name => removedp
(system defsys:system) definition-name => removedp
If there is a definition named definition-name in system, then call ( and return what it returns, else return false.defsys:unbind-definition system definition definition-name)
system definition definition-name => true
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.
(system defsys:hash-table-mixin) definition definition-name => true
Removes the definition named definition-name from the internal hash-table.
(system defsys:definition-order-mapping-mixin) definition definition-name
Keeps track of the removal of definition for definition-order mapping.
system definition-name definition-class &rest initargs &key &allow-other-keys => definition
Creates or reinitializes the definition named definition-name in system.
(system-name symbol) definition-name definition-class &rest initargs => definition
(system defsys:system) definition-name definition-class &rest initargs => definition
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:
object => system
Returns the default system associated with object.
Base defsys:definition classes should define an appropriate method.
(definition-class-name symbol) => system
Returns (.defsys:default-system (find-class definition-class-name))
(definition-class class) => system
Returns (.defsys:default-system (c2mop:class-prototype (c2mop:ensure-finalized definition-class)))
(system defsys:standard-system) => system
Returns (.defsys:root-system)
(system defsys:standard-root-system) => |
Throws an error of type error.
definition-prototype definition-name environment args &rest options => expansion
defsys:definition.defsys:define.Called by defsys:define to determine its expansion.
(prototype defsys:standard-definition) name environment args &rest options => expansion
Provides a flexible default syntax for defsys:define by straightforwardly expanding to a call to defsys:ensure.
Returns `(.defsys:ensure ,(defsys:default-system prototype) ',name ,(class-of prototype) ,@args)
(prototype defsys:standard-system) name environment args &rest options => expansion
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.
(definition-class-name definition-name &body options) &body args &environment env
Calls defsys:expand and returns whatever it returns.
The first argument is (c2mop:class-prototype (c2mop:ensure-finalized (find-class definition-class-name))).
function system => nil
Argument precedence order: system function
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.
function (system-name symbol) => nil
function (system defsys:hash-table-mixin) => nil
Calls maphash on function and system's internal hash-table.
function (system defsys:definition-order-mapping-mixin) => nil
Guarantees mapping in the same order that definitions were added to the defsys:system.
system &key => count
Returns the number of definitions in system.
(system-name symbol) &key => count
(system defsys:system) &key ((defsys:map map-options)) => count
Returns the number of times that defsys:map calls its function argument given system. Slow, obviously. May signal a warning.
(system defsys:hash-table-mixin) &key => count
Calls hash-table-count on system's internal hash-table.