The interface Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The interface Reference Manual

This is the interface Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 08:51:44 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

                              INTERFACE
                              =========

                           By Robert Smith

1. Introduction

This system contains an implementation of interfaces and
implementations. They're sometimes called protocols in other
languages.

Broadly speaking, an "interface" is some collection of function
"prototypes" that a valid implementation must implement. For example,
something called a "stack" must implement stack creation, pushing,
peeking, and popping.

The notion of interfaces and implementations aid the distinction
between data structures and different implementations of that data
structure. This was perhaps pioneered by Modula-3, and became a
significant part of other languages like Standard ML and OCaml. In all
of the aforementioned languages, interfaces can actually contain more
than just functions, such as types and values. Haskell typeclasses are
also a form of interface and implementation. They are very general and
are even parametric.

One way to accomplish the notion of interfaces and implementations in
Lisp is to use some "abstract class" and make several (final)
subclasses of that class. The interface, in this case, is the abstract
class and a collection of generic functions. The implementation would
be the final subclass along with method definitions.

For example:

    (defclass stack () ())
    (defgeneric make-stack (impl))
    (defgeneric stack-push (impl s x))
    (defgeneric stack-pop (impl s))
    (defgeneric stack-peek (impl s))

    (defclass list-stack (stack) ())
    (defmethod make-stack ((impl list-stack))
      nil)
    (defmethod stack-push ((impl list-stack) s x)
      (cons x s))
    (defmethod stack-pop ((impl list-stack) s)
      (cdr s))
    (defmethod stack-peek ((impl list-stack) s)
      (car s))

This is mostly sufficient, though Lisp makes no guarantee that a class
will have any set of methods defined for it. (One could perhaps use
the MOP for this.) One can "optimize" implementations by conflating
the notion of an implementation with the actual data structure being
implemented, and make it a part of the implementation class. In this
case, we could have a slot in LIST-STACK holding the list.

Since methods are not tied to classes, this implementation allows one
to have a class implement several methods. Also, it is entirely
possible to do away with the superclass; that is a formality tying all
implementations to a particular interface with a name.

