The swank-protocol Reference Manual

This is the swank-protocol Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 07:01:02 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 swank-protocol

A low-level Swank client.

Maintainer

Fernando Borretti <>

Author

Fernando Borretti <>

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

Long Description

# swank-protocol

[![Build Status](https://travis-ci.org/eudoxia0/swank-protocol.svg?branch=master)](https://travis-ci.org/eudoxia0/swank-protocol)
[![Coverage Status](https://coveralls.io/repos/eudoxia0/swank-protocol/badge.svg?branch=master)](https://coveralls.io/r/eudoxia0/swank-protocol?branch=master) [![Quicklisp](http://quickdocs.org/badge/swank-protocol.svg)](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 (system).
  • swank (system).
  • babel (system)., for feature (:not (:or :sbcl :allegro :ccl :clisp))
Source

swank-protocol.asd.

Child Component

src (module).


3 Modules

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


3.1 swank-protocol/src

Source

swank-protocol.asd.

Parent Component

swank-protocol (system).

Child 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/swank-protocol.asd

Source

swank-protocol.asd.

Parent Component

swank-protocol (system).

ASDF Systems

swank-protocol.


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

Source

swank-protocol.asd.

Parent Component

src (module).

Packages

swank-protocol.

Public Interface
Internals

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.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Ordinary 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.

Function: make-connection (hostname port &key logp)

Create a connection to a remote Swank server.

Package

swank-protocol.

Source

swank-protocol.lisp.

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.

Function: read-all-messages (connection)
Package

swank-protocol.

Source

swank-protocol.lisp.

Function: read-message (connection)

Read an arbitrary message from a connection.

Package

swank-protocol.

Source

swank-protocol.lisp.

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.

Function: request-connection-info (connection)

Request that Swank provide connection information.

Package

swank-protocol.

Source

swank-protocol.lisp.

Function: request-create-repl (connection)

Request that Swank create a new REPL.

Package

swank-protocol.

Source

swank-protocol.lisp.

Function: request-init-presentations (connection)

Request that Swank initiate presentations.

Package

swank-protocol.

Source

swank-protocol.lisp.

Function: request-input-string (connection string)

Send a string to the server’s standard input.

Package

swank-protocol.

Source

swank-protocol.lisp.

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.

Function: request-invoke-restart (connection debug-level restart-number)

Invoke a restart.

Package

swank-protocol.

Source

swank-protocol.lisp.

Function: request-listener-eval (connection string)

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

Package

swank-protocol.

Source

swank-protocol.lisp.

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.

Function: request-throw-to-toplevel (connection)

Leave the debugger.

Package

swank-protocol.

Source

swank-protocol.lisp.

Function: send-message-string (connection message)

Send a message string to a Swank connection.

Package

swank-protocol.

Source

swank-protocol.lisp.


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.

Generic Reader: connection-hostname (object)
Package

swank-protocol.

Methods
Reader Method: connection-hostname ((connection connection))

The host to connect to.

Source

swank-protocol.lisp.

Target Slot

hostname.

Generic Reader: connection-log-p (object)
Generic Writer: (setf connection-log-p) (object)
Package

swank-protocol.

Methods
Reader Method: connection-log-p ((connection connection))
Writer Method: (setf connection-log-p) ((connection connection))

Whether or not to log connection requests.

Source

swank-protocol.lisp.

Target Slot

logp.

Generic Reader: connection-logging-stream (object)
Generic Writer: (setf connection-logging-stream) (object)
Package

swank-protocol.

Methods
Reader Method: connection-logging-stream ((connection connection))
Writer Method: (setf connection-logging-stream) ((connection connection))

The stream to log to.

Source

swank-protocol.lisp.

Target Slot

logging-stream.

Generic Reader: connection-package (object)
Generic Writer: (setf connection-package) (object)
Package

swank-protocol.

Methods
Reader Method: connection-package ((connection connection))
Writer Method: (setf connection-package) ((connection connection))

The name of the connection’s package.

Source

swank-protocol.lisp.

Target Slot

package.

Generic Reader: connection-port (object)
Package

swank-protocol.

Methods
Reader Method: connection-port ((connection connection))

The port to connect to.

Source

swank-protocol.lisp.

Target Slot

port.

Generic Reader: connection-request-count (object)
Generic Writer: (setf connection-request-count) (object)
Package

swank-protocol.

Methods
Reader Method: connection-request-count ((connection connection))
Writer Method: (setf connection-request-count) ((connection connection))

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

Source

swank-protocol.lisp.

Target Slot

request-count.

Generic Reader: connection-thread (object)
Generic Writer: (setf connection-thread) (object)
Package

swank-protocol.

Methods
Reader Method: connection-thread ((connection connection))
Writer Method: (setf connection-thread) ((connection connection))

The current thread.

Source

swank-protocol.lisp.

Target Slot

thread.


6.1.3 Classes

Class: connection

A connection to a remote Lisp.

Package

swank-protocol.

Source

swank-protocol.lisp.

Direct methods
Direct slots
Slot: hostname

The host to connect to.

Type

string

Initargs

:hostname

Readers

connection-hostname.

Writers

This slot is read-only.

Slot: port

The port to connect to.

Type

integer

Initargs

:port

Readers

connection-port.

Writers

This slot is read-only.

Slot: socket

The usocket socket.

Type

usocket:stream-usocket

Readers

connection-socket.

Writers

(setf connection-socket).

Slot: request-count

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

Type

integer

Initform

0

Readers

connection-request-count.

Writers

(setf connection-request-count).

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.

Writers

(setf connection-read-count).

Slot: package

The name of the connection’s package.

Package

common-lisp.

Type

string

Initform

"common-lisp-user"

Readers

connection-package.

Writers

(setf connection-package).

Slot: thread

The current thread.

Initform

t

Readers

connection-thread.

Writers

(setf connection-thread).

Slot: logp

Whether or not to log connection requests.

Type

boolean

Initargs

:logp

Readers

connection-log-p.

Writers

(setf connection-log-p).

Slot: logging-stream

The stream to log to.

Type

stream

Initform

*error-output*

Initargs

:logging-stream

Readers

connection-logging-stream.

Writers

(setf connection-logging-stream).


6.2 Internals


6.2.1 Macros

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

swank-protocol.

Source

swank-protocol.lisp.


6.2.2 Ordinary 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.

Function: encode-integer (integer)

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

Package

swank-protocol.

Source

swank-protocol.lisp.

Function: log-message (connection format-string &rest arguments)

Log a message.

Package

swank-protocol.

Source

swank-protocol.lisp.

Function: octets-to-string (octets)
Package

swank-protocol.

Source

swank-protocol.lisp.

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.

Function: string-to-octets (string)
Package

swank-protocol.

Source

swank-protocol.lisp.

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.


6.2.3 Generic functions

Generic Reader: connection-read-count (object)
Generic Writer: (setf connection-read-count) (object)
Package

swank-protocol.

Methods
Reader Method: connection-read-count ((connection connection))
Writer Method: (setf connection-read-count) ((connection connection))

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

Source

swank-protocol.lisp.

Target Slot

read-count.

Generic Reader: connection-socket (object)
Generic Writer: (setf connection-socket) (object)
Package

swank-protocol.

Methods
Reader Method: connection-socket ((connection connection))
Writer Method: (setf connection-socket) ((connection connection))

The usocket socket.

Source

swank-protocol.lisp.

Target Slot

socket.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   E   F   G   L   M   O   R   S   W  
Index Entry  Section

(
(setf connection-log-p): Public generic functions
(setf connection-log-p): Public generic functions
(setf connection-logging-stream): Public generic functions
(setf connection-logging-stream): Public generic functions
(setf connection-package): Public generic functions
(setf connection-package): Public generic functions
(setf connection-read-count): Private generic functions
(setf connection-read-count): Private generic functions
(setf connection-request-count): Public generic functions
(setf connection-request-count): Public generic functions
(setf connection-socket): Private generic functions
(setf connection-socket): Private generic functions
(setf connection-thread): Public generic functions
(setf connection-thread): Public generic functions

C
connect: Public generic functions
connect: Public generic functions
connection-hostname: Public generic functions
connection-hostname: Public generic functions
connection-log-p: Public generic functions
connection-log-p: Public generic functions
connection-logging-stream: Public generic functions
connection-logging-stream: Public generic functions
connection-package: Public generic functions
connection-package: Public generic functions
connection-port: Public generic functions
connection-port: Public generic functions
connection-read-count: Private generic functions
connection-read-count: Private generic functions
connection-request-count: Public generic functions
connection-request-count: Public generic functions
connection-socket: Private generic functions
connection-socket: Private generic functions
connection-thread: Public generic functions
connection-thread: Public generic functions

D
decode-integer: Private ordinary functions

E
emacs-rex: Public ordinary functions
encode-integer: Private ordinary functions

F
Function, decode-integer: Private ordinary functions
Function, emacs-rex: Public ordinary functions
Function, encode-integer: Private ordinary functions
Function, log-message: Private ordinary functions
Function, make-connection: Public ordinary functions
Function, message-waiting-p: Public ordinary functions
Function, octets-to-string: Private ordinary functions
Function, read-all-messages: Public ordinary functions
Function, read-message: Public ordinary functions
Function, read-message-from-stream: Private ordinary functions
Function, read-message-string: Public ordinary functions
Function, request-connection-info: Public ordinary functions
Function, request-create-repl: Public ordinary functions
Function, request-init-presentations: Public ordinary functions
Function, request-input-string: Public ordinary functions
Function, request-input-string-newline: Public ordinary functions
Function, request-invoke-restart: Public ordinary functions
Function, request-listener-eval: Public ordinary functions
Function, request-swank-require: Public ordinary functions
Function, request-throw-to-toplevel: Public ordinary functions
Function, send-message-string: Public ordinary functions
Function, string-to-octets: Private ordinary functions
Function, write-message-to-stream: Private ordinary functions

G
Generic Function, (setf connection-log-p): Public generic functions
Generic Function, (setf connection-logging-stream): Public generic functions
Generic Function, (setf connection-package): Public generic functions
Generic Function, (setf connection-read-count): Private generic functions
Generic Function, (setf connection-request-count): Public generic functions
Generic Function, (setf connection-socket): Private generic functions
Generic Function, (setf connection-thread): Public generic functions
Generic Function, connect: Public generic functions
Generic Function, connection-hostname: Public generic functions
Generic Function, connection-log-p: Public generic functions
Generic Function, connection-logging-stream: Public generic functions
Generic Function, connection-package: Public generic functions
Generic Function, connection-port: Public generic functions
Generic Function, connection-read-count: Private generic functions
Generic Function, connection-request-count: Public generic functions
Generic Function, connection-socket: Private generic functions
Generic Function, connection-thread: Public generic functions

L
log-message: Private ordinary functions

M
Macro, with-swank-syntax: Private macros
make-connection: Public ordinary functions
message-waiting-p: Public ordinary functions
Method, (setf connection-log-p): Public generic functions
Method, (setf connection-logging-stream): Public generic functions
Method, (setf connection-package): Public generic functions
Method, (setf connection-read-count): Private generic functions
Method, (setf connection-request-count): Public generic functions
Method, (setf connection-socket): Private generic functions
Method, (setf connection-thread): Public generic functions
Method, connect: Public generic functions
Method, connection-hostname: Public generic functions
Method, connection-log-p: Public generic functions
Method, connection-logging-stream: Public generic functions
Method, connection-package: Public generic functions
Method, connection-port: Public generic functions
Method, connection-read-count: Private generic functions
Method, connection-request-count: Public generic functions
Method, connection-socket: Private generic functions
Method, connection-thread: Public generic functions

O
octets-to-string: Private ordinary functions

R
read-all-messages: Public ordinary functions
read-message: Public ordinary functions
read-message-from-stream: Private ordinary functions
read-message-string: Public ordinary functions
request-connection-info: Public ordinary functions
request-create-repl: Public ordinary functions
request-init-presentations: Public ordinary functions
request-input-string: Public ordinary functions
request-input-string-newline: Public ordinary functions
request-invoke-restart: Public ordinary functions
request-listener-eval: Public ordinary functions
request-swank-require: Public ordinary functions
request-throw-to-toplevel: Public ordinary functions

S
send-message-string: Public ordinary functions
string-to-octets: Private ordinary functions

W
with-swank-syntax: Private macros
write-message-to-stream: Private ordinary functions