The interface Reference Manual

Table of Contents

The interface Reference Manual

This is the interface Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:01:51 2018 GMT+0.

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.

2 Systems

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

2.1 interface

Author

Robert Smith <quad@symbo1ics.com>

License

BSD 3-clause (See LICENSE)

Description

A system for defining interfaces.

Dependencies

• alexandria
• global-vars

Source

interface.asd (file)

Components

• license (file)
• package.lisp (file)
• interface.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 interface.asd

Location

interface.asd

Systems

interface (system)

3.1.2 interface/package.lisp

Dependency

license (file)

Parent

interface (system)

Location

package.lisp

Packages

interface

3.1.3 interface/interface.lisp

Dependency

package.lisp (file)

Parent

interface (system)

Location

interface.lisp

Exported Definitions

• calling-form (function)
• define-implementation (macro)
• define-interface (macro)

Internal Definitions

• arglist (structure)
• arglist-args (function)
• (setf arglist-args) (function)
• arglist-form (function)
• arglist-p (function)
• arglist-use-apply (function)
• (setf arglist-use-apply) (function)
• copy-arglist (function)
• extend-arglist (function)
• interface-accessor (function)
• interface-conc-name (function)
• interface-function-specification-p (function)
• interface-implementation-constructor-name (function)
• interface-specification-p (function)
• interface-value-specification-p (function)
• make-arglist (function)
• make-arglist-use-apply (function)

3.2 Other

3.2.1 interface/LICENSE

Parent

interface (system)

Location

LICENSE

4 Packages

Packages are listed by definition order.

4.1 interface

Source

package.lisp (file)

Nickname

intf

Use List

common-lisp

Exported Definitions

• calling-form (function)
• define-implementation (macro)
• define-interface (macro)

Internal Definitions

• arglist (structure)
• arglist-args (function)
• (setf arglist-args) (function)
• arglist-form (function)
• arglist-p (function)
• arglist-use-apply (function)
• (setf arglist-use-apply) (function)
• copy-arglist (function)
• extend-arglist (function)
• interface-accessor (function)
• interface-conc-name (function)
• interface-function-specification-p (function)
• interface-implementation-constructor-name (function)
• interface-specification-p (function)
• interface-value-specification-p (function)
• make-arglist (function)
• make-arglist-use-apply (function)

5 Definitions

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

5.1 Exported definitions

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)

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)

5.2 Internal definitions

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)

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)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types