The modularize-interfaces Reference Manual

Table of Contents

The modularize-interfaces Reference Manual

This is the modularize-interfaces Reference Manual, version 0.9.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 14:26:14 2020 GMT+0.

1 Introduction

About Modularize-Interfaces

This is an extension to Modularize that allows your application to define interfaces in-code that serve both as a primary documentation and as compliance control. Other modules can then implement interfaces to provide the actual functionality as outlined in the definition. A good example for a scenario in which this would be useful is databases. If other parts of the application can rely on a standardised interface it won't matter which database is really connected underneath and the type of database connection can be switched without having to change any of the other modules that rely on this functionality.

How To

Interfaces are defined through DEFINE-INTERFACE. These calls consist of a name (or a list of names) for the interface and a body of component definitions. You can define your own components, but more on that later. By default there are components for functions, macros, generic functions, methods and classes. A simple interface might look like so:

(define-interface radio
  (defun listen (frequency)
    "Listens on a given frequency for radio signals and outputs them.")
  (defun scan ()
    "Attempts to search the radio frequency range for recognisable signals.")
  (defun broadcast (station)
    "Starts up the given radio station to broadcast.")
  (defmacro define-station ((name frequency) &body body)
    "Defines a new radio station on the given frequency."))

This will generate you an interface with the specified stub forms. Calling any of these functions before an implementation actually implements the interface will result in an error. In the back, DEFINE-INTERFACE creates a module through DEFINE-MODULE and then expands the specified components.

If a module wants to implement an interface, it can define this in the :IMPLEMENTS module-option. It will then be automatically set up as the current implementation. Otherwise you can also directly do (SETF (IMPLEMENTATION :interface) :my-module). If an interface is already implemented by another module, a condition is raised with restarts to either abort, delete the old module or override it. After an implementation is set, TEST-INTERFACE is called to check for compliance. Compliance checks must be implemented by the respective components and may or may not be sufficient to test for true interface compliance. If an implementing module gets deleted, RESET-INTERFACE is called, which returns it to its old state with error-ing stub definitions.

Defining the actual components of the interface in your module works just like writing any other function or whatever part it is in effect. You may want to use the provided I-* macros for the standard components though to make the intent more visible.

Adding new components to use in interface definition happens through DEFINE-COMPONENT-EXPANDER. This should evaluate to whatever stub forms you need, optimally resulting in an error if a user tries to access it without a conforming implementation in place. Additionally you will most likely want to add a DEFINE-COMPONENT-TESTER for each of your components. This is a simple function definition that is called whenever TEST-INTERFACE is invoked and should return two values, a boolean whether the test failed or not and a string that explains the reason for failure or passing. TEST-INTERFACE will convert this into warnings. It is discouraged to signal errors as this would prevent other components from being tested too and may interfere while developing an implementation.

For a super small sample use of an interface, have a look at interfaces-test-implementation.asd, interfaces-test-interface.lisp and interfaces-test-implementation.lisp.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 modularize-interfaces

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://Shinmera.github.io/modularize-interfaces/

Source Control

(:git "https://github.com/shinmera/modularize-interfaces.git")

Bug Tracker

https://github.com/Shinmera/modularize-interfaces/issues

License

zlib

Description

Programmatical interfaces extension for Modularize

Version

0.9.3

Dependencies

• modularize
• trivial-indent
• trivial-arguments
• lambda-fiddle

Source

modularize-interfaces.asd (file)

Components

• package.lisp (file)
• toolkit.lisp (file)
• component.lisp (file)
• standard-components.lisp (file)
• interface.lisp (file)
• module.lisp (file)
• indent.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 modularize-interfaces.asd

Location

modularize-interfaces.asd

Systems

modularize-interfaces (system)

3.1.2 modularize-interfaces/package.lisp

Parent

modularize-interfaces (system)

Location

package.lisp

Packages

modularize-interfaces

