Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
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.
• Introduction | What modularize-interfaces is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
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.
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.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The modularize-interfaces system |
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(:git "https://github.com/shinmera/modularize-interfaces.git")
zlib
Programmatical interfaces extension for Modularize
0.9.3
modularize-interfaces.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
Next: The modularize-interfaces/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
modularize-interfaces.asd
modularize-interfaces (system)
Next: The modularize-interfaces/toolkit․lisp file, Previous: The modularize-interfaces․asd file, Up: Lisp files [Contents][Index]
modularize-interfaces (system)
package.lisp
Next: The modularize-interfaces/component․lisp file, Previous: The modularize-interfaces/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
modularize-interfaces (system)
toolkit.lisp
Next: The modularize-interfaces/standard-components․lisp file, Previous: The modularize-interfaces/toolkit․lisp file, Up: Lisp files [Contents][Index]
toolkit.lisp (file)
modularize-interfaces (system)
component.lisp
Next: The modularize-interfaces/interface․lisp file, Previous: The modularize-interfaces/component․lisp file, Up: Lisp files [Contents][Index]
component.lisp (file)
modularize-interfaces (system)
standard-components.lisp
Next: The modularize-interfaces/module․lisp file, Previous: The modularize-interfaces/standard-components․lisp file, Up: Lisp files [Contents][Index]
standard-components.lisp (file)
modularize-interfaces (system)
interface.lisp
Next: The modularize-interfaces/indent․lisp file, Previous: The modularize-interfaces/interface․lisp file, Up: Lisp files [Contents][Index]
interface.lisp (file)
modularize-interfaces (system)
module.lisp
implements (function)
Previous: The modularize-interfaces/module․lisp file, Up: Lisp files [Contents][Index]
module.lisp (file)
modularize-interfaces (system)
indent.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The modularize-interfaces package |
package.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros | ||
• Exported functions | ||
• Exported generic functions | ||
• Exported conditions |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Expands to I-DEFMACRO, I-DEFMETHOD or I-DEFUN depending on what kind of symbol it names.
standard-components.lisp (file)
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.
component.lisp (file)
Defines a new testing method for a component type.
The structure of this macro is the same as for DEFINE-COMPONENT.
component.lisp (file)
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.
interface.lisp (file)
Currently not implemented.
interface.lisp (file)
Expands to a conditional macro definition that only happens if either *REDEFINE* is T or the macro has not yet been defined.
toolkit.lisp (file)
Expands to a conditional method definition that only happens if either *REDEFINE* is T or the method has not yet been defined.
toolkit.lisp (file)
Expands to a conditional function definition that only happens if either *REDEFINE* is T or the function has not yet been defined.
toolkit.lisp (file)
Expands to an interface macro definition.
standard-components.lisp (file)
Expands to an interface method definition.
standard-components.lisp (file)
Expands to an interface function definition.
standard-components.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Returns the actual component name the given alias points to or itself if it is not resolved..
component.lisp (file)
(setf component-alias) (function)
Sets a new alias for the given component-name.
component.lisp (file)
component-alias (function)
Generates a stub for the INTERFACE that you can use as an implementation starting point. Symbols are interned into PACKAGE where appropriate.
interface.lisp (file)
Returns the currently active implementation of the interface.
interface.lisp (file)
(setf implementation) (function)
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.
interface.lisp (file)
implementation (function)
Returns a list of interfaces this module implements.
module.lisp (file)
Returns the interface package module as identified by the object. See MODULE for more.
interface.lisp (file)
Returns T if the passed object is or names an interface, otherwise NIL.
interface.lisp (file)
Print the stub of GENERATE-INTERFACE-STUB in a way that is easily copy-pastable.
interface.lisp (file)
Resets the interface by redefining it with stubs as per its component definitions.
interface.lisp (file)
Tests the interface for definition conformity. See TEST-COMPONENTS.
interface.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Generic function used to expand components into their proper forms.
component.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Condition signalled if an interface is already implemented by a different module than was attempted to register as an implementation.
interface.lisp (file)
error (condition)
:interface
(quote (error "interface required."))
requested (generic function)
:current
(quote (error "current required."))
current (generic function)
:new
(quote (error "new required."))
new (generic function)
Condition signalled if an interface was requested but could not be found.
interface.lisp (file)
error (condition)
requested (method)
:requested
(quote (error "requested required."))
requested (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal special variables | ||
• Internal macros | ||
• Internal functions | ||
• Internal generic functions | ||
• Internal conditions |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Table of aliases for component names.
component.lisp (file)
Special variable that dictates whether already defined functions should be redefined by defun*, defmacro*, defmethod*.
toolkit.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Expands the component definitions for the INTERFACE to their proper forms.
component.lisp (file)
Expands the given interface into its basic form.
interface.lisp (file)
Calls the body with redefinition warnings muffled.
Currently only implemented on: SBCL
toolkit.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
standard-components.lisp (file)
standard-components.lisp (file)
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.
toolkit.lisp (file)
Interns the function name into the package. This has special handling for (SETF NAME).
toolkit.lisp (file)
Returns the matching keyword for the NAME.
toolkit.lisp (file)
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.
component.lisp (file)
Next: Internal conditions, Previous: Internal functions, Up: Internal definitions [Contents][Index]
component.lisp (file)
interface.lisp (file)
interface.lisp (file)
interface.lisp (file)
interface.lisp (file)
component.lisp (file)
component.lisp (file)
Tests a component type for validity.
component.lisp (file)
standard-components.lisp (file)
standard-components.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
Condition signalled when the test of an interface component failed for some reason.
component.lisp (file)
warning (condition)
:interface
(quote (error "interface required."))
requested (generic function)
(setf requested) (generic function)
:component
(quote (error "component required."))
component (generic function)
(setf component) (generic function)
:result
(quote nil)
result (generic function)
(setf result) (generic function)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L M |
---|
Jump to: | F L M |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
C D E F G I M N P R T W |
---|
Jump to: | (
C D E F G I M N P R T W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | %
*
S |
---|
Jump to: | %
*
S |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C I M P S |
---|
Jump to: | C I M P S |
---|