As I understand, this basic notion is taken to the extreme with Fare's
Lisp Interface Library (http://www.cliki.net/lisp-interface-library).


In this system, however, we take a different approach
entirely. Instead of using a class to represent interfaces and
implementations, we have a structure whose slots are the
implementation functions. The name of the structure (which decides
what slots it has) is the interface, and the implementation is the
actual slot values.

It is cumbersome, however, to use an interface by accessing slots all
of the time. Instead, we define functions---which correspond to the
slot names---which access the slots of an implementation and pass the
arguments to it.

In doing this, there's no dispatch on type required, just access on
the slots of the structure. It also forces data structures and the
interface to be completely disjoint entities.


2. Example

(define-interface stack ()
  (make-stack (&rest r))
  (push-stack (s x))
  (peek-stack (s))
  (pop-stack (s)))

(define-implementation list-stack (stack)
  :make-stack
  (lambda (&rest r)
    r)

  :push-stack
  (lambda (s x)
    (cons x s))

  :peek-stack
  (lambda (s)
    (car s))
  
  :pop-stack
  (lambda (s)
    (cdr s)))

(define-implementation vector-stack (stack)
  :make-stack
  (lambda (&rest r)
    (let ((length (length r)))
      (make-array length
                  :adjustable t
                  :fill-pointer length
                  :initial-contents r)))
  
  :push-stack
  (lambda (s x)
    (vector-push-extend x s)
    s)
  
  :peek-stack
  (lambda (s)
    (aref s (1- (length s))))
  
  :pop-stack
  (lambda (s)
    (vector-pop s)
    s))

;;; CL-USER> (pop-stack vector-stack
;;;                     (push-stack vector-stack
;;;                                 (make-stack vector-stack 1 2 3)
;;;                                 5))
;;; #(1 2 3)
;;; CL-USER> (pop-stack list-stack
;;;                     (push-stack list-stack
;;;                                 (make-stack list-stack 1 2 3)
;;;                                 5))
;;; (1 2 3)

3. Performance

This implementation has been measured to be between 10% and 30% faster
than the classes approach described above. See the file
interface-bench.lisp.

4. Other notes

The package also has a handy utility function called CALLING-FORM. It
solves the following problem:

Consider a function F with a lambda list (L...). How can we write a
function G

    (defun G (L...)
      )

such that calls to G are precisely equivalent to F? We can use

    (calling-form 'f '(L...))

which will produce code which is suitable for the definition of G.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 interface

Author

Robert Smith <quad@symbo1ics.com>

License

BSD 3-clause (See LICENSE)

Description

A system for defining interfaces.

Dependencies
Source

interface.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Next: , Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 interface.asd

Location

interface.asd

Systems

interface (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 interface/package.lisp

Dependency

license (file)

Parent

interface (system)

Location

package.lisp

Packages

interface


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 interface/interface.lisp

Dependency

package.lisp (file)

Parent

interface (system)

Location

interface.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Files   [Contents][Index]

3.2 Other


Previous: , Up: Other files   [Contents][Index]

3.2.1 interface/LICENSE

Parent

interface (system)

Location

LICENSE


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 interface

Source

package.lisp (file)

Nickname

intf

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: define-implementation NAME (INTF-NAME) &body IMPLEMENTATIONS
Package

interface

Source

interface.lisp (file)

Macro: define-interface NAME OPTIONS &body SPECS

Define an interface whose name is NAME and list of options are OPTIONS. (Currently, no options are supported.) The body of the definition should be a list of "interface specifications". An interface specification is:

* A list containing a function name as the first element and the
lambda list as the second element.

* A symbol representing a constant value.

Package

interface

Source

interface.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: calling-form FUNCTION-FORM LAMBDA-LIST

Given an ordinary lambda list LAMBDA-LIST and a FUNCALLable FUNCTION-FORM, construct a form which calls FUNCTION-FORM on all of the arguments specified by LAMBDA-LIST.

Package

interface

Source

interface.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: arglist-args INSTANCE
Function: (setf arglist-args) VALUE INSTANCE
Package

interface

Source

interface.lisp (file)

Function: arglist-form FUNCTION-FORM ARGLIST

Construct the calling form with the function form FUNCTION-FORM and the arglist ARGLIST.

Package

interface

Source

interface.lisp (file)

Function: arglist-p OBJECT
Package

interface

Source

interface.lisp (file)

Function: arglist-use-apply INSTANCE
Function: (setf arglist-use-apply) VALUE INSTANCE
Package

interface

Source

interface.lisp (file)

Function: copy-arglist INSTANCE
Package

interface

Source

interface.lisp (file)

Function: extend-arglist ARGLIST &rest ARGS

Extend the arglist ARGLIST with the arguments ARGS. Creates a new arglist.

Package

interface

Source

interface.lisp (file)

Function: interface-accessor INTF-NAME SLOT
Package

interface

Source

interface.lisp (file)

Function: interface-conc-name INTF-NAME
Package

interface

Source

interface.lisp (file)

Function: interface-function-specification-p SPEC
Package

interface

Source

interface.lisp (file)

Function: interface-implementation-constructor-name INTF-NAME &optional PACKAGE
Package

interface

Source

interface.lisp (file)

Function: interface-specification-p SPEC
Package

interface

Source

interface.lisp (file)

Function: interface-value-specification-p SPEC
Package

interface

Source

interface.lisp (file)

Function: make-arglist &key (ARGS ARGS) (USE-APPLY USE-APPLY)
Package

interface

Source

interface.lisp (file)

Function: make-arglist-use-apply ARGLIST

Create an arglist identical to the arglist ARGLIST, except specifying that it must use APPLY.

Package

interface

Source

interface.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Structures

Structure: arglist ()
Package

interface

Source

interface.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: args
Readers

arglist-args (function)

Writers

(setf arglist-args) (function)

Slot: use-apply
Readers

arglist-use-apply (function)

Writers

(setf arglist-use-apply) (function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   I   L   O  
Index Entry  Section

F
File, Lisp, interface.asd: The interface<dot>asd file
File, Lisp, interface/interface.lisp: The interface/interface<dot>lisp file
File, Lisp, interface/package.lisp: The interface/package<dot>lisp file
File, other, interface/LICENSE: The interface/license file

I
interface.asd: The interface<dot>asd file
interface/interface.lisp: The interface/interface<dot>lisp file
interface/LICENSE: The interface/license file
interface/package.lisp: The interface/package<dot>lisp file

L
Lisp File, interface.asd: The interface<dot>asd file
Lisp File, interface/interface.lisp: The interface/interface<dot>lisp file
Lisp File, interface/package.lisp: The interface/package<dot>lisp file

O
Other File, interface/LICENSE: The interface/license file

Jump to:   F   I   L   O  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   E   F   I   M  
Index Entry  Section

(
(setf arglist-args): Internal functions
(setf arglist-use-apply): Internal functions

A
arglist-args: Internal functions
arglist-form: Internal functions
arglist-p: Internal functions
arglist-use-apply: Internal functions

C
calling-form: Exported functions
copy-arglist: Internal functions

D
define-implementation: Exported macros
define-interface: Exported macros

E
extend-arglist: Internal functions

F
Function, (setf arglist-args): Internal functions
Function, (setf arglist-use-apply): Internal functions
Function, arglist-args: Internal functions
Function, arglist-form: Internal functions
Function, arglist-p: Internal functions
Function, arglist-use-apply: Internal functions
Function, calling-form: Exported functions
Function, copy-arglist: Internal functions
Function, extend-arglist: Internal functions
Function, interface-accessor: Internal functions
Function, interface-conc-name: Internal functions
Function, interface-function-specification-p: Internal functions
Function, interface-implementation-constructor-name: Internal functions
Function, interface-specification-p: Internal functions
Function, interface-value-specification-p: Internal functions
Function, make-arglist: Internal functions
Function, make-arglist-use-apply: Internal functions

I
interface-accessor: Internal functions
interface-conc-name: Internal functions
interface-function-specification-p: Internal functions
interface-implementation-constructor-name: Internal functions
interface-specification-p: Internal functions
interface-value-specification-p: Internal functions

M
Macro, define-implementation: Exported macros
Macro, define-interface: Exported macros
make-arglist: Internal functions
make-arglist-use-apply: Internal functions

Jump to:   (  
A   C   D   E   F   I   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   A   S   U  
Index Entry  Section

A
args: Internal structures

S
Slot, args: Internal structures
Slot, use-apply: Internal structures

U
use-apply: Internal structures

Jump to:   A   S   U  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   A   I   P   S  
Index Entry  Section

A
arglist: Internal structures

I
interface: The interface system
interface: The interface package

P
Package, interface: The interface package

S
Structure, arglist: Internal structures
System, interface: The interface system

Jump to:   A   I   P   S