Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
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.
• Introduction | What swank-protocol is all about | |
• Systems | The systems documentation | |
• Modules | The modules documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
A low-level client for the Swank server of SLIME.
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.
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)
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.
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.
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)
Copyright (c) 2015 Fernando Borretti
Licensed under the MIT License.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The swank-protocol system |
Fernando Borretti <eudoxiahp@gmail.com>
Fernando Borretti <eudoxiahp@gmail.com>
(:git "git@github.com:eudoxia0/swank-protocol.git")
MIT
A low-level Swank client.
# 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
swank-protocol.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
• The swank-protocol/src module |
swank-protocol (system)
src/
swank-protocol.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The swank-protocol.asd file | ||
• The swank-protocol/src/swank-protocol.lisp file |
Next: The swank-protocol/src/swank-protocol․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
swank-protocol.asd
swank-protocol (system)
Previous: The swank-protocol․asd file, Up: Lisp files [Contents][Index]
src (module)
src/swank-protocol.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The swank-protocol package |
Low-level implementation of a client for the Swank protocol.
swank-protocol.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported functions | ||
• Exported generic functions | ||
• Exported classes |
Next: Exported generic functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
(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.
swank-protocol.lisp (file)
Create a connection to a remote Swank server.
swank-protocol.lisp (file)
t if there’s a message in the connection waiting to be read, nil otherwise.
swank-protocol.lisp (file)
swank-protocol.lisp (file)
Read an arbitrary message from a connection.
swank-protocol.lisp (file)
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.
swank-protocol.lisp (file)
Request that Swank provide connection information.
swank-protocol.lisp (file)
Request that Swank create a new REPL.
swank-protocol.lisp (file)
Request that Swank initiate presentations.
swank-protocol.lisp (file)
Send a string to the server’s standard input.
swank-protocol.lisp (file)
Send a string to the server’s standard input with a newline at the end.
swank-protocol.lisp (file)
Invoke a restart.
swank-protocol.lisp (file)
Request that Swank evaluate a string of code in the REPL.
swank-protocol.lisp (file)
Request that the Swank server load contrib modules. ‘requirements‘ must be a list of symbols, e.g. ’(swank-repl swank-media).
swank-protocol.lisp (file)
Leave the debugger.
swank-protocol.lisp (file)
Send a message string to a Swank connection.
swank-protocol.lisp (file)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Connect to the remote server. Returns t.
swank-protocol.lisp (file)
The host to connect to.
swank-protocol.lisp (file)
Whether or not to log connection requests.
swank-protocol.lisp (file)
The stream to log to.
swank-protocol.lisp (file)
The name of the connection’s package.
swank-protocol.lisp (file)
The port to connect to.
swank-protocol.lisp (file)
A number that is increased and sent along with every request.
swank-protocol.lisp (file)
The current thread.
swank-protocol.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
A connection to a remote Lisp.
swank-protocol.lisp (file)
standard-object (class)
The host to connect to.
string
:hostname
connection-hostname (generic function)
The port to connect to.
integer
:port
connection-port (generic function)
The usocket socket.
usocket:stream-usocket
connection-socket (generic function)
(setf connection-socket) (generic function)
A number that is increased and sent along with every request.
integer
0
connection-request-count (generic function)
(setf connection-request-count) (generic function)
Counter of the number of times read is called in the server’s REPL.
integer
0
connection-read-count (generic function)
(setf connection-read-count) (generic function)
The name of the connection’s package.
string
"common-lisp-user"
connection-package (generic function)
(setf connection-package) (generic function)
The current thread.
t
connection-thread (generic function)
(setf connection-thread) (generic function)
Whether or not to log connection requests.
boolean
:logp
connection-log-p (generic function)
(setf connection-log-p) (generic function)
The stream to log to.
stream
:logging-stream
*error-output*
connection-logging-stream (generic function)
(setf connection-logging-stream) (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal macros | ||
• Internal functions | ||
• Internal generic functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
swank-protocol.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
Decode a string representing a 0-padded 16-bit hex string to an integer.
swank-protocol.lisp (file)
Encode an integer to a 0-padded 16-bit hexadecimal string.
swank-protocol.lisp (file)
Log a message.
swank-protocol.lisp (file)
Read a string from a string.
Parses length information to determine how many characters to read.
swank-protocol.lisp (file)
Write a string to a stream, prefixing it with length information for Swank.
swank-protocol.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
Counter of the number of times read is called in the server’s REPL.
swank-protocol.lisp (file)
The usocket socket.
swank-protocol.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L M S |
---|
Jump to: | F L M S |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
C D E F G L M R S W |
---|
Jump to: | (
C D E F G L M R S W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | H L P R S T |
---|
Jump to: | H L P R S T |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C P S |
---|
Jump to: | C P S |
---|