definitions-systems provides a simple unified extensible way of processing named definitions.
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 and defsys:expand.
(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), defsys:unbind and defsys:boundp 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.
defsys:system defsys:base-definition-class-mixin defsys:standard-definition defsys:hash-table-mixin
A ready-to-use implementation of defsys: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."))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:root-system defsys:standard-system
The standard root definitions-systems (as returned by function defsys:root-system) inherits from this class.
Provides a make-load-form method that returns the form (.defsys:root-system)
Definitions usually inherit from this class.
defsys:definition defsys:name-mixin defsys:owner-mixin
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
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 (system defsys:check-definition-mixin) definition-name &key => new-definition
Calls (.defsys:check-definition system new-definition definition-name)
(new-definition defsys:owner-mixin) (system defsys:system) definition-name &key => new-definition
Assigns system as the new defsys:owner of new-definition if it does not already have one.
new-definition (system defsys:hash-table-mixin) definition-name &key => new-definition
Sets the definition using the internal hash-table.
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 definition-name => 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:system) (definition defsys:owner-mixin) definition-name
If definition's defsys:owner is system, then set it to nil.
system definition-name => generalized-boolean
Returns true if there is a definition named definition-name in system, else returns false.
system definition-name => generalized-boolean
Simply attempts to defsys:locate the definition-name with errorp being false, returns true if this was successful, else false.
system definition-name class &rest initargs => definition
Creates or reinitializes the definition named definition-name in system.
(system-name symbol) definition-name class &rest initargs => definition
(system defsys:system) definition-name 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:
system definition-name environment args &rest options => expansion
defsys:define.Called by defsys:define to determine its expansion.
(system-name symbol) definition-name environment args &rest options => expansion
(system defsys:simple-expansion-mixin) definition-name environment args &rest options => expansion
Gives the following simple syntax to defsys:define: (defsys:define (kind definition-name) [definition-class] &rest initargs)
If ( is true at compile-time, then the definition-class is required and must evaluate (at runtime) to a class or to the symbol defsys:explicit-definition-class-p system)t, in which case the definition-class is determined by calling defsys:definition-class. Else, the definition-class is omitted and is determined by calling defsys:definition-class.
The initargs are computed by calling (apply #' at compile-time, and the keywords of the resulting plist will be automatically quoted during expansion as appropriate if non-keyword symbols are used.defsys:expand-args system args)
We then call (apply #'.defsys:ensure system 'name definition-class initargs)
(kind definition-name &body options) &body args
Calls defsys:expand and returns whatever it returns.
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.
system => count
Returns the number of definitions in system.
(system-name symbol) => count
(system defsys:system) => 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) => count
Calls hash-table-count on system's internal hash-table.
Slots:
((default-definition-class :initarg :default-definition-class
:reader defsys:default-definition-class
:type (or null class)
:canonicalize #'%maybe-find-class
:initform nil
:documentation "A value of nil means there is no default definition class for this system."))%maybe-find-class is an internal function that forwards its argument to enhanced-find-class:find-class unless its argument is nil, in which case it returns nil.
system &key => class-or-nil
Returns the default definition class for system, else returns nil if errorp is false or throws an error if errorp is true.
system &key (errorp t) => class-or-nil
Calls the next method and throws an error of type error if there is no default definition class and errorp is true.
(system defsys:default-definition-class-mixin) &key => class-or-nil
Retrieves the default definition class from the internal slot.
defsys:default-definition-class-mixin
Slots:
((explicit-definition-class-p :initarg :explicit-definition-class-p
:reader defsys:explicit-definition-class-p
:type boolean
:initform nil))
system => explicit-definition-class-p
Indicates whether or not defsys:expand should accept a class argument before the initargs. A method is defined for defsys:simple-expansion-mixin.
system &rest initargs => class
Returns the class that should be used for the definition according to initargs if no class has been explicitly specified.
(system defsys:system) &rest initargs => class
Calls ( and returns what it returns.defsys:default-definition-class system)
system &rest initargs => expanded-initargs
Transforms the abstract initargs into the concrete expanded-initargs.
(system-name symbol) &rest initargs => expanded-initargs
(system defsys:system) &rest initargs => transformed-initargs
Returns initargs.