This is the swank-protocol Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Nov 06 15:00:14 2023 GMT+0.
The main system appears first, followed by any subsystem dependency.
swank-protocolA low-level Swank client.
Fernando Borretti <eudoxiahp@gmail.com>
Fernando Borretti <eudoxiahp@gmail.com>
(GIT git@github.com:eudoxia0/swank-protocol.git)
MIT
# 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.
0.1
usocket (system).
swank (system).
babel (system)., for feature (:not (:or :sbcl :allegro :ccl :clisp))
src (module).
Modules are listed depth-first from the system components tree.
swank-protocol/srcswank-protocol (system).
swank-protocol.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
swank-protocol/swank-protocol.asdswank-protocol (system).
swank-protocol/src/swank-protocol.lispsrc (module).
connect (method).
connection (class).
connection-hostname (reader method).
connection-log-p (reader method).
(setf connection-log-p) (writer method).
connection-logging-stream (reader method).
(setf connection-logging-stream) (writer method).
connection-package (reader method).
(setf connection-package) (writer method).
connection-port (reader method).
connection-request-count (reader method).
(setf connection-request-count) (writer method).
connection-thread (reader method).
(setf connection-thread) (writer 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).
connection-read-count (reader method).
(setf connection-read-count) (writer method).
connection-socket (reader method).
(setf connection-socket) (writer method).
decode-integer (function).
encode-integer (function).
log-message (function).
octets-to-string (function).
read-message-from-stream (function).
string-to-octets (function).
with-swank-syntax (macro).
write-message-to-stream (function).
Packages are listed by definition order.
swank-protocolLow-level implementation of a client for the Swank protocol.
common-lisp.
connect (generic function).
connection (class).
connection-hostname (generic reader).
connection-log-p (generic reader).
(setf connection-log-p) (generic writer).
connection-logging-stream (generic reader).
(setf connection-logging-stream) (generic writer).
connection-package (generic reader).
(setf connection-package) (generic writer).
connection-port (generic reader).
connection-request-count (generic reader).
(setf connection-request-count) (generic writer).
connection-thread (generic reader).
(setf connection-thread) (generic writer).
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).
connection-read-count (generic reader).
(setf connection-read-count) (generic writer).
connection-socket (generic reader).
(setf connection-socket) (generic writer).
decode-integer (function).
encode-integer (function).
log-message (function).
octets-to-string (function).
read-message-from-stream (function).
string-to-octets (function).
with-swank-syntax (macro).
write-message-to-stream (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
(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.
Create a connection to a remote Swank server.
t if there’s a message in the connection waiting to be read, nil otherwise.
Read an arbitrary message from a 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.
Request that Swank provide connection information.
Request that Swank create a new REPL.
Request that Swank initiate presentations.
Send a string to the server’s standard input.
Send a string to the server’s standard input with a newline at the end.
Invoke a restart.
Request that Swank evaluate a string of code in the REPL.
Request that the Swank server load contrib modules. ‘requirements‘ must be a list of symbols, e.g. ’(swank-repl swank-media).
Leave the debugger.
Send a message string to a Swank connection.
connection)) ¶Connect to the remote server. Returns t.
connection)) ¶The host to connect to.
connection)) ¶connection)) ¶Whether or not to log connection requests.
logp.
connection)) ¶connection)) ¶The stream to log to.
connection)) ¶connection)) ¶The name of the connection’s package.
connection)) ¶The port to connect to.
port.
connection)) ¶connection)) ¶A number that is increased and sent along with every request.
connection)) ¶connection)) ¶The current thread.
A connection to a remote Lisp.
connect.
connection-hostname.
(setf connection-log-p).
connection-log-p.
(setf connection-logging-stream).
connection-logging-stream.
(setf connection-package).
connection-package.
connection-port.
(setf connection-read-count).
connection-read-count.
(setf connection-request-count).
connection-request-count.
(setf connection-socket).
connection-socket.
(setf connection-thread).
connection-thread.
The host to connect to.
string
:hostname
This slot is read-only.
The port to connect to.
integer
:port
This slot is read-only.
The usocket socket.
usocket:stream-usocket
A number that is increased and sent along with every request.
integer
0
Counter of the number of times read is called in the server’s REPL.
integer
0
The name of the connection’s package.
common-lisp.
string
"common-lisp-user"
The current thread.
t
Whether or not to log connection requests.
boolean
:logp
The stream to log to.
stream
*error-output*
:logging-stream
Decode a string representing a 0-padded 16-bit hex string to an integer.
Encode an integer to a 0-padded 16-bit hexadecimal string.
Log a message.
Read a string from a string.
Parses length information to determine how many characters to read.
Write a string to a stream, prefixing it with length information for Swank.
connection)) ¶connection)) ¶Counter of the number of times read is called in the server’s REPL.
connection)) ¶connection)) ¶The usocket socket.
| Jump to: | (
C D E F G L M O R S W |
|---|
| Jump to: | (
C D E F G L M O R S W |
|---|
| Jump to: | H L P R S T |
|---|
| Jump to: | H L P R S T |
|---|
| Jump to: | C F M P S |
|---|
| Jump to: | C F M P S |
|---|