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 » 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 and defsys:expand.

(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

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 » 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."))

...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

Method location :around

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

Class defsys:primary-binding-mixin

defsys:owner-mixin defsys:name-mixin

Description

Tracks the primary binding of this definition, that is, the owner system of which the name binding is this definition.

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

Class defsys:alias-bindings-mixin

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

Method locate :around

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.

After-Method (setf locate)

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

Description

Assigns system as the new defsys:owner of new-definition if it does not already have one.

Method (setf locate)

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

Description

Sets the definition using the internal hash-table.

... » 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 » unbind

Generic Function defsys:unbind

system definition-name => 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.

... » Protocols » boundp

Generic Function defsys:boundp

system definition-name => generalized-boolean

Arguments and Values

Description

Returns true if there is a definition named definition-name in system, else returns false.

Methods

Method boundp

system definition-name => generalized-boolean

Description

Simply attempts to defsys:locate the definition-name with errorp being false, returns true if this was successful, else false.

... » Protocols » ensure

Generic Function defsys:ensure

system definition-name class &rest initargs => definition

Arguments and Values

Description

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

Methods

Method ensure

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

Description

Forwards appropriately.

Method ensure

(system defsys:system) definition-name 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 » expand

Generic Function defsys:expand

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

Arguments and Values

  • system -- A definitions-system designator.
  • 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

(system-name symbol) definition-name environment args &rest options => expansion

Description

Forwards appropriately.

Method expand

(system defsys:simple-expansion-mixin) definition-name environment args &rest options => expansion

Description

Gives the following simple syntax to defsys:define: (defsys:define (kind definition-name) [definition-class] &rest initargs)

If (defsys:explicit-definition-class-p system) is true at compile-time, then the definition-class is required and must evaluate (at runtime) to a class or to the symbol 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 #'defsys:expand-args system args) at compile-time, and the keywords of the resulting plist will be automatically quoted during expansion as appropriate if non-keyword symbols are used.

We then call (apply #'defsys:ensure system 'name definition-class initargs).

... » Protocols » define

Macro defsys:define

(kind definition-name &body options) &body args

Arguments and Values

  • kind -- A symbol naming the kind of definition.
  • definition-name -- A definition name.
  • options -- A list.
  • args -- A list. The body of the definition.

Description

Calls defsys:expand and returns whatever it returns.

... » 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 => count

Arguments and Values

Description

Returns the number of definitions in system.

Methods

Method count

(system defsys:system) => count

Description

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

Dictionary » Simple expansion

... » Simple expansion » default-definition-class-mixin

Class defsys:default-definition-class-mixin

Metaclass: canon-initargs:standard-class

Description

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.

... » Simple expansion » default-definition-class

Generic Function defsys:default-definition-class

system &key => class-or-nil

Arguments and Values

  • system -- A definitions-system.
  • definition-or-nil -- A class or nil.

Description

Returns the default definition class for system, else returns nil if errorp is false or throws an error if errorp is true.

Methods

Method default-definition-class :around

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

Description

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

... » Simple expansion » simple-expansion-mixin

... » Simple expansion » explicit-definition-class-p

Generic Function defsys:explicit-definition-class-p

system => explicit-definition-class-p

Description

Indicates whether or not defsys:expand should accept a class argument before the initargs. A method is defined for defsys:simple-expansion-mixin.

... » Simple expansion » definition-class

Generic Function defsys:definition-class

system &rest initargs => class

Arguments and Values

  • system -- A definitions-system.
  • initargs -- A plist.
  • class -- A class.

Description

Returns the class that should be used for the definition according to initargs if no class has been explicitly specified.

Methods

... » Simple expansion » expand-args

Generic Function defsys:expand-args

system &rest initargs => expanded-initargs

Arguments and Values

Description

Transforms the abstract initargs into the concrete expanded-initargs.

Methods

Method expand-args

(system defsys:system) &rest initargs => transformed-initargs

Description

Returns initargs.