3.1.3 modularize-interfaces/toolkit.lisp

Dependency

package.lisp (file)

Parent

modularize-interfaces (system)

Location

toolkit.lisp

Exported Definitions

• defmacro* (macro)
• defmethod* (macro)
• defun* (macro)

Internal Definitions

• *redefine* (special variable)
• function-lambda-matches (function)
• intern-function-name (function)
• make-keyword (function)
• with-muffled-warnings (macro)

3.1.4 modularize-interfaces/component.lisp

Dependency

toolkit.lisp (file)

Parent

modularize-interfaces (system)

Location

component.lisp

Exported Definitions

• component-alias (function)
• (setf component-alias) (function)
• define-component-expander (macro)
• define-component-tester (macro)
• expand-component (generic function)

Internal Definitions

• *component-alias* (special variable)
• component (method)
• (setf component) (method)
• component-test-failed (condition)
• expand-components (macro)
• requested (method)
• (setf requested) (method)
• result (method)
• (setf result) (method)
• test-component (generic function)
• test-component (method)
• test-components (function)

3.1.5 modularize-interfaces/standard-components.lisp

Dependency

component.lisp (file)

Parent

modularize-interfaces (system)

Location

standard-components.lisp

Exported Definitions

• defimpl (macro)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• i-defmacro (macro)
• i-defmethod (macro)
• i-defun (macro)

Internal Definitions

• check-function-name (function)
• emit-class-def (function)
• test-component (method)
• test-component (method)

3.1.6 modularize-interfaces/interface.lisp

Dependency

standard-components.lisp (file)

Parent

modularize-interfaces (system)

Location

interface.lisp

Exported Definitions

• define-interface (macro)
• define-interface-extension (macro)
• generate-interface-stub (function)
• implementation (function)
• (setf implementation) (function)
• interface (function)
• interface-already-implemented (condition)
• interface-not-found (condition)
• interface-p (function)
• print-interface-stub (function)
• reset-interface (function)
• test-interface (function)

Internal Definitions

• current (method)
• expand-interface (macro)
• new (method)
• requested (method)
• requested (method)

3.1.7 modularize-interfaces/module.lisp

Dependency

interface.lisp (file)

Parent

modularize-interfaces (system)

Location

module.lisp

Exported Definitions

implements (function)

3.1.8 modularize-interfaces/indent.lisp

Dependency

module.lisp (file)

Parent

modularize-interfaces (system)

Location

indent.lisp

4 Packages

Packages are listed by definition order.

4.1 modularize-interfaces

Source

package.lisp (file)

Nicknames

• interfaces
• org.shirakumo.radiance.lib.modularize.interfaces

Use List

• lambda-fiddle
• trivial-arguments
• trivial-indent
• modularize
• common-lisp

Exported Definitions

• component-alias (function)
• (setf component-alias) (function)
• defimpl (macro)
• define-component-expander (macro)
• define-component-tester (macro)
• define-interface (macro)
• define-interface-extension (macro)
• defmacro* (macro)
• defmethod* (macro)
• defun* (macro)
• expand-component (generic function)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• expand-component (method)
• generate-interface-stub (function)
• i-defmacro (macro)
• i-defmethod (macro)
• i-defun (macro)
• implementation (function)
• (setf implementation) (function)
• implements (function)
• interface (function)
• interface-already-implemented (condition)
• interface-not-found (condition)
• interface-p (function)
• print-interface-stub (function)
• reset-interface (function)
• test-interface (function)

Internal Definitions

