The swank-protocol Reference Manual

Table of Contents

The swank-protocol Reference Manual

This is the swank-protocol Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 15:09:34 2020 GMT+0.

1 Introduction

swank-protocol

A low-level client for the Swank server of SLIME.

Overview

swank-protocol is a small, low-level client for Swank. It handles connections and reading/writing messages.

This is not a full client for Swank, it's a permissively-licensed library for building Swank clients. It doesn't match requests to responses, it doesn't asynchronously read responses and events from Swank. It just takes care of the low level details: Connecting, sending messages down the socket, reading and parsing incoming events and responses, and optionally logging.

Usage

First, load everything:

(ql:quickload :swank-protocol)

Run this to start a Swank server on localhost:5000:

(setf swank:*configure-emacs-indentation* nil)

(let ((swank::*loopback-interface* (uiop:hostname)))
  (swank:create-server :port 5000 :dont-close t))

Now we connect:

(defparameter connection
  (swank-protocol-make-connection (uiop:hostname)
                                  5000))

(swank-protocol:connect connection)

Now we can start sending requests:

(swank-protocol:request-connection-info connection)

And reading responses:

(swank-protocol:read-message connection)

For instance, let's create a REPL. First, we require some modules:

(swank-protocol:request-swank-require connection
                                      '(swank-presentations swank-repl))
(swank-protocol:request-init-presentations connection)

(Don't worry about the symbols' package)

Now we actually create it:

(swank-protocol:request-create-repl connection)

Now we can send things for evaluation:

(swank-protocol:request-listener-eval connection "(+ 2 2)")

And receive the results:

(swank-protocol:read-all-messages connection)

API

connection

The connection class has the following readers:

• connection-hostname: The Swank server's hostname.
• connection-port: The Swank server's port.

And the following accessors:

• connection-request-count: The integer ID of the last request sent to the Swank server. Starts at zero.
• connection-package: The package where things are evaluated. This should be changed when you send a request to Swank to change the current package.
• connection-thread: This is the keyword ID of the thread to execute things in. t is used by default to tell Swank to pick the default thread.
• connection-log-p: Whether to log messages as they are read/written.
• connection-logging-stream: The stream to log things to, by default, *error-output*.

Instances of connection can be created with make-connection:

;; A regular connection
(make-connection "my-hostname" "1234")

;; A connection with logging
(make-connection "my-test-server" "1234" :logp t)

The connect function connects to the Swank server and returns t.

Input/Output

After connecting, you can do two things: Send messages or read them.

To write messages, you can use emacs-rex, which takes a connection and an S-expression to send to Swank. Implicit in this request, and stored in the connection object, are two bits of information: The current package and the request ID.

To read messages, you use read-message, which takes a connection and reads the next message coming from Swank. The result is an S-expression.

High-level Functions

There are higher-level convenience functions that call emacs-rex, to minimize repetition and error:

connection-info

Requests connection information. The matching response is a plist with connection information.

Example response:

(:return
  (:ok
    (:pid 1234
     :style :spawn
     :encoding (:coding-systems ("utf-8-unix" "iso-latin-1-unix"))
     :lisp-implementation (:type "SBCL" :name "sbcl" :version "1.2.9" :program "/usr/local/bin/sbcl")
     :machine (:instance "laptop" :type "X86-64" :version "Intel(R) Core(TM) i5-2410M CPU @ 2.30GHz")
     :features (:bordeaux-threads ... :x86-64)
     :modules ("SWANK-REPL" ... "uiop")
     :package (:name "COMMON-LISP-USER" :prompt "CL-USER")
     :version "2014-12-23"))
  1)

See Also

• swank-client: A more complete client, but GPL-licensed.
• Swank protocol description

License

Copyright (c) 2015 Fernando Borretti

Licensed under the MIT License.

2 Systems

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

2.1 swank-protocol

Maintainer

Fernando Borretti <eudoxiahp@gmail.com>

Author

Fernando Borretti <eudoxiahp@gmail.com>

Home Page

https://github.com/eudoxia0/swank-protocol

Source Control

(:git "git@github.com:eudoxia0/swank-protocol.git")

Bug Tracker

https://github.com/eudoxia0/swank-protocol/issues

License

MIT

Description

A low-level Swank client.

Long Description

# swank-protocol

[](https://travis-ci.org/eudoxia0/swank-protocol)
[](https://coveralls.io/r/eudoxia0/swank-protocol?branch=master) [](http://quickdocs.org/swank-protocol/)

A low-level client for the [Swank][swank] server of [SLIME][slime].

# Overview

swank-protocol is a small, low-level client for Swank. It handles connections
and reading/writing messages.

This is not a full client for Swank, it’s a permissively-licensed library for
building Swank clients. It doesn’t match requests to responses, it doesn’t
asynchronously read responses and events from Swank. It just takes care of the
low level details: Connecting, sending messages down the socket, reading and
parsing incoming events and responses, and optionally logging.

# Usage

First, load everything:

“‘
(ql:quickload :swank-protocol)
“‘

Run this to start a Swank server on ‘localhost:5000‘:

“‘lisp
(setf swank:*configure-emacs-indentation* nil)

(let ((swank::*loopback-interface* (uiop:hostname)))
(swank:create-server :port 5000 :dont-close t))
“‘

Now we connect:

“‘
(defparameter connection
(swank-protocol-make-connection (uiop:hostname)
5000))

(swank-protocol:connect connection)
“‘

Now we can start sending requests:

“‘lisp
(swank-protocol:request-connection-info connection)
“‘

And reading responses:

“‘lisp
(swank-protocol:read-message connection)
“‘

For instance, let’s create a REPL. First, we require some modules:

“‘lisp
(swank-protocol:request-swank-require connection
’(swank-presentations swank-repl))
(swank-protocol:request-init-presentations connection)
“‘

(Don’t worry about the symbols’ package)

Now we actually create it:

“‘lisp
(swank-protocol:request-create-repl connection)
“‘

Now we can send things for evaluation:

“‘lisp
(swank-protocol:request-listener-eval connection "(+ 2 2)")
“‘

And receive the results:

“‘lisp
(swank-protocol:read-all-messages connection)
“‘

# API

## ‘connection‘

The ‘connection‘ class has the following readers:

* ‘connection-hostname‘: The Swank server’s hostname.
* ‘connection-port‘: The Swank server’s port.

And the following accessors:

* ‘connection-request-count‘: The integer ID of the last request sent to the
Swank server. Starts at zero.
* ‘connection-package‘: The package where things are evaluated. This should be
changed when you send a request to Swank to change the current package.
* ‘connection-thread‘: This is the keyword ID of the thread to execute things
in. ‘t‘ is used by default to tell Swank to pick the default thread.
* ‘connection-log-p‘: Whether to log messages as they are read/written.
* ‘connection-logging-stream‘: The stream to log things to, by default,
‘*error-output*‘.

Instances of ‘connection‘ can be created with ‘make-connection‘:

“‘lisp
;; A regular connection
(make-connection "my-hostname" "1234")

;; A connection with logging
(make-connection "my-test-server" "1234" :logp t)
“‘

The ‘connect‘ function connects to the Swank server and returns t.

## Input/Output

After connecting, you can do two things: Send messages or read them.

To write messages, you can use ‘emacs-rex‘, which takes a connection and an
S-expression to send to Swank. Implicit in this request, and stored in the
‘connection‘ object, are two bits of information: The current package and the
request ID.

To read messages, you use ‘read-message‘, which takes a connection and reads the
next message coming from Swank. The result is an S-expression.

## High-level Functions

There are higher-level convenience functions that call ‘emacs-rex‘, to minimize
repetition and error:

### ‘connection-info‘

Requests connection information. The matching response is a plist with
connection information.

Example response:

“‘lisp
(:return
(:ok
(:pid 1234
:style :spawn
:encoding (:coding-systems ("utf-8-unix" "iso-latin-1-unix"))
:lisp-implementation (:type "SBCL" :name "sbcl" :version "1.2.9" :program "/usr/local/bin/sbcl")
:machine (:instance "laptop" :type "X86-64" :version "Intel(R) Core(TM) i5-2410M CPU @ 2.30GHz")
:features (:bordeaux-threads ... :x86-64)
:modules ("SWANK-REPL" ... "uiop")
:package (:name "COMMON-LISP-USER" :prompt "CL-USER")
:version "2014-12-23"))
1)
“‘

# See Also

* [swank-client][s-c]: A more complete client, but GPL-licensed.
* [Swank protocol description][description]

[slime]: https://common-lisp.net/project/slime/
[swank]: https://github.com/slime/slime/tree/master/swank
[s-c]: https://github.com/brown/swank-client
[description]: https://github.com/astine/swank-client/blob/master/swank-description.markdown

# License

Copyright (c) 2015 Fernando Borretti

Licensed under the MIT License.

Version

0.1

Dependencies

• usocket
• swank

Source

swank-protocol.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 swank-protocol/src

Parent

swank-protocol (system)

Location

src/

Component

swank-protocol.lisp (file)

4 Files

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

4.1 Lisp

4.1.1 swank-protocol.asd

Location

swank-protocol.asd

Systems

swank-protocol (system)

4.1.2 swank-protocol/src/swank-protocol.lisp

Parent

src (module)

Location

src/swank-protocol.lisp

Packages

swank-protocol

Exported Definitions

• connect (method)
• connection (class)
• connection-hostname (method)
• connection-log-p (method)
• (setf connection-log-p) (method)
• connection-logging-stream (method)
• (setf connection-logging-stream) (method)
• connection-package (method)
• (setf connection-package) (method)
• connection-port (method)
• connection-request-count (method)
• (setf connection-request-count) (method)
• connection-thread (method)
• (setf connection-thread) (method)
• emacs-rex (function)
• make-connection (function)
• message-waiting-p (function)
• read-all-messages (function)
• read-message (function)
• read-message-string (function)
• request-connection-info (function)
• request-create-repl (function)
• request-init-presentations (function)
• request-input-string (function)
• request-input-string-newline (function)
• request-invoke-restart (function)
• request-listener-eval (function)
• request-swank-require (function)
• request-throw-to-toplevel (function)
• send-message-string (function)

Internal Definitions

• connection-read-count (method)
• (setf connection-read-count) (method)
• connection-socket (method)
• (setf connection-socket) (method)
• decode-integer (function)
• encode-integer (function)
• log-message (function)
• read-message-from-stream (function)
• with-swank-syntax (macro)
• write-message-to-stream (function)

5 Packages

Packages are listed by definition order.

5.1 swank-protocol

Low-level implementation of a client for the Swank protocol.

Source

swank-protocol.lisp (file)

Use List

common-lisp

Exported Definitions

• connect (generic function)
• connect (method)
• connection (class)
• connection-hostname (generic function)
• connection-hostname (method)
• connection-log-p (generic function)
• connection-log-p (method)
• (setf connection-log-p) (method)
• (setf connection-log-p) (generic function)
• connection-logging-stream (generic function)
• connection-logging-stream (method)
• (setf connection-logging-stream) (method)
• (setf connection-logging-stream) (generic function)
• connection-package (generic function)
• connection-package (method)
• (setf connection-package) (method)
• (setf connection-package) (generic function)
• connection-port (generic function)
• connection-port (method)
• connection-request-count (generic function)
• connection-request-count (method)
• (setf connection-request-count) (method)
• (setf connection-request-count) (generic function)
• connection-thread (generic function)
• connection-thread (method)
• (setf connection-thread) (method)
• (setf connection-thread) (generic function)
• emacs-rex (function)
• make-connection (function)
• message-waiting-p (function)
• read-all-messages (function)
• read-message (function)
• read-message-string (function)
• request-connection-info (function)
• request-create-repl (function)
• request-init-presentations (function)
• request-input-string (function)
• request-input-string-newline (function)
• request-invoke-restart (function)
• request-listener-eval (function)
• request-swank-require (function)
• request-throw-to-toplevel (function)
• send-message-string (function)

Internal Definitions

• connection-read-count (generic function)
• connection-read-count (method)
• (setf connection-read-count) (method)
• (setf connection-read-count) (generic function)
• connection-socket (generic function)
• connection-socket (method)
• (setf connection-socket) (method)
• (setf connection-socket) (generic function)
• decode-integer (function)
• encode-integer (function)
• log-message (function)
• read-message-from-stream (function)
• with-swank-syntax (macro)
• write-message-to-stream (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Functions

Function: emacs-rex CONNECTION FORM

(R)emote (E)xecute S-e(X)p.

Send an S-expression command to Swank to evaluate. The resulting response must be read with read-response.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: make-connection HOSTNAME PORT &key LOGP

Create a connection to a remote Swank server.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: message-waiting-p CONNECTION

t if there’s a message in the connection waiting to be read, nil otherwise.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: read-all-messages CONNECTION

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: read-message CONNECTION

Read an arbitrary message from a connection.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: read-message-string CONNECTION

Read a message string from a Swank connection.

This function will block until it reads everything. Consider message-waiting-p to check if input is available.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-connection-info CONNECTION

Request that Swank provide connection information.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-create-repl CONNECTION

Request that Swank create a new REPL.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-init-presentations CONNECTION

Request that Swank initiate presentations.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-input-string CONNECTION STRING

Send a string to the server’s standard input.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-input-string-newline CONNECTION STRING

Send a string to the server’s standard input with a newline at the end.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-invoke-restart CONNECTION DEBUG-LEVEL RESTART-NUMBER

Invoke a restart.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-listener-eval CONNECTION STRING

Request that Swank evaluate a string of code in the REPL.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-swank-require CONNECTION REQUIREMENTS

Request that the Swank server load contrib modules. ‘requirements‘ must be a list of symbols, e.g. ’(swank-repl swank-media).

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: request-throw-to-toplevel CONNECTION

Leave the debugger.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: send-message-string CONNECTION MESSAGE

Send a message string to a Swank connection.

Package

swank-protocol

Source

swank-protocol.lisp (file)

6.1.2 Generic functions

Generic Function: connect CONNECTION

Package

swank-protocol

Methods

Method: connect (CONNECTION connection)

Connect to the remote server. Returns t.

Source

swank-protocol.lisp (file)

Generic Function: connection-hostname OBJECT

Package

swank-protocol

Methods

Method: connection-hostname (CONNECTION connection)

The host to connect to.

Source

swank-protocol.lisp (file)

Generic Function: connection-log-p OBJECT

Generic Function: (setf connection-log-p) NEW-VALUE OBJECT

Package

swank-protocol

Methods

Method: connection-log-p (CONNECTION connection)

Method: (setf connection-log-p) NEW-VALUE (CONNECTION connection)

Whether or not to log connection requests.

Source

swank-protocol.lisp (file)

Generic Function: connection-logging-stream OBJECT

Generic Function: (setf connection-logging-stream) NEW-VALUE OBJECT

Package

swank-protocol

Methods

Method: connection-logging-stream (CONNECTION connection)

Method: (setf connection-logging-stream) NEW-VALUE (CONNECTION connection)

The stream to log to.

Source

swank-protocol.lisp (file)

Generic Function: connection-package OBJECT

Generic Function: (setf connection-package) NEW-VALUE OBJECT

Package

swank-protocol

Methods

Method: connection-package (CONNECTION connection)

Method: (setf connection-package) NEW-VALUE (CONNECTION connection)

The name of the connection’s package.

Source

swank-protocol.lisp (file)

Generic Function: connection-port OBJECT

Package

swank-protocol

Methods

Method: connection-port (CONNECTION connection)

The port to connect to.

Source

swank-protocol.lisp (file)

Generic Function: connection-request-count OBJECT

Generic Function: (setf connection-request-count) NEW-VALUE OBJECT

Package

swank-protocol

Methods

Method: connection-request-count (CONNECTION connection)

Method: (setf connection-request-count) NEW-VALUE (CONNECTION connection)

A number that is increased and sent along with every request.

Source

swank-protocol.lisp (file)

Generic Function: connection-thread OBJECT

Generic Function: (setf connection-thread) NEW-VALUE OBJECT

Package

swank-protocol

Methods

Method: connection-thread (CONNECTION connection)

Method: (setf connection-thread) NEW-VALUE (CONNECTION connection)

The current thread.

Source

swank-protocol.lisp (file)

6.1.3 Classes

Class: connection ()

A connection to a remote Lisp.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• connect (method)
• connection-logging-stream (method)
• connection-logging-stream (method)
• connection-log-p (method)
• connection-log-p (method)
• connection-thread (method)
• connection-thread (method)
• connection-package (method)
• connection-package (method)
• connection-read-count (method)
• connection-read-count (method)
• connection-request-count (method)
• connection-request-count (method)
• connection-socket (method)
• connection-socket (method)
• connection-port (method)
• connection-hostname (method)

Direct slots

Slot: hostname

The host to connect to.

Type

string

Initargs

:hostname

Readers

connection-hostname (generic function)

Slot: port

The port to connect to.

Type

integer

Initargs

:port

Readers

connection-port (generic function)

Slot: socket

The usocket socket.

Type

usocket:stream-usocket

Readers

connection-socket (generic function)

Writers

(setf connection-socket) (generic function)

Slot: request-count

A number that is increased and sent along with every request.

Type

integer

Initform

0

Readers

connection-request-count (generic function)

Writers

(setf connection-request-count) (generic function)

Slot: read-count

Counter of the number of times read is called in the server’s REPL.

Type

integer

Initform

0

Readers

connection-read-count (generic function)

Writers

(setf connection-read-count) (generic function)

Slot: package

The name of the connection’s package.

Type

string

Initform

"common-lisp-user"

Readers

connection-package (generic function)

Writers

(setf connection-package) (generic function)

Slot: thread

The current thread.

Initform

t

Readers

connection-thread (generic function)

Writers

(setf connection-thread) (generic function)

Slot: logp

Whether or not to log connection requests.

Type

boolean

Initargs

:logp

Readers

connection-log-p (generic function)

Writers

(setf connection-log-p) (generic function)

Slot: logging-stream

The stream to log to.

Type

stream

Initargs

:logging-stream

Initform

*error-output*

Readers

connection-logging-stream (generic function)

Writers

(setf connection-logging-stream) (generic function)

6.2 Internal definitions

6.2.1 Macros

Macro: with-swank-syntax () &body BODY

Package

swank-protocol

Source

swank-protocol.lisp (file)

6.2.2 Functions

Function: decode-integer STRING

Decode a string representing a 0-padded 16-bit hex string to an integer.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: encode-integer INTEGER

Encode an integer to a 0-padded 16-bit hexadecimal string.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: log-message CONNECTION FORMAT-STRING &rest ARGUMENTS

Log a message.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: read-message-from-stream STREAM

Read a string from a string.

Parses length information to determine how many characters to read.

Package

swank-protocol

Source

swank-protocol.lisp (file)

Function: write-message-to-stream STREAM MESSAGE

Write a string to a stream, prefixing it with length information for Swank.

Package

swank-protocol

Source

swank-protocol.lisp (file)

6.2.3 Generic functions

Generic Function: connection-read-count OBJECT

Generic Function: (setf connection-read-count) NEW-VALUE OBJECT

Package

swank-protocol

Methods

Method: connection-read-count (CONNECTION connection)

Method: (setf connection-read-count) NEW-VALUE (CONNECTION connection)

Counter of the number of times read is called in the server’s REPL.

Source

swank-protocol.lisp (file)

Generic Function: connection-socket OBJECT

Generic Function: (setf connection-socket) NEW-VALUE OBJECT

Package

swank-protocol

Methods

Method: connection-socket (CONNECTION connection)

Method: (setf connection-socket) NEW-VALUE (CONNECTION connection)

The usocket socket.

Source

swank-protocol.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types