Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
The descriptions Reference Manual
This is the descriptions Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:26:27 2022 GMT+0.
Table of Contents
Next: Systems, Previous: The descriptions Reference Manual, Up: The descriptions Reference Manual [Contents][Index]
1 Introduction
{} descriptions
Overview
{} descriptions is a meta level descriptions library for Common Lisp.
It is inspired by Smalltalk Maggrite, as well as Lisp On Lines.
Documentation
Install
Download the source code from https://github.com/mmontone/descriptions and point .asd system definition files from ./sbcl/system (ln -s <system definition file path>) and then evaluate:
(require :descriptions)
from your lisp listener.
You will also need to satisfy these system dependencies:
alexandriaanaphorasheeplecxmlandcl-jsonfor the serialization modulecl-ppcrefor the validation module
The easiest way of installing those packages is via Quicklisp.
This library is under the MIT licence.
Getting started
{} descriptions is a very dynamic meta-description library similar to Smalltalk Maggrite and Lisp On Lines. Meta description of the application's domain model is done defining descriptions for the different aspects is desired to represent. This helps automate the generation of different views, editors, serialization schemas, validation procedures for the domain model objects and to avoid very repetitive and error-prone work when those objects change its shape.
Domain model meta descriptions consist of the definition of description objects for its different aspects (viewing, editing, validation, persistence, serialization, etc). Description objects are a collections of attributes, can inherit from each other, and are composable.
Let's go through an example to see how this works.
Say we have a person model object:
(defclass person ()
((id :accessor id)
(username :initarg :username
:accessor username)
(fullname :initarg :fullname
:accessor fullname)
(email :initarg :email
:accessor email)
(password :initarg :password
:accessor password)))
We would like to print instances of that model on the screen. So first we define a {person} description that just describes which attributes person model objecs possess and their "types".
(define-description {person} ()
((username =>string
:reader #'username
:writer #'(setf username))
(email =>email
:reader #'email
:writer #'(setf email))
(fullname =>string
:reader #'fullname
:writer #'(setf fullname))
(password =>password
:reader #'password
:writer #'(setf password)))
:documentation "A person description")
Descriptions names are enclosed between brackets { } as a naming convention. Also, notice that the attribute types (=>string, =>email, =>password), begin with =>. Attributes types begin with => as a naming convention.
Now we can use the information on the attributes of a person, and its types, to print a description of a person on the screen. To do that we define a new description that indicates which person slots we would like to print, and in which order.
(define-description {person-view} ({person})
((fullname =>view :label "Full name")
(username =>view)
(email =>view :label "E-mail")
(password =>view :view nil)))
We can see that the password is disabled for viewing, that "Full name" and "E-mail" are used for labels, and that fullname, username, email and password are to be displayed in that order.
We can see that in action:
(display-object (make-instance 'person :username "mmontone"
:email "mariano@copyleft.no"
:password "lalala"
:fullname "Mariano Montone")
{person-view})
prints:
Full name: "Mariano Montone"
Username: "mmontone"
E-mail: "mariano@copyleft.no"
Descriptions composition
Descriptions can be composed using inheritance. Multiple inheritance is supported and they are implemented on top of a prototype based object system, so they can be composed in run time on the fly.
Attributes composition
When inheriting from other descriptions, attributes with the same name are collapsed into one containing all the attribute properties.
For example, consider the basic {person} description we had before. We can ask for an attribute name and type, but asking if that attribute is going to be displayed throws an error, because that attribute property does not belong to the {person} description, but the {person-view} description we saw before.
{}> (attribute-name (get-attribute {person} 'fullname))
FULLNAME
{}> (attribute-type (get-attribute {person} 'fullname))
#<Object =>STRING {1005A0A0A3}>
{}> (attribute-view (get-attribute {person} 'fullname))
;; Error
But if we ask the same to the {person-view} description, we can access to all the attributes properties.
{}> (attribute-name (get-attribute {person-view} 'fullname))
FULLNAME
{}> (attribute-type (get-attribute {person-view} 'fullname))
#<Object =>STRING {1005A0A0A3}>
{}> (attribute-view (get-attribute {person-view} 'fullname))
T
This makes the approach layered, with each description describing different aspects of the same model and extending other more basic descriptions.
Descriptions composition
As we mentioned before, descriptions can be composed on the fly thanks to the prototype object system the library is implemented in.
For example, we can create new descriptions with the make-description function, passing the descriptions we want to compose as parents:
(let ((description (make-description :parents
(list {person-validation} {person-repl-editing}))))
(let ((person (make-instance 'person)))
(edit-object person description)
(validate-object person description)
(describe person)))
A prettier way of doing it is using the description name as a function:
(let ((description ({person-validation} {person-repl-editing})))
(let ((person (make-instance 'person)))
(edit-object person description)
(validate-object person description)
(describe person)))
We can also choose not to compose descriptions, but work with them separately on the different aspects of the model objects:
(let ((person (make-instance 'person)))
(edit-object person {person-repl-editing})
(validate-object person {person-validation})
(describe person)
(print
(with-output-to-string (s)
(serialize-object person {person-serialization} s))))
Implementation
{} descriptions is implemented as a thin layer over Sheeple prototypes. As a consequence, descriptions and its attributes can be easily be combined in run time.
Why not just use metaclasses instead?
It is not possible to achieve quite the same with metaclasses. They do not allow to keep the metamodel independent of the actual implementation of the class. It should be possible to exchange descriptions on the fly, and even use multiple descriptions at the same time for the same underlying domain object.
Metaclasses have their own specific power though, and may be good to use them in combination with descriptions.
References
- http://code.google.com/p/magritte-metamodel/
- http://www.cliki.net/lisp-on-lines
- http://common-lisp.net/project/lisp-on-lines/repo/lisp-on-lines/doc/manual.html
- http://scg.unibe.ch/archive/papers/Reng07aMagritte.pdf
Next: Modules, Previous: Introduction, Up: The descriptions Reference Manual [Contents][Index]
2 Systems
The main system appears first, followed by any subsystem dependency.
Next: Files, Previous: Systems, Up: The descriptions Reference Manual [Contents][Index]
3 Modules
Modules are listed depth-first from the system components tree.
3.1 descriptions/src
- Source
- Parent Component
descriptions (system).
- Child Components
- package.lisp (file).
- descriptions.lisp (file).
- mop.lisp (file).
Next: Packages, Previous: Modules, Up: The descriptions Reference Manual [Contents][Index]
4 Files
Files are sorted by type and then listed depth-first from the systems components trees.
4.1 Lisp
- descriptions/descriptions.asd
- descriptions/src/package.lisp
- descriptions/src/descriptions.lisp
- descriptions/src/mop.lisp
Next: descriptions/src/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
4.1.1 descriptions/descriptions.asd
- Source
- Parent Component
descriptions (system).
- ASDF Systems
Next: descriptions/src/descriptions.lisp, Previous: descriptions/descriptions.asd, Up: Lisp [Contents][Index]
4.1.2 descriptions/src/package.lisp
- Source
- Parent Component
src (module).
- Packages
Next: descriptions/src/mop.lisp, Previous: descriptions/src/package.lisp, Up: Lisp [Contents][Index]
4.1.3 descriptions/src/descriptions.lisp
- Dependency
package.lisp (file).
- Source
- Parent Component
src (module).
- Public Interface
- => (macro).
- =>boolean (function).
- =>email (function).
- =>integer (function).
- =>keyword (function).
- =>multiple-option (function).
- =>password (function).
- =>single-option (function).
- =>string (function).
- =>symbol (function).
- =>to-many-relation (function).
- =>to-one-relation (function).
- =>valued (function).
- =>view (function).
- add-attribute (function).
- attribute-documentation (function).
- attribute-properties (function).
- define-attribute (macro).
- define-description (macro).
- description-attributes (function).
- display-object (function).
- get-attribute (function).
- make-attribute (function).
- make-description (function).
- undefinedp (function).
- with-described-object (macro).
- with-description-attributes (macro).
- Internals
- %undefined% (special variable).
- +undefined+ (symbol macro).
- =>option (function).
- =>reference (function).
- =>relation (function).
- copy-undefined (function).
- make-undefined (function).
- symbol->keyword (function).
- undefined (structure).
- undefined-p (function).
Previous: descriptions/src/descriptions.lisp, Up: Lisp [Contents][Index]
4.1.4 descriptions/src/mop.lisp
- Dependency
descriptions.lisp (file).
- Source
- Parent Component
src (module).
- Public Interface
- compute-effective-slot-definition (method).
- default-description (reader method).
- default-description (reader method).
- (setf default-description) (writer method).
- (setf default-description) (writer method).
- define-described-class (macro).
- described-object (class).
- described-object-class (class).
- direct-slot-definition-class (method).
- effective-slot-definition-class (method).
- shared-initialize (method).
- shared-initialize (method).
- validate-superclass (method).
- Internals
- default-description-name (reader method).
- (setf default-description-name) (writer method).
- described-object-direct-slot-definition (class).
- described-object-effective-slot-definition (class).
- described-object-slot-mixin (class).
- described-p (method).
- described-p (reader method).
- (setf described-p) (writer method).
- described-slot-p (generic function).
- parent-descriptions (reader method).
- (setf parent-descriptions) (writer method).
- plist-keys (function).
- plist-values (function).
- slot-attribute (method).
- slot-attribute (reader method).
- (setf slot-attribute) (writer method).
- slot-attribute-name (method).
Next: Definitions, Previous: Files, Up: The descriptions Reference Manual [Contents][Index]
5 Packages
Packages are listed by definition order.
5.1 descriptions
- Source
- Nicknames
- {}
- desc
- Use List
- alexandria.
- anaphora.
- common-lisp.
- sheeple.
- Public Interface
- => (special variable).
- => (macro).
- =>boolean (special variable).
- =>boolean (function).
- =>email (special variable).
- =>email (function).
- =>integer (special variable).
- =>integer (function).
- =>keyword (special variable).
- =>keyword (function).
- =>multiple-option (special variable).
- =>multiple-option (function).
- =>password (special variable).
- =>password (function).
- =>single-option (special variable).
- =>single-option (function).
- =>string (special variable).
- =>string (function).
- =>symbol (special variable).
- =>symbol (function).
- =>to-many-relation (special variable).
- =>to-many-relation (function).
- =>to-one-relation (special variable).
- =>to-one-relation (function).
- =>valued (special variable).
- =>valued (function).
- =>view (special variable).
- =>view (function).
- add-attribute (function).
- attribute-documentation (function).
- attribute-properties (function).
- default-description (generic reader).
- (setf default-description) (generic writer).
- define-attribute (macro).
- define-described-class (macro).
- define-description (macro).
- described-object (class).
- described-object-class (class).
- description-attributes (function).
- display-object (function).
- get-attribute (function).
- make-attribute (function).
- make-description (function).
- undefinedp (function).
- with-described-object (macro).
- with-description-attributes (macro).
- {description} (special variable).
- Internals
- %undefined% (special variable).
- +undefined+ (symbol macro).
- =>option (special variable).
- =>option (function).
- =>reference (special variable).
- =>reference (function).
- =>relation (special variable).
- =>relation (function).
- copy-undefined (function).
- default-description-name (generic reader).
- (setf default-description-name) (generic writer).
- described-object-direct-slot-definition (class).
- described-object-effective-slot-definition (class).
- described-object-slot-mixin (class).
- described-p (generic function).
- (setf described-p) (generic writer).
- described-slot-p (generic function).
- make-undefined (function).
- parent-descriptions (generic reader).
- (setf parent-descriptions) (generic writer).
- plist-keys (function).
- plist-values (function).
- slot-attribute (generic function).
- (setf slot-attribute) (generic writer).
- slot-attribute-name (generic function).
- symbol->keyword (function).
- undefined (structure).
- undefined-p (function).
Next: Indexes, Previous: Packages, Up: The descriptions Reference Manual [Contents][Index]
6 Definitions
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
6.1 Public Interface
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
6.1.1 Special variables
- Special Variable: => ¶
-
- Package
- Special Variable: =>boolean ¶
-
Boolean attribute
- Package
- Special Variable: =>email ¶
-
Email attribute
- Package
- Special Variable: =>integer ¶
-
Integer attribute
- Package
- Special Variable: =>keyword ¶
-
Keyword attribute
- Package
- Special Variable: =>multiple-option ¶
-
- Package
- Special Variable: =>password ¶
-
Password attribute
- Package
- Special Variable: =>single-option ¶
-
- Package
- Special Variable: =>string ¶
-
String attribute
- Package
- Special Variable: =>symbol ¶
-
Symbol attribute
- Package
- Special Variable: =>to-many-relation ¶
-
- Package
- Special Variable: =>to-one-relation ¶
-
- Package
- Special Variable: =>valued ¶
-
- Package
- Special Variable: =>view ¶
-
- Package
- Special Variable: {description} ¶
-
- Package
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
6.1.2 Macros
- Macro: => (type-spec &rest property-values) ¶
-
Attribute builder macro
- Package
- Source
- Macro: define-attribute (name parents properties &rest options) ¶
-
Define an attribute type
:param name: the attribute type name.
:param parents: the attribute type parents. :param properties: list of properties.
:param options: options, like :documentation, etc- Package
- Source
- Macro: define-described-class (name direct-superclasses direct-slots &rest options) ¶
-
- Package
- Source
- Macro: define-description (name parents attributes &rest options) ¶
-
Define a new description
- Package
- Source
- Macro: with-described-object (attributes (object &optional description) &body body) ¶
-
- Package
- Source
- Macro: with-description-attributes (attributes description &body body) ¶
-
Run body with description attributes bound
- Package
- Source
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
6.1.3 Ordinary functions
- Function: =>boolean (&rest property-values) ¶
-
Create a =>BOOLEAN attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>email (&rest property-values) ¶
-
Create a =>EMAIL attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>integer (&rest property-values) ¶
-
Create a =>INTEGER attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>keyword (&rest property-values) ¶
-
Create a =>KEYWORD attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>multiple-option (&rest property-values) ¶
-
Create a =>MULTIPLE-OPTION attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>password (&rest property-values) ¶
-
Create a =>PASSWORD attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>single-option (&rest property-values) ¶
-
Create a =>SINGLE-OPTION attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>string (&rest property-values) ¶
-
Create a =>STRING attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>symbol (&rest property-values) ¶
-
Create a =>SYMBOL attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>to-many-relation (&rest property-values) ¶
-
Create a =>TO-MANY-RELATION attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>to-one-relation (&rest property-values) ¶
-
Create a =>TO-ONE-RELATION attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>valued (&rest property-values) ¶
-
Create a =>VALUED attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>view (&rest property-values) ¶
-
Create a =>VIEW attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: add-attribute (description attribute &key reader writer accessor) ¶
-
- Package
- Source
- Function: attribute-documentation (attribute) ¶
-
- Package
- Source
- Function: attribute-properties (attribute) ¶
-
- Package
- Source
- Function: description-attributes (description) ¶
-
Obtain a description attributes. :param description: the description.
- Package
- Source
- Function: display-object (object &optional description stream) ¶
-
- Package
- Source
- Function: get-attribute (description attribute-name) ¶
-
- Package
- Source
- Function: make-attribute (attribute-type &rest property-values) ¶
-
Create an attribute.
:param attribute-type: The attribute type :property-values: A plist of attribute properties values
- Package
- Source
- Function: make-description (&key parents attributes) ¶
-
- Package
- Source
- Function: undefinedp (value) ¶
-
- Package
- Source
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
6.1.4 Generic functions
- Generic Reader: default-description (object) ¶
-
- Package
- Methods
- Reader Method: default-description ((described-object-class described-object-class)) ¶
-
automatically generated reader method
- Source
- Target Slot
- Reader Method: default-description ((described-object described-object)) ¶
-
automatically generated reader method
- Source
- Target Slot
- Generic Writer: (setf default-description) (object) ¶
-
- Package
- Methods
- Writer Method: (setf default-description) ((described-object-class described-object-class)) ¶
-
automatically generated writer method
- Source
- Target Slot
- Writer Method: (setf default-description) ((described-object described-object)) ¶
-
automatically generated writer method
- Source
- Target Slot
Next: Classes, Previous: Generic functions, Up: Public Interface [Contents][Index]
6.1.5 Standalone methods
- Method: compute-effective-slot-definition ((class described-object-class) name direct-slots) ¶
-
- Package
sb-mop.
- Source
- Method: direct-slot-definition-class ((class described-object-class) &rest initargs) ¶
-
- Package
sb-mop.
- Source
- Method: effective-slot-definition-class ((class described-object-class) &rest initargs) ¶
-
- Package
sb-mop.
- Source
-
Initialize the default object description
- Source
-
Ensures we inherit from described-object.
- Source
- Method: validate-superclass ((class described-object-class) (superclass standard-class)) ¶
-
- Package
sb-mop.
- Source
Previous: Standalone methods, Up: Public Interface [Contents][Index]
6.1.6 Classes
- Class: described-object ¶
-
- Package
- Source
- Direct methods
- Direct slots
- Slot: default-description ¶
-
- Initargs
:default-description
- Readers
- Writers
- Slot: parent-descriptions ¶
-
- Initform
(list descriptions:{description})
- Initargs
:parent-descriptions
- Readers
- Writers
- Slot: default-description-name ¶
-
- Initargs
:default-description-name
- Readers
- Writers
- Class: described-object-class ¶
-
- Package
- Source
- Direct superclasses
standard-class.
- Direct methods
- Direct slots
- Slot: default-description ¶
-
- Initargs
:default-description
- Readers
- Writers
Previous: Public Interface, Up: Definitions [Contents][Index]
6.2 Internals
Next: Symbol macros, Previous: Internals, Up: Internals [Contents][Index]
6.2.1 Special variables
- Special Variable: %undefined% ¶
-
- Package
- Source
- Special Variable: =>option ¶
-
- Package
- Special Variable: =>reference ¶
-
- Package
- Special Variable: =>relation ¶
-
- Package
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
6.2.2 Symbol macros
- Symbol Macro: +undefined+ ¶
-
- Package
- Source
Next: Generic functions, Previous: Symbol macros, Up: Internals [Contents][Index]
6.2.3 Ordinary functions
- Function: =>option (&rest property-values) ¶
-
Create a =>OPTION attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>reference (&rest property-values) ¶
-
Create a =>REFERENCE attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: =>relation (&rest property-values) ¶
-
Create a =>RELATION attribute. Takes a plist of property values for the created attribute
- Package
- Source
- Function: copy-undefined (instance) ¶
-
- Package
- Source
- Function: make-undefined (&key) ¶
-
- Package
- Source
- Function: plist-keys (plist) ¶
-
- Package
- Source
- Function: plist-values (plist) ¶
-
- Package
- Source
- Function: symbol->keyword (symbol) ¶
-
- Package
- Source
- Function: undefined-p (object) ¶
-
- Package
- Source
Next: Structures, Previous: Ordinary functions, Up: Internals [Contents][Index]
6.2.4 Generic functions
- Generic Reader: default-description-name (object) ¶
-
- Package
- Methods
- Reader Method: default-description-name ((described-object described-object)) ¶
-
automatically generated reader method
- Source
- Target Slot
- Generic Writer: (setf default-description-name) (object) ¶
-
- Package
- Methods
- Writer Method: (setf default-description-name) ((described-object described-object)) ¶
-
automatically generated writer method
- Source
- Target Slot
- Generic Function: described-p (object) ¶
-
- Package
- Methods
-
- Reader Method: described-p ((described-object-slot-mixin described-object-slot-mixin)) ¶
-
automatically generated reader method
- Source
- Target Slot
- Generic Writer: (setf described-p) (object) ¶
-
- Package
- Methods
- Writer Method: (setf described-p) ((described-object-slot-mixin described-object-slot-mixin)) ¶
-
automatically generated writer method
- Source
- Target Slot
- Generic Function: described-slot-p (slot) ¶
-
- Package
- Source
- Methods
- Method: described-slot-p (slot) ¶
- Method: described-slot-p ((slot described-object-slot-mixin)) ¶
- Generic Reader: parent-descriptions (object) ¶
-
- Package
- Methods
- Reader Method: parent-descriptions ((described-object described-object)) ¶
-
automatically generated reader method
- Source
- Target Slot
- Generic Writer: (setf parent-descriptions) (object) ¶
-
- Package
- Methods
- Writer Method: (setf parent-descriptions) ((described-object described-object)) ¶
-
automatically generated writer method
- Source
- Target Slot
- Generic Function: slot-attribute (object) ¶
-
- Package
- Methods
-
- Reader Method: slot-attribute ((described-object-slot-mixin described-object-slot-mixin)) ¶
-
automatically generated reader method
- Generic Writer: (setf slot-attribute) (object) ¶
-
- Package
- Methods
- Writer Method: (setf slot-attribute) ((described-object-slot-mixin described-object-slot-mixin)) ¶
-
automatically generated writer method
- Generic Function: slot-attribute-name (slot) ¶
-
- Package
- Methods
Next: Classes, Previous: Generic functions, Up: Internals [Contents][Index]
6.2.5 Structures
- Structure: undefined ¶
-
- Package
- Source
- Direct superclasses
structure-object.
Previous: Structures, Up: Internals [Contents][Index]
6.2.6 Classes
- Class: described-object-direct-slot-definition ¶
-
- Package
- Source
- Direct superclasses
- described-object-slot-mixin.
- standard-direct-slot-definition.
- Class: described-object-effective-slot-definition ¶
-
- Package
- Source
- Direct superclasses
- described-object-slot-mixin.
- standard-effective-slot-definition.
- Class: described-object-slot-mixin ¶
Previous: Definitions, Up: The descriptions Reference Manual [Contents][Index]
Appendix A Indexes
A.2 Functions
| Jump to: | (
=
A C D E F G M P S U V W |
|---|
| Jump to: | (
=
A C D E F G M P S U V W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
A.3 Variables
| Jump to: | %
+
=
{
A D P S |
|---|
| Jump to: | %
+
=
{
A D P S |
|---|
A.4 Data types
| Jump to: | C D F M P S U |
|---|
| Jump to: | C D F M P S U |
|---|