• *component-alias* (special variable)
• *redefine* (special variable)
• check-function-name (function)
• component (generic function)
• component (method)
• (setf component) (method)
• (setf component) (generic function)
• component-test-failed (condition)
• current (generic function)
• current (method)
• emit-class-def (function)
• expand-components (macro)
• expand-interface (macro)
• function-lambda-matches (function)
• intern-function-name (function)
• make-keyword (function)
• new (generic function)
• new (method)
• requested (generic function)
• requested (method)
• requested (method)
• requested (method)
• (setf requested) (method)
• (setf requested) (generic function)
• result (generic function)
• result (method)
• (setf result) (method)
• (setf result) (generic function)
• test-component (generic function)
• test-component (method)
• test-component (method)
• test-component (method)
• test-components (function)
• with-muffled-warnings (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Macros

Macro: defimpl NAME &rest ARGS

Expands to I-DEFMACRO, I-DEFMETHOD or I-DEFUN depending on what kind of symbol it names.

Package

modularize-interfaces

Source

standard-components.lisp (file)

Macro: define-component-expander NAME (INTERFACE &rest ARGUMENTS) &body BODY

Defines a new component expander for interface definitions.

The NAME can be a list of names that will be aliased to the first one. All names will be turned into keywords to allow for differing naming schemes in the component definitions. INTERFACE should be a symbol to which the interface package is bound. ARGUMENTS is the lambda-list used to deconstruct the arguments of the component definition.

Package

modularize-interfaces

Source

component.lisp (file)

Macro: define-component-tester NAME (INTERFACE &rest ARGUMENTS) &body BODY

Defines a new testing method for a component type.

The structure of this macro is the same as for DEFINE-COMPONENT.

Package

modularize-interfaces

Source

component.lisp (file)

Macro: define-interface NAME &body COMPONENTS

Defines a new interface.

This defines a new module with the given name and nicks, as well
as a fully qualified interface identifier which is the name prefixed by MODULARIZE.INT. . It then calls EXPAND-INTERFACE on the new module and finally expands the component definitions as per EXPAND-COMPONENTS.

Package

modularize-interfaces

Source

interface.lisp (file)

Macro: define-interface-extension NAME &body COMPONENTS

Currently not implemented.

Package

modularize-interfaces

Source

interface.lisp (file)

Macro: defmacro* NAME ARGS &body BODY

Expands to a conditional macro definition that only happens if either *REDEFINE* is T or the macro has not yet been defined.

Package

modularize-interfaces

Source

toolkit.lisp (file)

Macro: defmethod* NAME &rest ARGS

Expands to a conditional method definition that only happens if either *REDEFINE* is T or the method has not yet been defined.

Package

modularize-interfaces

Source

toolkit.lisp (file)

Macro: defun* NAME ARGS &body BODY

Expands to a conditional function definition that only happens if either *REDEFINE* is T or the function has not yet been defined.

Package

modularize-interfaces

Source

toolkit.lisp (file)

Macro: i-defmacro NAME ARGS &body BODY

Expands to an interface macro definition.

Package

modularize-interfaces

Source

standard-components.lisp (file)

Macro: i-defmethod NAME &rest ARGS

Expands to an interface method definition.

Package

modularize-interfaces

Source

standard-components.lisp (file)

Macro: i-defun NAME ARGS &body BODY

Expands to an interface function definition.

Package

modularize-interfaces

Source

standard-components.lisp (file)

5.1.2 Functions

Function: component-alias ALIAS

Returns the actual component name the given alias points to or itself if it is not resolved..

Package

modularize-interfaces

Source

component.lisp (file)

Writer

(setf component-alias) (function)

Function: (setf component-alias) COMPONENT ALIAS

Sets a new alias for the given component-name.

Package

modularize-interfaces

Source

component.lisp (file)

Reader

component-alias (function)

Function: generate-interface-stub INTERFACE &optional PACKAGE

Generates a stub for the INTERFACE that you can use as an implementation starting point. Symbols are interned into PACKAGE where appropriate.

Package

modularize-interfaces

Source

interface.lisp (file)

Function: implementation INTERFACE

Returns the currently active implementation of the interface.

Package

modularize-interfaces

Source

interface.lisp (file)

Writer

(setf implementation) (function)

Function: (setf implementation) IMPLEMENTATION INTERFACE

Attempts to set the implementation of an interface.
Interfaces can only be implemented by modules and if a different module already implements the interface a condition is signalled. The following restarts are available:
DELETE Deletes the old implementation through DELETE-MODULE. OVERRIDE Overrides the implementation and leaves the old module. ABORT Aborts the setting of the implementation completely.

If the implementation setting was successful, TEST-INTERFACE is called. If the implementation is set to NIL, RESET-INTERFACE is called.

Package

modularize-interfaces

Source

interface.lisp (file)

Reader

implementation (function)

Function: implements MODULE

Returns a list of interfaces this module implements.

Package

modularize-interfaces

Source

module.lisp (file)

Function: interface OBJECT

Returns the interface package module as identified by the object. See MODULE for more.

Package

modularize-interfaces

Source

interface.lisp (file)

Function: interface-p OBJECT

Returns T if the passed object is or names an interface, otherwise NIL.

Package

modularize-interfaces

Source

interface.lisp (file)

Function: print-interface-stub INTERFACE &optional PACKAGE

Print the stub of GENERATE-INTERFACE-STUB in a way that is easily copy-pastable.

Package

modularize-interfaces

Source

interface.lisp (file)

Function: reset-interface INTERFACE

Resets the interface by redefining it with stubs as per its component definitions.

Package

modularize-interfaces

Source

interface.lisp (file)

Function: test-interface INTERFACE

Tests the interface for definition conformity. See TEST-COMPONENTS.

Package

modularize-interfaces

Source

interface.lisp (file)

5.1.3 Generic functions

Generic Function: expand-component TYPE ARGS &key INTERFACE &allow-other-keys

Generic function used to expand components into their proper forms.

Package

modularize-interfaces

Source

component.lisp (file)

Methods

Method: expand-component (TYPE1 (eql variable)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: expand-component (TYPE1 (eql method)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: expand-component (TYPE1 (eql generic)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: expand-component (TYPE1 (eql class)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: expand-component (TYPE1 (eql condition)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: expand-component (TYPE1 (eql macro)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: expand-component (TYPE1 (eql function)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: expand-component (TYPE1 (eql type)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

5.1.4 Conditions

Condition: interface-already-implemented ()

Condition signalled if an interface is already implemented by a different module than was attempted to register as an implementation.

Package

modularize-interfaces

Source

interface.lisp (file)

Direct superclasses

error (condition)

Direct methods

• new (method)
• current (method)
• requested (method)

Direct slots

Slot: %requested

Initargs

:interface

Initform

(quote (error "interface required."))

Readers

requested (generic function)

Slot: %current

Initargs

:current

Initform

(quote (error "current required."))

Readers

current (generic function)

Slot: %new

Initargs

:new

Initform

(quote (error "new required."))

Readers

new (generic function)

Condition: interface-not-found ()

Condition signalled if an interface was requested but could not be found.

Package

modularize-interfaces

Source

interface.lisp (file)

Direct superclasses

error (condition)

Direct methods

requested (method)

Direct slots

Slot: %requested

Initargs

:requested

Initform

(quote (error "requested required."))

Readers

requested (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *component-alias*

Table of aliases for component names.

Package

modularize-interfaces

Source

component.lisp (file)

Special Variable: *redefine*

Special variable that dictates whether already defined functions should be redefined by defun*, defmacro*, defmethod*.

Package

modularize-interfaces

Source

toolkit.lisp (file)

5.2.2 Macros

Macro: expand-components INTERFACE &body COMPONENT-DEFS

Expands the component definitions for the INTERFACE to their proper forms.

Package

modularize-interfaces

Source

component.lisp (file)

Macro: expand-interface INTERFACE

Expands the given interface into its basic form.

Package

modularize-interfaces

Source

interface.lisp (file)

Macro: with-muffled-warnings &body BODY

Calls the body with redefinition warnings muffled.

Currently only implemented on: SBCL

Package

modularize-interfaces

Source

toolkit.lisp (file)

5.2.3 Functions

Function: check-function-name NAME

Package

modularize-interfaces

Source

standard-components.lisp (file)

Function: emit-class-def MACRO NAME SUPER SLOTS OPTIONS

Package

modularize-interfaces

Source

standard-components.lisp (file)

Function: function-lambda-matches FUNCTION LAMBDA-LIST

Returns T if the function matches the lambda-list in arguments.
As a secondary value it returns a reason as to why it may have failed the test.

Package

modularize-interfaces

Source

toolkit.lisp (file)

Function: intern-function-name PACKAGE NAME

Interns the function name into the package. This has special handling for (SETF NAME).

Package

modularize-interfaces

Source

toolkit.lisp (file)

Function: make-keyword NAME

Returns the matching keyword for the NAME.

Package

modularize-interfaces

Source

toolkit.lisp (file)

Function: test-components INTERFACE COMPONENT-DEFS

Tests the interface against the component-definitions to see if it matches. That is to say, the passed component-defs tell what the interface should look like and this function will test if the defined components match this definition
to a certain extent.

How well and thorough the tests are depends on the component itself and its test function. Certain components may even not provide any tests at all.

Package

modularize-interfaces

Source

component.lisp (file)

5.2.4 Generic functions

Generic Function: component CONDITION

Generic Function: (setf component) NEW-VALUE CONDITION

Package

modularize-interfaces

Methods

Method: component (CONDITION component-test-failed)

Method: (setf component) NEW-VALUE (CONDITION component-test-failed)

Source

component.lisp (file)

Generic Function: current CONDITION

Package

modularize-interfaces

Methods

Method: current (CONDITION interface-already-implemented)

Source

interface.lisp (file)

Generic Function: new CONDITION

Package

modularize-interfaces

Methods

Method: new (CONDITION interface-already-implemented)

Source

interface.lisp (file)

Generic Function: requested CONDITION

Generic Function: (setf requested) NEW-VALUE CONDITION

Package

modularize-interfaces

Methods

Method: requested (CONDITION interface-already-implemented)

Source

interface.lisp (file)

Method: requested (CONDITION interface-not-found)

Source

interface.lisp (file)

Method: requested (CONDITION component-test-failed)

Method: (setf requested) NEW-VALUE (CONDITION component-test-failed)

Source

component.lisp (file)

Generic Function: result CONDITION

Generic Function: (setf result) NEW-VALUE CONDITION

Package

modularize-interfaces

Methods

Method: result (CONDITION component-test-failed)

Method: (setf result) NEW-VALUE (CONDITION component-test-failed)

Source

component.lisp (file)

Generic Function: test-component TYPE ARGS &key INTERFACE &allow-other-keys

Tests a component type for validity.

Package

modularize-interfaces

Source

component.lisp (file)

Methods

Method: test-component (TYPE1 (eql macro)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: test-component (TYPE1 (eql function)) ARGS0 &key INTERFACE

Source

standard-components.lisp (file)

Method: test-component TYPE ARGS &key INTERFACE

5.2.5 Conditions

Condition: component-test-failed ()

Condition signalled when the test of an interface component failed for some reason.

Package

modularize-interfaces

Source

component.lisp (file)

Direct superclasses

warning (condition)

Direct methods

• result (method)
• result (method)
• component (method)
• component (method)
• requested (method)
• requested (method)

Direct slots

Slot: %requested

Initargs

:interface

Initform

(quote (error "interface required."))

Readers

requested (generic function)

Writers

(setf requested) (generic function)

Slot: %component

Initargs

:component

Initform

(quote (error "component required."))

Readers

component (generic function)

Writers

(setf component) (generic function)

Slot: %result

Initargs

:result

Initform

(quote nil)

Readers

result (generic function)

Writers

(setf result) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types